From 57f84dcef5b1529bd76cbfa32bd69fa1ad8727a4 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 6 Oct 2026 09:39:45 +0530 Subject: [PATCH 001/169] lb embed split --- .idea/.gitignore | 3 + .idea/developer-docs.iml | 9 + .idea/misc.xml | 6 + .idea/modules.xml | 8 + .idea/vcs.xml | 6 + modules/ROOT/pages/api-changelog.adoc | 10 +- modules/ROOT/pages/common/nav-embedding.adoc | 3 + .../pages/common/nav-in-product-help.adoc | 3 + .../pages/customize-liveboard-filters.adoc | 134 +++++ .../pages/customize-liveboard-layout.adoc | 246 +++++++++ modules/ROOT/pages/data-security.adoc | 2 +- modules/ROOT/pages/embed-pinboard.adoc | 501 +----------------- modules/ROOT/pages/filters_overview.adoc | 2 +- .../ROOT/pages/liveboard-data-downloads.adoc | 172 ++++++ .../ROOT/pages/whats-new-prev-history.adoc | 10 +- modules/ROOT/pages/whats-new.adoc | 10 +- src/configs/doc-configs.js | 1 + 17 files changed, 618 insertions(+), 508 deletions(-) create mode 100644 .idea/.gitignore create mode 100644 .idea/developer-docs.iml create mode 100644 .idea/misc.xml create mode 100644 .idea/modules.xml create mode 100644 .idea/vcs.xml create mode 100644 modules/ROOT/pages/customize-liveboard-filters.adoc create mode 100644 modules/ROOT/pages/customize-liveboard-layout.adoc create mode 100644 modules/ROOT/pages/liveboard-data-downloads.adoc diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100644 index 000000000..26d33521a --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,3 @@ +# Default ignored files +/shelf/ +/workspace.xml diff --git a/.idea/developer-docs.iml b/.idea/developer-docs.iml new file mode 100644 index 000000000..d6ebd4805 --- /dev/null +++ b/.idea/developer-docs.iml @@ -0,0 +1,9 @@ + + + + + + + + + \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 000000000..639900d13 --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 000000000..aff6e430d --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 000000000..35eb1ddfb --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 95e141cfb..407da9247 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -263,11 +263,11 @@ The SDK includes the following new features and enhancements in Liveboard embedd `liveboardGutter` embed config property:: A new `liveboardGutter` property is available on `LiveboardViewConfig`. Use this property to set the gutter spacing between tiles on an embedded Liveboard. -For more information, see xref:embed-pinboard.adoc#liveboard-gutter[Set Liveboard tile gutter] +For more information, see #xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter]# 12-column layout for Liveboard tile positioning:: A new embed config property is available on `LiveboardViewConfig` to always use a 12-column grid layout for Liveboard tile positioning. When enabled, tile placement and sizing follow a fixed 12-column grid regardless of the Liveboard's default layout settings. -For more information, see xref:embed-pinboard.adoc#force-12col-layout[12-column layout in embedded Liveboards] +For more information, see #xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards]# New host events for the Liveboard edit page:: * `HostEvent.OpenAddFilterModal` + @@ -316,7 +316,7 @@ Enables compact header layout in embedded Liveboards. * `coverAndFilterOptionInPDF` + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * `isLiveboardMasterpiecesEnabled` + -Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. +Enables the #xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping]# feature. * `isEnhancedFilterInteractivityEnabled` + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. @@ -387,7 +387,7 @@ Trigger a manual cache refresh from the host application. * `Action.RefreshLiveboardBrowserCache` + Action ID to show or hide the cache refresh button. -For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. +For more information, see #xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh]#. |[tag greenBackground]#NEW# a| [discrete] @@ -1731,7 +1731,7 @@ For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources |[tag greenBackground]#NEW#| For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. -For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. +For more information, see #xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]#. |[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index e19841f8a..35d18dcd2 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -20,6 +20,9 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-spotter-agent[Embed Spotter without ThoughtSpot UI] * Embed charts and Liveboards ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +*** link:{{navprefix}}/customize-liveboard-layout[Customize Liveboard layout and UI] +*** link:{{navprefix}}/customize-liveboard-filters[Customize Liveboard filters] +*** link:{{navprefix}}/liveboard-data-downloads[Liveboard data refresh and downloads] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index e2dfb49e3..a7173bacf 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -39,6 +39,9 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-spotter-agent[Embed Spotter AI without ThoughtSpot UI] * link:{{navprefix}}/embed-liveboard[Embed live analytics] ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +*** link:{{navprefix}}/customize-liveboard-layout[Customize Liveboard layout and UI] +*** link:{{navprefix}}/customize-liveboard-filters[Customize Liveboard filters] +*** link:{{navprefix}}/liveboard-data-downloads[Liveboard data refresh and downloads] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc new file mode 100644 index 000000000..27d7b95a4 --- /dev/null +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -0,0 +1,134 @@ += Customize Liveboard filters +:toc: true +:toclevels: 2 + +:page-title: Customize Liveboard filters +:page-pageid: customize-liveboard-filters +:page-description: Use the Visual Embed SDK to control filter visibility, apply filters at load time, scope filters to tabs and groups, and update filters on an embedded Liveboard. + +To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. #The Visual Embed SDK provides properties and host events to control which filter chips are visible, apply filters at load time, scope filters to specific tabs or groups, and update filters programmatically.# + +#Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component.# + +[#filter-visibility] +== Customizing filter visibility +To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. #For more information, see xref:customize-liveboard-layout.adoc#show-hide-ui-elements[Show/hide large UI elements].# + +If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, + hideIrrelevantChipsInLiveboardTabs: true, +}); +---- + +When `hideIrrelevantChipsInLiveboardTabs` is `true`: + +* Filter chips backed by data sources that are *not used by any visualization on the active tab* are hidden automatically when the user switches tabs. +* A *Show irrelevant filters* toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips. +* When the user clicks *Show irrelevant filters*, a complementary *Hide irrelevant filters* button appears to restore the filtered view. + +#For more information about the compact header, see xref:customize-liveboard-layout.adoc#compact-header[Enable compact Liveboard header].# + +[#masked-filter-chips] +=== #Masked filter chips# +#If a Liveboard includes filters on columns that a user cannot access because of column-level security, the filter values are masked for that user. Use the `showMaskedFilterChip` property to control whether these masked filter chips are visible:# + +* #`true`: the filter chips for inaccessible columns are displayed as masked.# +* #`false`: the filter chips for inaccessible columns are hidden.# + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + showMaskedFilterChip: true, +}); +---- + +#The `showMaskedFilterChip` property is also available in full application embedding. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards].# + +[#filters-at-load] +== #Apply filters at load time# +By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. + +[IMPORTANT] +==== +Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced +limit are silently dropped without an error or warning. For more information, see +xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. +==== + +[#contextual-liveboard-filtering] +== Contextual filtering in Liveboards [earlyAccess eaBackground]#Early Access# +Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parameters can be scoped at three levels: + +* *Liveboard*: applies to all visualizations on the Liveboard. +* *Tab*: applies only to visualizations on a specific tab. +* *Group*: applies only to visualizations in a specific group on a tab. + +With contextual filtering, you can add the same filter at more than one level on a Liveboard, but not at a level directly below it in the same hierarchy. For example: + +* If a `Region` filter is set at the Liveboard level, it cannot be added again on any tab or group on that Liveboard. +* If a `City` filter is set on Tab 1, it cannot be added to a group on Tab 1. However, it can be added to a group on another tab, such as Tab 2, because that group is not in the Tab 1 hierarchy. + +[NOTE] +==== +Contextual filtering in Liveboards is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, set `isScopedLiveboardFilteringEnabled` to `true`. +==== + + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", + isScopedLiveboardFilteringEnabled: true, +}); +---- + +The `isScopedLiveboardFilteringEnabled` property is also available in `AppViewConfig` for full application embedding. + +To get the groups on a Liveboard, use `HostEvent.GetGroups`. To scope a filter or parameter update to a specific tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`: + +[source,javascript] +---- +liveboardEmbed.trigger(HostEvent.UpdateFilters, { + filters: [ + { + column: 'Region', + oper: 'IN', + values: ['West'], + applicability: { + level: 'GROUP', + targetId: '{group-id}', + }, + }, + ], +}); +---- + +To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and `EmbedEvent.ParameterChanged`. Starting with SDK 1.53.0, both events include an optional `applicability` field in their response payload that indicates the scope of the change. + +For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. + +[#update-filters] +== Updating filters +Use the following host events in the Visual Embed SDK to update filters: + +* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatefilters[`HostEvent.UpdateFilters`] to update Liveboard filters +* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateruntimefilters[`HostEvent.UpdateRuntimeFilters`] to update runtime filters +* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatecrossfilter[`HostEvent.UpdateCrossFilter`] + +For more information and examples, see xref:filters_overview.adoc[Filter types and application layers]. + +== #Related information# +* #xref:embed-pinboard.adoc[Embed a Liveboard]# +* #xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# +* #xref:liveboard-data-downloads.adoc[Liveboard data refresh and downloads]# +* #xref:runtime-filters.adoc[Runtime filters]# +* #xref:runtime-parameters.adoc[Runtime Parameter overrides]# diff --git a/modules/ROOT/pages/customize-liveboard-layout.adoc b/modules/ROOT/pages/customize-liveboard-layout.adoc new file mode 100644 index 000000000..adc1a7835 --- /dev/null +++ b/modules/ROOT/pages/customize-liveboard-layout.adoc @@ -0,0 +1,246 @@ += Customize Liveboard layout and UI +:toc: true +:toclevels: 2 + +:page-title: Customize Liveboard layout and UI +:page-pageid: customize-liveboard-layout +:page-description: Use the LiveboardViewConfig properties in the Visual Embed SDK to customize the header, tabs, tiles, and layout of an embedded Liveboard. + +#The xref:LiveboardViewConfig.adoc[LiveboardViewConfig] object includes several properties that control the look and layout of an embedded Liveboard, such as the header, tabs, tile spacing, responsive layout, and grouping and styling of tiles.# + +#Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component.# + +[#show-hide-ui-elements] +== Show/hide large UI elements +Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderSticky`, `showLiveboardTitle`, and `showLiveboardDescription` control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether `true` enables or disables the particular feature. + +//Along with xref:Action.adoc[Actions], there is very fine-grained control of the display of the `LiveboardEmbed` component, which can vary for each user or content object displayed depending on the desires of the app development team. + +[.widthAuto] +image::./images/liveboard_view_config_callouts_2.png[LiveboardViewConfig parameters] + +The `hideLiveboardHeader` property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only" use cases or for rebuilding your own menus and buttons using xref:embed-events.adoc[HostEvents]. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed', { + ... // other liveboard view config + hideLiveboardHeader:true, +}); +---- + +#When the header is hidden, you can trigger filter interactions programmatically using host events. For more information, see xref:customize-liveboard-filters.adoc#update-filters[Updating filters].# + +The following constructor disables the __sticky header__ and shows the Liveboard title, which is hidden by default: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + isLiveboardHeaderSticky : false, + showLiveboardTitle: true, + liveboardId: '<%=liveboardGUID%>', +}); +---- + +[NOTE] +==== +When `fullHeight` is set to `true`, the SDK ignores the `isLiveboardHeaderSticky:true` setting, and the Liveboard header is not sticky. +==== + +[#compact-header] +== Enable compact Liveboard header +By default, embedded Liveboards display a full-height header bar that contains the Liveboard title, description, filter chips, tab navigation, and action menu. You can switch to a more space-efficient layout by enabling the compact header. + +The compact header reduces the vertical footprint of the header area, integrates tabs and filter chips into a single condensed row, and moves the *Edit* button into the header's overflow action menu. + +To enable the compact header, set `isLiveboardCompactHeaderEnabled` to `true` in the `LiveboardViewConfig` object. Note that the `isLiveboardCompactHeaderEnabled` attribute is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, +}); +---- + +When `isLiveboardCompactHeaderEnabled` is `true`, the following UI changes apply compared to the standard header: + +[width="100%",cols="2,4",options="header"] +|==== +|Area |Change +|Header height |The header renders in a condensed, shorter height to maximize the visible content area. +|Edit button |The *Edit* button is removed from the top-level header and is accessible from the header overflow (*...*) menu. +|Filter chips |Filter chips are rendered inside the compact header's integrated filter row, replacing the separate floating filter panel. +|Tabs |The tab bar is incorporated into the compact header row, rather than appearing as a separate element below the header. +|Sticky scroll behavior |The scroll threshold at which the sticky header attaches to the top of the viewport is recalculated for the compact header's shorter height. This may affect the scroll position at which the header becomes sticky compared to the standard header. +|| +|==== + +=== Hiding the Liveboard title in compact header +In the compact header, you can hide the Liveboard title by setting `showLiveboardTitle` to `false` in the `LiveboardViewConfig` object: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, + showLiveboardTitle: false, +}); +---- + +#To hide filter chips that are not relevant to the active tab in the compact header, see xref:customize-liveboard-filters.adoc#filter-visibility[Customizing filter visibility].# + +[#liveboard-tabs] +== Customize Liveboard tabs +By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the `activeTabId` property in the Visual Embed SDK as shown in the example here: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", + activeTabId: "05406350-44ce-488e-abc5-5e8cdd65cf3c", +}); +---- + +[NOTE] +==== +The `activeTabId` property is available only in the `LiveboardEmbed` package and is not supported in the full application embed mode. +==== + +[#visible-tabs-vizs] +== Reduce visible tabs and visualizations +`visibleVizs` and `visibleTabs` allow you to limit the experience for certain users on a Liveboard with many more elements. + +For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). + +[#liveboard-gutter] +== Set Liveboard tile gutter + +The `liveboardGutter` property lets you control the spacing between Liveboard tiles and groups, and the grid's outer layout padding, directly from your embed configuration. The value you set overrides the Liveboard's saved styling setting. + +Use this property when you need to enforce consistent tile spacing across embedded Liveboards, regardless of how individual Liveboards are styled in ThoughtSpot. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '<%=liveboardGUID%>', + liveboardGutter: 16, +}); +liveboardEmbed.render(); +---- + +The following rules apply to the `liveboardGutter` value: + +* Accepts non-negative integers (0 or greater). +* A value of `0` removes all gutter space between tiles and the grid's outer layout padding. +* Negative numbers, decimal values, and non-numeric strings are ignored. The Liveboard falls back to its saved styling value. + +[NOTE] +==== +`liveboardGutter` controls the spacing between tiles and groups, not the spacing within a group. + +The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#lb-header-margin[Liveboard CSS variables]. +==== + +[#noteTiles] +== Add Note tiles +You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. + +* Only users with edit access to a Liveboard can add a Note tile. +* Users require `Can upload data` privilege to upload an image to the note tile. +* If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. + +[#liveboard-breakpoints] +== Redefine Liveboard breakpoint widths +The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. +The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards. + +These breakpoint widths are customizable for the embedded customers. Contact ThoughtSpot support for assistance with customization. + +[#force-12col-layout] +== 12-column layout in embedded Liveboards +By default, embedded Liveboards use a responsive layout that collapses from 12 columns to +2 columns at container widths of 1024px or less, and to a single column at 630px or less. + +Use the `isLiveboardAlwaysOn12ColLayout` property in the SDK to prevent this collapse and keep the +12-column layout at all container widths. + +To force the 12-column layout, set `isLiveboardAlwaysOn12ColLayout` to `true` in the +`LiveboardViewConfig` object: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '<%=liveboardGUID%>', + isLiveboardAlwaysOn12ColLayout: true, +}); +---- + +The property is also supported on `AppEmbed` via `AppViewConfig`: + +[source,JavaScript] +---- +const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + isLiveboardAlwaysOn12ColLayout: true, +}); +---- + +[NOTE] +==== +The CSS variables `--ts-var-liveboard-dual-column-breakpoint` and +`--ts-var-liveboard-single-column-breakpoint` control the pixel thresholds at which the +responsive layout collapses. +Use `isLiveboardAlwaysOn12ColLayout: true` when you want to prevent layout collapse +entirely, rather than adjust the breakpoint thresholds. +For more information about the CSS layout variables available for Liveboard layout control, +see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. +==== + +[#liveboard-grouping-styling] +== Liveboard grouping and styling + +You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. +To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. +Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. + +* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. +* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. +* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. ++ +[.bordered] +[.widthAuto] +-- +image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] +-- ++ +To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. + +For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. + +For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. + +== #Related information# +* #xref:embed-pinboard.adoc[Embed a Liveboard]# +* #xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# +* #xref:liveboard-data-downloads.adoc[Liveboard data refresh and downloads]# +* #xref:LiveboardViewConfig.adoc[LiveboardViewConfig]# diff --git a/modules/ROOT/pages/data-security.adoc b/modules/ROOT/pages/data-security.adoc index e8f25e89b..d1d997f7c 100644 --- a/modules/ROOT/pages/data-security.adoc +++ b/modules/ROOT/pages/data-security.adoc @@ -34,6 +34,6 @@ Starting with ThoughtSpot Cloud 26.10.0.cl, Liveboards that include columns rest * Filter chips from columns that the user cannot access are masked instead of blocking the Liveboard. Only one masked filter chip is shown, at the end of the filter bar, to indicate that one or more filters are inaccessible. For example, if five filters are inaccessible, the Liveboard still shows a single masked filter chip. * Scheduled Liveboard deliveries apply CSR separately for each recipient. -To control whether masked filter chips are visible in an embedded Liveboard, use the `showMaskedFilterChip` SDK property. For more information, see xref:embed-pinboard.adoc#masked-filter-chips[Masked filter chips]. +To control whether masked filter chips are visible in an embedded Liveboard, use the `showMaskedFilterChip` SDK property. For more information, see #xref:customize-liveboard-filters.adoc#masked-filter-chips[Masked filter chips]#. For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards, window=_blank]. diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index bfe4aabb6..54067ac77 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -67,7 +67,7 @@ For more information about the Liveboard embed object, classes, methods, interfa The `LiveboardEmbed` component includes the `xref:LiveboardViewConfig.adoc[LiveboardViewConfig]` object. This object provides various attributes and properties to xref:css-customization.adoc[customize the look and feel of the Liveboard page], xref:embed-actions.adoc[control the visibility of menu actions] and features, and xref:embed-events.adoc[manage interactions between the host and embedded app]. -The most common customization is controlling the visibility of menu items in the embedded view by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of xref:Action.adoc[Action] IDs. For information about the other frequently used properties, see xref:embed-pinboard.adoc#common-customizations[common customization options]. +The most common customization is controlling the visibility of menu items in the embedded view by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of xref:Action.adoc[Action] IDs. For information about the other frequently used properties, see #<>#. == Register, handle, and trigger events @@ -106,505 +106,24 @@ image::./images/embed-lb.png[Liveboard embed] == Common customization options The *xref:LiveboardViewConfig.adoc[LiveboardViewConfig]* object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide the header, and more. -=== Show/hide large UI elements -Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderSticky`, `showLiveboardTitle`, and `showLiveboardDescription` control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether `true` enables or disables the particular feature. - -//Along with xref:Action.adoc[Actions], there is very fine-grained control of the display of the `LiveboardEmbed` component, which can vary for each user or content object displayed depending on the desires of the app development team. - -[.widthAuto] -image::./images/liveboard_view_config_callouts_2.png[LiveboardViewConfig parameters] - -The `hideLiveboardHeader` property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only" use cases or for rebuilding your own menus and buttons using xref:embed-events.adoc[HostEvents]. - -The following constructor disables the __sticky header__ and shows the Liveboard title, which is hidden by default: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - isLiveboardHeaderSticky : false, - showLiveboardTitle: true, - liveboardId: '<%=liveboardGUID%>', -}); ----- - -[NOTE] -==== -When `fullHeight` is set to `true`, the SDK ignores the `isLiveboardHeaderSticky:true` setting, and the Liveboard header is not sticky. -==== - -[#compact-header] -=== Enable compact Liveboard header -By default, embedded Liveboards display a full-height header bar that contains the Liveboard title, description, filter chips, tab navigation, and action menu. You can switch to a more space-efficient layout by enabling the compact header. - -The compact header reduces the vertical footprint of the header area, integrates tabs and filter chips into a single condensed row, and moves the *Edit* button into the header's overflow action menu. - -To enable the compact header, set `isLiveboardCompactHeaderEnabled` to `true` in the `LiveboardViewConfig` object. Note that the `isLiveboardCompactHeaderEnabled` attribute is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - isLiveboardCompactHeaderEnabled: true, -}); ----- - -When `isLiveboardCompactHeaderEnabled` is `true`, the following UI changes apply compared to the standard header: +#The customization options are grouped into the following pages:# [width="100%",cols="2,4",options="header"] |==== -|Area |Change -|Header height |The header renders in a condensed, shorter height to maximize the visible content area. -|Edit button |The *Edit* button is removed from the top-level header and is accessible from the header overflow (*...*) menu. -|Filter chips |Filter chips are rendered inside the compact header's integrated filter row, replacing the separate floating filter panel. -|Tabs |The tab bar is incorporated into the compact header row, rather than appearing as a separate element below the header. -|Sticky scroll behavior |The scroll threshold at which the sticky header attaches to the top of the viewport is recalculated for the compact header's shorter height. This may affect the scroll position at which the header becomes sticky compared to the standard header. -|| -|==== - -==== Hiding the Liveboard title in compact header -In the compact header, you can hide the Liveboard title by setting `showLiveboardTitle` to `false` in the `LiveboardViewConfig` object: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - isLiveboardCompactHeaderEnabled: true, - showLiveboardTitle: false, -}); ----- - - -[#liveboard-gutter] -=== Set Liveboard tile gutter - -The `liveboardGutter` property lets you control the spacing between Liveboard tiles and groups, and the grid's outer layout padding, directly from your embed configuration. The value you set overrides the Liveboard's saved styling setting. - -Use this property when you need to enforce consistent tile spacing across embedded Liveboards, regardless of how individual Liveboards are styled in ThoughtSpot. - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '<%=liveboardGUID%>', - liveboardGutter: 16, -}); -liveboardEmbed.render(); ----- - -The following rules apply to the `liveboardGutter` value: - -* Accepts non-negative integers (0 or greater). -* A value of `0` removes all gutter space between tiles and the grid's outer layout padding. -* Negative numbers, decimal values, and non-numeric strings are ignored. The Liveboard falls back to its saved styling value. - -[NOTE] -==== -`liveboardGutter` controls the spacing between tiles and groups, not the spacing within a group. - -The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#lb-header-margin[Liveboard CSS variables]. -==== - -=== Customize Liveboard tabs -By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the `activeTabId` property in the Visual Embed SDK as shown in the example here: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", - activeTabId: "05406350-44ce-488e-abc5-5e8cdd65cf3c", -}); ----- - -[NOTE] -==== -The `activeTabId` property is available only in the `LiveboardEmbed` package and is not supported in the full application embed mode. -==== - -=== Reduce visible tabs and visualizations -`visibleVizs` and `visibleTabs` allow you to limit the experience for certain users on a Liveboard with many more elements. - -For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). - -=== Customizing filter visibility -To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. - -[source,JavaScript] ----- -const embed = new LiveboardEmbed('#embed', { - ... // other liveboard view config - hideLiveboardHeader:true, -}); ----- - -If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - isLiveboardCompactHeaderEnabled: true, - hideIrrelevantChipsInLiveboardTabs: true, -}); ----- - -When `hideIrrelevantChipsInLiveboardTabs` is `true`: - -* Filter chips backed by data sources that are *not used by any visualization on the active tab* are hidden automatically when the user switches tabs. -* A *Show irrelevant filters* toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips. -* When the user clicks *Show irrelevant filters*, a complementary *Hide irrelevant filters* button appears to restore the filtered view. - -[#masked-filter-chips] -==== #Masked filter chips# -#If a Liveboard includes filters on columns that a user cannot access because of column-level security, the filter values are masked for that user. Use the `showMaskedFilterChip` property to control whether these masked filter chips are visible:# - -* #`true`: the filter chips for inaccessible columns are displayed as masked.# -* #`false`: the filter chips for inaccessible columns are hidden.# - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - showMaskedFilterChip: true, -}); ----- - -#The `showMaskedFilterChip` property is also available in full application embedding. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards].# - -[#noteTiles] -=== Add Note tiles -You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. - -* Only users with edit access to a Liveboard can add a Note tile. -* Users require `Can upload data` privilege to upload an image to the note tile. -* If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. - -=== Redefine Liveboard breakpoint widths -The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. -The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards. - -These breakpoint widths are customizable for the embedded customers. Contact ThoughtSpot support for assistance with customization. - -[#force-12col-layout] -=== 12-column layout in embedded Liveboards -By default, embedded Liveboards use a responsive layout that collapses from 12 columns to -2 columns at container widths of 1024px or less, and to a single column at 630px or less. - -Use the `isLiveboardAlwaysOn12ColLayout` property in the SDK to prevent this collapse and keep the -12-column layout at all container widths. - -To force the 12-column layout, set `isLiveboardAlwaysOn12ColLayout` to `true` in the -`LiveboardViewConfig` object: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '<%=liveboardGUID%>', - isLiveboardAlwaysOn12ColLayout: true, -}); ----- - -The property is also supported on `AppEmbed` via `AppViewConfig`: - -[source,JavaScript] ----- -const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - isLiveboardAlwaysOn12ColLayout: true, -}); ----- - -[NOTE] -==== -The CSS variables `--ts-var-liveboard-dual-column-breakpoint` and -`--ts-var-liveboard-single-column-breakpoint` control the pixel thresholds at which the -responsive layout collapses. -Use `isLiveboardAlwaysOn12ColLayout: true` when you want to prevent layout collapse -entirely, rather than adjust the breakpoint thresholds. -For more information about the CSS layout variables available for Liveboard layout control, -see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. -==== - -[#liveboard-data-cache] -=== Liveboard browser cache and refresh -ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. - -[NOTE] -==== -The CSS variables `--ts-var-liveboard-dual-column-breakpoint` and -`--ts-var-liveboard-single-column-breakpoint` control the pixel thresholds at which the -responsive layout collapses. -Use `isLiveboardAlwaysOn12ColLayout: true` when you want to prevent layout collapse -entirely, rather than adjust the breakpoint thresholds. -For more information about the CSS layout variables available for Liveboard layout control, -see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. -==== - -[#liveboard-data-cache] -=== Liveboard browser cache and refresh -ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. - -To enable Liveboard data caching, set `enableLiveboardDataCache` to `true`. - -[source,javascript] ----- -const liveboardEmbed = new LiveboardEmbed('#embed-container', { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '', // - enableLiveboardDataCache: true, // -}); ----- - -When data caching is enabled, the refresh icon appears in the Liveboard header. Users can click this button to clear the browser cache and fetch fresh data. - -[.bordered] -[.widthAuto] --- -image::./images/liveboard-refresh.png[Liveboard refresh] --- - -The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow. - -[width="100%",cols="2,4"] -|==== -|ID | Description - -|xref:Action.adoc#_refreshliveboardbrowsercache[Action.RefreshLiveboardBrowserCache] -|Action ID to show, hide, or disable the *Refresh* button in the Liveboard header. - -|xref:EmbedEvent.adoc#_refreshliveboardbrowsercache[EmbedEvent.RefreshLiveboardBrowserCache] -|Emitted when a user clicks the *Refresh* button in the Liveboard header. - -|xref:HostEvent.adoc#_refreshliveboardbrowsercache[HostEvent.RefreshLiveboardBrowserCache] -|Triggers a browser cache refresh programmatically for all visualization containers on the embedded Liveboard. +|#Page# |#Covers# +|#xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# +|#Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling.# +|#xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# +|#Filter chip visibility, masked filter chips, filters at load time, contextual filtering at the Liveboard, tab, and group levels, and updating filters with host events.# +|#xref:liveboard-data-downloads.adoc[Liveboard data refresh and downloads]# +|#Browser data cache and refresh, PDF, XLSX, and CSV downloads, download action IDs and host events, and scheduled exports.# |==== -=== Customize filters -To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. - [IMPORTANT] ==== -Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. -When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced -limit are silently dropped without an error or warning. For more information, see -xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. +#If a Liveboard is saved with Groups in the ThoughtSpot interface, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embed configuration. Otherwise, the embedded Liveboard fails to load. For more information, see xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard grouping and styling].# ==== -[#contextual-liveboard-filtering] -==== Contextual filtering in Liveboards [earlyAccess eaBackground]#Early Access# -Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parameters can be scoped at three levels: - -* *Liveboard*: applies to all visualizations on the Liveboard. -* *Tab*: applies only to visualizations on a specific tab. -* *Group*: applies only to visualizations in a specific group on a tab. - -With contextual filtering, you can add the same filter at more than one level on a Liveboard, but not at a level directly below it in the same hierarchy. For example: - -* If a `Region` filter is set at the Liveboard level, it cannot be added again on any tab or group on that Liveboard. -* If a `City` filter is set on Tab 1, it cannot be added to a group on Tab 1. However, it can be added to a group on another tab, such as Tab 2, because that group is not in the Tab 1 hierarchy. - -[NOTE] -==== -Contextual filtering in Liveboards is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, set `isScopedLiveboardFilteringEnabled` to `true`. -==== - - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", - isScopedLiveboardFilteringEnabled: true, -}); ----- - -The `isScopedLiveboardFilteringEnabled` property is also available in `AppViewConfig` for full application embedding. - -To get the groups on a Liveboard, use `HostEvent.GetGroups`. To scope a filter or parameter update to a specific tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`: - -[source,javascript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filters: [ - { - column: 'Region', - oper: 'IN', - values: ['West'], - applicability: { - level: 'GROUP', - targetId: '{group-id}', - }, - }, - ], -}); ----- - -To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and `EmbedEvent.ParameterChanged`. Starting with SDK 1.53.0, both events include an optional `applicability` field in their response payload that indicates the scope of the change. - -For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. - -==== Updating filters -Use the following host events in the Visual Embed SDK to update filters: - -* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatefilters[`HostEvent.UpdateFilters`] to update Liveboard filters -* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateruntimefilters[`HostEvent.UpdateRuntimeFilters`] to update runtime filters -* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatecrossfilter[`HostEvent.UpdateCrossFilter`] - -For more information and examples, see xref:filters_overview.adoc[Filter types and application layers]. - -=== Liveboard download options - -Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view. - -[NOTE] -==== -Starting with ThoughtSpot Cloud version 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. -==== - -==== XLSX and CSV in Liveboard scheduled exports -To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` is set to `true`. - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - //... - isGranularXLSXCSVSchedulesEnabled: true, // enable scope selection for XLSX and CSV Liveboard scheduled jobs. -}); ----- - -==== Download actions and behavior - -[width=100%, cols="2,2,4"] -[options="header"] -|===== -| Download actions -| SDK parameter -| Action ID for show/hide control -| **Download** menu action -| Enabled by default. -a| Use the `Action.DownloadLiveboard` to show, hide, or disable the Download action in the menu. -| Continuous PDF -|`isContinuousLiveboardPDFEnabled` + -Enables or disables the continuous PDF option in Liveboard downloads -a| Use the `Action.DownloadLiveboardAsContinuousPDF` action ID to show or hide the **PDF (Continuous)** option in the **Download** modal. - -| XLSX download -| `isLiveboardXLSXCSVDownloadEnabled` + -Enables the XLSX and CSV download options in the Download modal. -a|`Action.DownloadLiveboardAsXlsx` - action ID to show or hide the XLSX option in the **Download** modal. - -| CSV download -a| `isLiveboardXLSXCSVDownloadEnabled` + -Enables the XLSX and CSV download options in the Download modal. -a|`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV option in the **Download** modal. - -| PDF cover and filter pages -| None. UI options in PDF modal only. -a| Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog. -|===== - -==== Example - -The following example enables the **PDF (Continuous)**, **XLSX**, and **CSV** options in the Liveboard **Download** modal. - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - isContinuousLiveboardPDFEnabled: true, - isLiveboardXLSXCSVDownloadEnabled: true, -}); ----- - -To hide or disable the download options, specify the following action IDs: - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - //... - hiddenActions: [ - Action.DownloadLiveboard, // Hides the Download parent action from the more options menu - Action.DownloadLiveboardAsContinuousPDF, // Hides the Continuous PDF download option from the Download modal - Action.DownloadLiveboardAsCsv, // Hides the CSV download option from the Download modal - Action.DownloadLiveboardAsXlsx // Hides the XLSX download option from the Download modal - ], - // Use either `hiddenActions` or visibleActions, not both, to avoid errors - //visibleActions: [ - //Action.DownloadLiveboard, // Shows the Download parent action in the more options menu - //Action.DownloadLiveboardAsContinuousPDF, // Shows the Continuous PDF download option - //Action.DownloadLiveboardAsCsv, // Shows the CSV download option - //Action.DownloadLiveboardAsXlsx // Shows the XLSX download option - //] -}); ----- - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - //... - disabledActions: [ - Action.DownloadLiveboard,// Disables the Download parent action in the more options menu - Action.DownloadLiveboardAsContinuousPDF, // Disables the Continuous PDF download option in the Download modal - Action.DownloadLiveboardAsCsv, // Disables the CSV download option in the Download modal - Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal - ], -}); ----- - -==== HostEvent workflow for the download actions -Use the HostEvent IDs to trigger download actions on an embedded Liveboard. - -* `HostEvent.DownloadLiveboardAsContinuousPDF` + -To open the **Download** modal with the continuous PDF download option selected. -* `HostEvent.DownloadAsPdf` + -To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of the visualization in the `vizId` key. -* `HostEvent.DownloadAsXlsx` + -To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view. -* `HostEvent.DownloadAsCsv` + -To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view. - -=== Liveboard grouping and styling - -You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. -To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. -Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. - -* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. -* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. -* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. -+ -[.bordered] -[.widthAuto] --- -image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] --- -+ -To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. - -For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. - -For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. - == Additional resources * For information about runtime overrides, see xref:runtime-filters.adoc[Runtime filters] and xref:runtime-parameters.adoc[Runtime Parameter overrides]. * For code examples, see link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/liveboard[Developer examples^]. diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index f618a328f..875c1b1cc 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -230,7 +230,7 @@ liveboardEmbed.trigger(HostEvent.UpdateFilters, { * #*Tab*: applies only to visualizations on a specific tab.# * #*Group*: applies only to visualizations in a specific group on a tab.# -#To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:embed-pinboard.adoc#scoped-liveboard-filtering[Scoped Liveboard filtering].# +#To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Scoped Liveboard filtering].# #To scope an update to a tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`. Set `level` to `TAB` or `GROUP`, and set `targetId` to the ID of the tab or group. To get the group IDs on a Liveboard, use `HostEvent.GetGroups`.# diff --git a/modules/ROOT/pages/liveboard-data-downloads.adoc b/modules/ROOT/pages/liveboard-data-downloads.adoc new file mode 100644 index 000000000..dc5697326 --- /dev/null +++ b/modules/ROOT/pages/liveboard-data-downloads.adoc @@ -0,0 +1,172 @@ += Liveboard data refresh and downloads +:toc: true +:toclevels: 2 + +:page-title: Liveboard data refresh and downloads +:page-pageid: liveboard-data-downloads +:page-description: Use the Visual Embed SDK to enable browser data caching and refresh, and to configure PDF, XLSX, and CSV downloads and scheduled exports on an embedded Liveboard. + +#The Visual Embed SDK provides properties, action IDs, and events to control how users refresh Liveboard data and download or export Liveboards from the embedded view.# + +#Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component.# + +[#liveboard-data-cache] +== Liveboard browser cache and refresh +ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. + +To enable Liveboard data caching, set `enableLiveboardDataCache` to `true`. + +[source,javascript] +---- +const liveboardEmbed = new LiveboardEmbed('#embed-container', { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '', // + enableLiveboardDataCache: true, // +}); +---- + +When data caching is enabled, the refresh icon appears in the Liveboard header. Users can click this button to clear the browser cache and fetch fresh data. + +[.bordered] +[.widthAuto] +-- +image::./images/liveboard-refresh.png[Liveboard refresh] +-- + +The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow. + +[width="100%",cols="2,4"] +|==== +|ID | Description + +|xref:Action.adoc#_refreshliveboardbrowsercache[Action.RefreshLiveboardBrowserCache] +|Action ID to show, hide, or disable the *Refresh* button in the Liveboard header. + +|xref:EmbedEvent.adoc#_refreshliveboardbrowsercache[EmbedEvent.RefreshLiveboardBrowserCache] +|Emitted when a user clicks the *Refresh* button in the Liveboard header. + +|xref:HostEvent.adoc#_refreshliveboardbrowsercache[HostEvent.RefreshLiveboardBrowserCache] +|Triggers a browser cache refresh programmatically for all visualization containers on the embedded Liveboard. +|==== + +[#liveboard-download-options] +== Liveboard download options + +Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view. + +[NOTE] +==== +Starting with ThoughtSpot Cloud version 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. +==== + +=== Download actions and behavior + +[width=100%, cols="2,2,4"] +[options="header"] +|===== +| Download actions +| SDK parameter +| Action ID for show/hide control +| **Download** menu action +| Enabled by default. +a| Use the `Action.DownloadLiveboard` to show, hide, or disable the Download action in the menu. +| Continuous PDF +|`isContinuousLiveboardPDFEnabled` + +Enables or disables the continuous PDF option in Liveboard downloads +a| Use the `Action.DownloadLiveboardAsContinuousPDF` action ID to show or hide the **PDF (Continuous)** option in the **Download** modal. + +| XLSX download +| `isLiveboardXLSXCSVDownloadEnabled` + +Enables the XLSX and CSV download options in the Download modal. +a|`Action.DownloadLiveboardAsXlsx` - action ID to show or hide the XLSX option in the **Download** modal. + +| CSV download +a| `isLiveboardXLSXCSVDownloadEnabled` + +Enables the XLSX and CSV download options in the Download modal. +a|`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV option in the **Download** modal. + +| PDF cover and filter pages +| None. UI options in PDF modal only. +a| Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog. +|===== + +=== Example + +The following example enables the **PDF (Continuous)**, **XLSX**, and **CSV** options in the Liveboard **Download** modal. + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + isContinuousLiveboardPDFEnabled: true, + isLiveboardXLSXCSVDownloadEnabled: true, +}); +---- + +To hide or disable the download options, specify the following action IDs: + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + hiddenActions: [ + Action.DownloadLiveboard, // Hides the Download parent action from the more options menu + Action.DownloadLiveboardAsContinuousPDF, // Hides the Continuous PDF download option from the Download modal + Action.DownloadLiveboardAsCsv, // Hides the CSV download option from the Download modal + Action.DownloadLiveboardAsXlsx // Hides the XLSX download option from the Download modal + ], + // Use either `hiddenActions` or visibleActions, not both, to avoid errors + //visibleActions: [ + //Action.DownloadLiveboard, // Shows the Download parent action in the more options menu + //Action.DownloadLiveboardAsContinuousPDF, // Shows the Continuous PDF download option + //Action.DownloadLiveboardAsCsv, // Shows the CSV download option + //Action.DownloadLiveboardAsXlsx // Shows the XLSX download option + //] +}); +---- + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + disabledActions: [ + Action.DownloadLiveboard,// Disables the Download parent action in the more options menu + Action.DownloadLiveboardAsContinuousPDF, // Disables the Continuous PDF download option in the Download modal + Action.DownloadLiveboardAsCsv, // Disables the CSV download option in the Download modal + Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal + ], +}); +---- + +=== HostEvent workflow for the download actions +Use the HostEvent IDs to trigger download actions on an embedded Liveboard. + +* `HostEvent.DownloadLiveboardAsContinuousPDF` + +To open the **Download** modal with the continuous PDF download option selected. +* `HostEvent.DownloadAsPdf` + +To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of the visualization in the `vizId` key. +* `HostEvent.DownloadAsXlsx` + +To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view. +* `HostEvent.DownloadAsCsv` + +To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view. + +[#scheduled-exports] +== XLSX and CSV in Liveboard scheduled exports +To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` is set to `true`. + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + isGranularXLSXCSVSchedulesEnabled: true, // enable scope selection for XLSX and CSV Liveboard scheduled jobs. +}); +---- + +== #Related information# +* #xref:embed-pinboard.adoc[Embed a Liveboard]# +* #xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# +* #xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# +* #xref:Action.adoc[Actions]# +* #xref:HostEvent.adoc[HostEvent]# diff --git a/modules/ROOT/pages/whats-new-prev-history.adoc b/modules/ROOT/pages/whats-new-prev-history.adoc index 0de0de67b..eefffcd92 100644 --- a/modules/ROOT/pages/whats-new-prev-history.adoc +++ b/modules/ROOT/pages/whats-new-prev-history.adoc @@ -736,7 +736,7 @@ For more information, see xref:selective-user-access.adoc[User access to non-emb ==== You can now customize the width of the Liveboard breakpoint on an embedded instance. To enable it, you must set the `enable2ColumnLayout` property to `true`. -For more information, see xref:embed-pinboard.adoc#_redefine_liveboard_breakpoint_widths[Redefine Liveboard breakpoint widths]. +For more information, see #xref:customize-liveboard-layout.adoc#liveboard-breakpoints[Redefine Liveboard breakpoint widths]#. ==== .Visual Embed SDK @@ -1389,7 +1389,7 @@ We recommend using a development environment to test your customizations before ==== In the new Liveboard experience mode, you can now add Note tiles with custom text, images, and links. This feature is turned off by default and can be enabled by ThoughtSpot administrators. -For more information, see xref:embed-pinboard.adoc#noteTiles[Note tiles]. +For more information, see #xref:customize-liveboard-layout.adoc#noteTiles[Note tiles]#. ==== .Visual Embed SDK [%collapsible] @@ -1407,7 +1407,7 @@ For information about REST API enhancements, see xref:rest-apiv1-changelog.adoc[ .New Liveboard experience [%collapsible] ==== -The xref:embed-pinboard.adoc#lbv2[new Liveboard experience] is now Generally Available (GA) on embedded instances and is enabled by default. +The #xref:embed-pinboard.adoc[new Liveboard experience]# is now Generally Available (GA) on embedded instances and is enabled by default. ==== .New CSS variables for custom styling @@ -1605,7 +1605,7 @@ For more information, see xref:fixed-issues.adoc[Fixed issues]. ==== The new Liveboard experience[beta betaBackground]^Beta^ now supports organizing visualizations in tabs. Users with edit access to a Liveboard can add, edit, and move visualizations to tabs on a Liveboard. On embedded ThoughtSpot instances, developers can set a specific tab as an active tab using the Visual Embed SDK. -This feature is available only on deployments that have the new Liveboard experience enabled. For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. +This feature is available only on deployments that have the new Liveboard experience enabled. For more information, see #xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]#. [IMPORTANT] The new Liveboard experience is in BETA on embedded ThoughtSpot instances. This feature is turned off by default on embedded ThoughtSpot instances. @@ -1665,7 +1665,7 @@ The new Liveboard experience is currently available in BETA on embedded ThoughtS In ThoughtSpot Cloud 8.6.0.cl:: -The new Liveboard experience is turned off by default on embedded ThoughtSpot instances. If you are using the Visual Embed SDK to embed ThoughtSpot, you can xref:embed-pinboard.adoc#lbv2[set the `liveboardV2` parameter] in the SDK package to `true` and enable the new experience globally for all users on your instance. + +The new Liveboard experience is turned off by default on embedded ThoughtSpot instances. If you are using the Visual Embed SDK to embed ThoughtSpot, you can #xref:embed-pinboard.adoc[set the `liveboardV2` parameter]# in the SDK package to `true` and enable the new experience globally for all users on your instance. + + ThoughtSpot users with administrator privileges can also link:https://docs.thoughtspot.com/cloud/latest/liveboard-experience-new[turn on the new Liveboard experience, window=_blank] at the cluster level. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index ba1188c23..c5d0f72f5 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -64,7 +64,7 @@ ThoughtSpot now supports programmatic feature management with new REST APIv2 end ==== Liveboard enhancements * *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# + -Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:embed-pinboard.adoc#contextual-liveboard-filtering[Embed a Liveboard]. +Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see #xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]#. * *Host Events* + @@ -227,13 +227,13 @@ Embedded Spotter interface supports onboarding starter prompts to guide first-ti The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: * Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + -xref:embed-pinboard.adoc#_customizing_filter_visibility[Hides filters] that are not relevant to the displayed visualization in a tab. +#xref:customize-liveboard-filters.adoc#filter-visibility[Hides filters]# that are not relevant to the displayed visualization in a tab. * Compact header (`isLiveboardCompactHeaderEnabled`) + -Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:embed-pinboard.adoc#compact-header[compact Liveboard header]. +Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see #xref:customize-liveboard-layout.adoc#compact-header[compact Liveboard header]#. * Cover page filtering options (`coverAndFilterOptionInPDF`) + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + -Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. +Enables the #xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping]# feature. * Filter interactivity (`isEnhancedFilterInteractivityEnabled`) + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. @@ -500,7 +500,7 @@ Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. Excel exports for pivot tables:: Pivot table visualizations can now be exported to Excel format. -For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. +For more information, see #xref:liveboard-data-downloads.adoc#liveboard-download-options[Liveboard download options]#. --- diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 1d2ae8770..30f4e171a 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -84,6 +84,7 @@ module.exports = { 'getting-started', 'VisualEmbedSdk', 'embed-spotter', 'embed-spotter-agent', 'embed-ai-search-analytics', 'search-embed', 'embed-searchbar', 'embed-a-viz', 'embed-liveboard', + 'customize-liveboard-layout', 'customize-liveboard-filters', 'liveboard-data-downloads', 'full-embed', 'full-app-customize', 'react-app-embed', 'embed-without-sdk', 'mobile-embed', 'embed-ts-mobile-react-native', 'embed-ts-flutter', 'embed-ts-swift', 'embed-ts-android', From 2665348afe52f1af9910ef13727bbe4b2ea803dc Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 6 Oct 2026 10:00:24 +0530 Subject: [PATCH 002/169] removed highlights --- modules/ROOT/pages/events-hostEvents.adoc | 4 ++-- modules/ROOT/pages/filters_overview.adoc | 20 ++++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/events-hostEvents.adoc b/modules/ROOT/pages/events-hostEvents.adoc index 20272105c..e412fce35 100644 --- a/modules/ROOT/pages/events-hostEvents.adoc +++ b/modules/ROOT/pages/events-hostEvents.adoc @@ -383,7 +383,7 @@ embed.trigger(HostEvent.PinSpotterConversation, { ---- [#liveboard-group-events] -=== #Liveboard group and parameter events# +=== Liveboard group and parameter events The following `HostEvent` members are new in SDK 1.53.0 and support the scoped Liveboard filtering feature introduced in ThoughtSpot Cloud 26.10.0.cl. @@ -413,7 +413,7 @@ Use `HostEvent.GetGroups` to retrieve the group IDs needed before scoping a filt ---- [#applicability-host-events] -=== #Scoped filter and parameter host events# +=== Scoped filter and parameter host events The following existing `HostEvent` members gained an optional `applicability` attribute in Visual Embed SDK 1.53.0. This attribute scopes a filter or parameter operation to a specific Liveboard tab or group. diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index f618a328f..98d1a6ea3 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -223,16 +223,16 @@ liveboardEmbed.trigger(HostEvent.UpdateFilters, { ---- [#scoped-filter-updates] -=== #Scoped filter and parameter updates# -#Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parameters can be scoped at three levels:# +=== Scoped filter and parameter updates +Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parameters can be scoped at three levels: -* #*Liveboard*: applies to all visualizations on the Liveboard.# -* #*Tab*: applies only to visualizations on a specific tab.# -* #*Group*: applies only to visualizations in a specific group on a tab.# +* *Liveboard*: applies to all visualizations on the Liveboard. +* *Tab*: applies only to visualizations on a specific tab. +* *Group*: applies only to visualizations in a specific group on a tab. -#To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:embed-pinboard.adoc#scoped-liveboard-filtering[Scoped Liveboard filtering].# +To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:embed-pinboard.adoc#scoped-liveboard-filtering[Scoped Liveboard filtering]. -#To scope an update to a tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`. Set `level` to `TAB` or `GROUP`, and set `targetId` to the ID of the tab or group. To get the group IDs on a Liveboard, use `HostEvent.GetGroups`.# +To scope an update to a tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`. Set `level` to `TAB` or `GROUP`, and set `targetId` to the ID of the tab or group. To get the group IDs on a Liveboard, use `HostEvent.GetGroups`. [source,JavaScript] ---- @@ -251,7 +251,7 @@ liveboardEmbed.trigger(HostEvent.UpdateFilters, { }); ---- -#For more information, see xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events].# +For more information, see xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. === 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 `HostEvent.GetFilters`. @@ -269,7 +269,7 @@ Each filter object in the `HostEvent.GetFilters` response includes two additiona * `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`). -#Starting with Visual Embed SDK 1.53.0, the filter objects returned by `HostEvent.GetFilters` and the parameter objects returned by `HostEvent.GetParameters` also include an optional `applicability` field that indicates whether the filter or parameter is scoped to the Liveboard, a tab, or a group.# +Starting with Visual Embed SDK 1.53.0, the filter objects returned by `HostEvent.GetFilters` and the parameter objects returned by `HostEvent.GetParameters` also include an optional `applicability` field that indicates whether the filter or parameter is scoped to the Liveboard, a tab, or a group. For more information, see xref:events-hostEvents.adoc#_hostevent_getfilters[HostEvent.GetFilters] and xref:HostEvent.adoc#_getfilters[HostEvent reference documentation]. @@ -294,7 +294,7 @@ You can also listen for the user's interactions with the filters using the link: There is an equivalent EmbedEvent for Parameters called link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_parameterchanged[EmbedEvent.ParameterChanged]. -#Starting with Visual Embed SDK 1.53.0, the `EmbedEvent.FilterChanged` and `EmbedEvent.ParameterChanged` payloads include an optional `applicability` object that describes the scope of the changed filter or parameter. For more information, see xref:event-embedEvents.adoc#applicability-scope[Scoped filter and parameter events].# +Starting with Visual Embed SDK 1.53.0, the `EmbedEvent.FilterChanged` and `EmbedEvent.ParameterChanged` payloads include an optional `applicability` object that describes the scope of the changed filter or parameter. For more information, see xref:event-embedEvents.adoc#applicability-scope[Scoped filter and parameter events]. === UpdateCrossFilter event You can programmatically trigger an action to update a cross filter using link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatecrossfilter[HostEvent.UpdateCrossFilter]: From a1bef8fdd109a74adc45180a4f6ff152d9077baa Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 6 Oct 2026 10:10:57 +0530 Subject: [PATCH 003/169] formatting fix --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 91b0afe7c..235280ad0 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -23,7 +23,7 @@ Returns the Spotter Analysts visible to the caller. Updates a Spotter Analyst. * `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` + Deletes a Spotter Analyst. - ++ For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. Pin conversations in the update conversation API:: From 8e3a81f26583619c058e3810aa8c17ef4354ea41 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 6 Oct 2026 16:56:10 +0530 Subject: [PATCH 004/169] Updates for SCAL-341326, SCAL-337999, SCAL-337598 --- modules/ROOT/pages/about-rest-apis.adoc | 23 +++- modules/ROOT/pages/embed-actions.adoc | 121 ++++++++++++++++++ modules/ROOT/pages/embed-search.adoc | 10 ++ .../ROOT/pages/spottercode-integration.adoc | 5 + modules/ROOT/pages/whats-new.adoc | 23 ++-- 5 files changed, 162 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/about-rest-apis.adoc b/modules/ROOT/pages/about-rest-apis.adoc index 02d98842a..9e5baf84e 100644 --- a/modules/ROOT/pages/about-rest-apis.adoc +++ b/modules/ROOT/pages/about-rest-apis.adoc @@ -55,18 +55,31 @@ In the Playground, you can: * View and copy generated code samples for your requests. == Rate limits for API requests -To ensure API stability, optimize resource usage, and maintain service quality for all users, ThoughtSpot limits the number of public API requests allowed per client to prevent excessive requests from reaching application servers. +To ensure operational stability, optimize resource usage, and maintain service quality for all users, ThoughtSpot enforces rate limits on the number of public API requests allowed per client. -By default, on instances running 26.2.0.cl and later, a global rate limit of 100 requests per second per client IP is enforced at the cluster level for all public APIs. This limit is applied per client IP across all public APIs combined, not per endpoint. If a client IP exceeds this combined rate limit, a burst of 10 additional API requests is allowed before rejecting the requests with the 'HTTP 429: Too Many Requests' error. +By default, a global rate limit of 100 requests per second per client IP is enforced at the cluster level for all public APIs. This limit applies per client IP across all public APIs combined, not per individual endpoint. If a client IP exceeds this combined rate limit, a burst of requests up to 10 is allowed before rejecting the requests with the 'HTTP 429: Too Many Requests' error. For async status endpoints such as `/api/rest/2.0/metadata/tml/async/status`, up to 100 requests per minute per client IP are allowed, with a burst of 100 requests before requests are rejected with an HTTP 429 error. -These rate limits are enforced by default on all ThoughtSpot instances. Currently, rate limits are applied at the cluster level; Org-level rate limits are not supported. +=== Org-level rate limit +On ThoughtSpot Cloud instances with Orgs enabled, a rate limit of *50 RPS* per Org is enforced at the application layer. This limit is applied per Org across all public REST API endpoints combined. -To update rate limits or adjust the rate limit settings for your dev or prod environment, contact ThoughtSpot Support. +The Org-level rate limit provides noisy-neighbor protection in multi-Org deployments. It ensures that API usage from one Org does not impact the service quality of other Orgs on the same cluster. If the Org-level limit is exceeded, the API returns an `HTTP 429: Too Many Requests` error. -== REST API SDKs +The Org-level and cluster-level rate limits operate independently. A request can be rejected by either limit: + +* If a single client IP sends more than 100 RPS across the cluster, the cluster-level limit rejects the request. +* If all clients in a single Org collectively send more than 50 RPS, the Org-level limit rejects the request. + +=== Rate limit response +When a request is rejected due to rate limiting, the API returns the `HTTP/1.1 429 Too Many Requests` response. +If your application receives an HTTP 429 response, reduce the request frequency or implement a retry mechanism with exponential backoff. + +=== Adjusting rate limits +The default rate limits are designed for typical production workloads. To update rate limits or adjust the rate limit settings for your deployment, contact ThoughtSpot Support. + +== REST API SDKs To integrate v2.0 APIs into your applications faster, ThoughtSpot provides SDK libraries in several languages, including TypeScript and Python. The SDKs wrap endpoint calls, authentication, and typed request and response models. For more information, see xref:rest-api-sdk-libraries.adoc[REST API SDK libraries]. == Related information diff --git a/modules/ROOT/pages/embed-actions.adoc b/modules/ROOT/pages/embed-actions.adoc index 915ab4485..31209f385 100644 --- a/modules/ROOT/pages/embed-actions.adoc +++ b/modules/ROOT/pages/embed-actions.adoc @@ -69,6 +69,79 @@ If the actions are in a nested menu, you must specify the action ID for parent e visibleActions: [Action.Download, Action.DownloadAsPdf] ---- +==== Nested menu behavior + +When you use `visibleActions` with actions that belong to a nested menu, the following rules apply: + +* *Parent and child required* — To show a specific child action, include both the parent action ID and the child action ID. If you include only the child without the parent, the child action does not appear because the parent container is hidden. ++ +[source,Javascript] +---- +// Correct: show only the PDF option in the Download menu +visibleActions: [Action.Download, Action.DownloadAsPdf] + +// Incorrect: DownloadAsPdf will NOT appear because its parent (Action.Download) is absent +visibleActions: [Action.DownloadAsPdf] +---- + +* *Parent without children* — If you include a parent action without specifying any of its children, all default children of that parent appear. ++ +[source,Javascript] +---- +// All children of the Download menu (PDF, CSV, XLSX, PNG) will appear +visibleActions: [Action.Download] +---- + +==== Actions not supported in visibleActions + +The `visibleActions` array works as an allowlist for discrete menu actions and buttons. It does not control structural UI elements such as sidebars, banners, and panels. The following action IDs control structural UI surfaces and are supported only in `hiddenActions` (and where noted, `disabledActions`): + +[cols="2,3,1,1", options="header"] +|=== +|Action ID |Controls |Supported in `hiddenActions` |Supported in `visibleActions` + +|`Action.AllLiveboardFilters` +|All filter surfaces on a Liveboard (filter chips, parameter chips, cross-filter chips). Note: parameter and cross-filter chips are hide-only and do not support `disabledActions`. +|✓ +|✗ + +|`Action.SpotterSharedConversationBanner` +|The read-only data-access banner shown when a recipient opens a shared Spotter conversation. +|✓ +|✗ + +|`Action.SpotterShareUpToCurrentInfo` +|The footer note in the Spotter share modal ("Chat will be shared up to the current moment"). +|✓ +|✗ + +|`Action.SpotterSidebarHeader` +|The title and toggle button in the Spotter past conversations sidebar. +|✓ +|✗ + +|`Action.SpotterSidebarFooter` +|The documentation link in the Spotter past conversations sidebar. +|✓ +|✗ + +|`Action.SpotterSidebarToggle` +|The expand/collapse toggle button in the Spotter past conversations sidebar. +|✓ +|✗ + +|`Action.SpotterAnalystSidebar` +|The sidebar in the Spotter Analyst interface. +|✓ +|✗ +|=== + +[NOTE] +==== +If you add any of these action IDs to a `visibleActions` array, the SDK does not return an error, but the action visibility will not be affected in the embedded interface. Use `hiddenActions` to control these UI surfaces. +==== + + === Visible actions and hidden actions If both `visibleActions` and `hiddenActions` attributes are defined, the SDK will return a configuration error. @@ -211,6 +284,54 @@ const embed = new LiveboardEmbed("#your-own-div", { * If `primaryAction` is configured, the default action is moved to the More options `(...)` menu, and the action you configured appears as the primary button on your Liveboard visualizations. On Answers, the new action is added as a secondary button, positioned above the chart or table along with other primary actions ==== +== Hide the answer edit panel + +[NOTE] +==== +`hideAnswerEditPanel` is a `ViewConfig` flag, not an `Action` ID. It cannot be used in `visibleActions`, `hiddenActions`, or `disabledActions`. +==== + +The answer edit panel is a sidebar panel that allows users to edit the search tokens behind an Answer. It is shown by default in embedded views. + +To hide the answer edit panel, set `hideAnswerEditPanel` to `true` in your embed configuration. This flag is available on `SearchEmbed` and `AppEmbed`. + +// SOURCE: https://github.com/thoughtspot/visual-embed-sdk/blob/main/src/embed/search.ts +// SOURCE: https://github.com/thoughtspot/visual-embed-sdk/blob/main/src/embed/app.ts +[source,Javascript] +---- +// SearchEmbed +const embed = new SearchEmbed('#embed-div', { + // ... other config + hideAnswerEditPanel: true, +}); + +// AppEmbed +const embed = new AppEmbed('#embed-div', { + // ... other config + hideAnswerEditPanel: true, +}); +---- + +[cols="2,3", options="header"] +|=== +|Property |Details + +|*Type* +|`boolean` + +|*Default* +|`false` (panel is shown by default) + +|*Supported in* +|`SearchEmbed`, `AppEmbed` + +|*Not supported in* +|`LiveboardEmbed`, `EmbedViz`, `SpotterEmbed`, `AppEmbed` (non-Answer pages) + +|*Available from* +|SDK: 1.54.0 \| ThoughtSpot Cloud: 26.11.0.cl +|=== + == Code sample [source,JavaScript] diff --git a/modules/ROOT/pages/embed-search.adoc b/modules/ROOT/pages/embed-search.adoc index 54b163875..e09949efa 100644 --- a/modules/ROOT/pages/embed-search.adoc +++ b/modules/ROOT/pages/embed-search.adoc @@ -285,6 +285,16 @@ const searchEmbed = new SearchEmbed(document.getElementById('ts-embed'), { For more information about the new data panel, see link:https://docs.thoughtspot.com/cloud/latest/search-start[ThoughtSpot product documentation]. +=== Hide the chart Panel +The chart configuration sidebar panel in the search results and Answer pages allows users to edit chart type, modify chart styles, and configure other properties in the Answer interface. By default, this sidebar panel is visible. If you want to hide this panel, set the `hideAnswerEditPanel` flag to `true`. + +[source,Javascript] +---- +const searchEmbed = new SearchEmbed('#embed-div', { + //...other embed config */ + hideAnswerEditPanel: true, +}); +---- == Register, handle, and trigger events diff --git a/modules/ROOT/pages/spottercode-integration.adoc b/modules/ROOT/pages/spottercode-integration.adoc index 6bdb97d9e..5a5e4ac08 100644 --- a/modules/ROOT/pages/spottercode-integration.adoc +++ b/modules/ROOT/pages/spottercode-integration.adoc @@ -15,6 +15,11 @@ This guide walks you through the process of adding SpotterCode to your AI-native * Ensure that the latest version of Node.js is installed in your environment. This is required for building embedding code with the SDK. * Ensure that you have access to a ThoughtSpot instance and can view the objects and resources that you want to embed or access via the REST API. +[NOTE] +==== +For ThoughtSpot instances on version 26.7.0.cl or earlier, the administrator must add `spottercode.thoughtspot.app` to the xref:security-settings.adoc#cors-hosts[CORS] and xref:configure-saml.adoc#saml-redirect[SAML redirect] domains allowlists before users can authenticate with SpotterCode. +==== + [#_authenticate_spottercode] == Authentication Starting with August 2026, the SpotterCode MCP Server endpoint requires you to authenticate with a ThoughtSpot instance. This allows SpotterCode to perform authenticated user operations using ThoughtSpot REST APIs. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index ba1188c23..e9f128fbd 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -79,6 +79,14 @@ Liveboards that were previously blocked by Column Security Rules (CSR) now open --- +[discrete] +==== Upcoming changes to API rate limits +Starting from 26.11.0.cl, ThoughtSpot enforces an API rate limit of 50 requests per second (RPS) per Org for all public REST API endpoints. This Org-level limit operates independently of the existing cluster-level limit of 100 RPS per client IP. + +ThoughtSpot recommends reviewing your existing API integrations to identify any workflows that may exceed 50 RPS within a single Org. Where possible, implement request throttling to handle `HTTP 429: Too Many Requests` responses gracefully. If your workflows require a higher rate limit, contact ThoughtSpot Support to discuss your requirements. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. + [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.53.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. @@ -180,21 +188,6 @@ For more information, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 chang --- -//// -[discrete] -==== Answer Export API - -The following enhancements in the `POST /api/rest/2.0/report/answer` endpoint are now GA. - -* *Pinned Answer export* from a Liveboard, using the new `type` parameter. -* *Personalized View* support to export data from a specific Personalized View of a Liveboard. -* *Spotter Answer export* in `XLSX` and `PDF`, in addition to `CSV` and `PNG`. -* *Custom PNG output*, using `x_resolution`, `y_resolution`, and `scaling`. - -For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API]. - ---- -//// |=== From 32078ce58e6193de254b9cb3b457bbce3ca21b91 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 6 Oct 2026 18:09:22 +0530 Subject: [PATCH 005/169] minor edits and fixes --- modules/ROOT/pages/about-rest-apis.adoc | 14 ++++----- .../ROOT/pages/hosteventsv2-migration.adoc | 5 --- .../partials/rest-apiv1-deprecation-note.adoc | 2 +- modules/ROOT/pages/whats-new.adoc | 31 ++++++++++++------- 4 files changed, 27 insertions(+), 25 deletions(-) diff --git a/modules/ROOT/pages/about-rest-apis.adoc b/modules/ROOT/pages/about-rest-apis.adoc index 9e5baf84e..02296c787 100644 --- a/modules/ROOT/pages/about-rest-apis.adoc +++ b/modules/ROOT/pages/about-rest-apis.adoc @@ -12,7 +12,7 @@ You can use REST APIs to integrate ThoughtSpot capabilities into your applicatio * *Manage users, groups, and roles*. Create and manage user accounts, define groups and privileges, and automate provisioning workflows. * *Authenticate and manage sessions*. Get authentication tokens for users, including tokens for embedded application users with trusted authentication. -* *Manage metadata objects*. Search, create, update, and delete objects such as Liveboards, Answers, Models, Worksheets, and Tables. Import and export objects as ThoughtSpot Modeling Language (TML) representations. +* *Manage metadata objects*. Search, create, update, and delete objects such as Liveboards, Answers, Models, and Tables. Import and export objects as ThoughtSpot Modeling Language (TML) representations. * *Query data*. Run search queries against your data and fetch Liveboard, Answer, and visualization data in your application. * *Export reports*. Download Liveboards and Answers in PDF, PNG, CSV, or XLSX formats. * *Automate deployments*. Move content between environments and Orgs with TML and version control APIs, and manage multi-tenant deployments. @@ -37,7 +37,7 @@ ThoughtSpot REST APIs are available in the following versions: The REST API v2 framework includes a wider set of xref:rest-api-v2-reference.adoc[API endpoints] with enhanced functionality and provides an interactive Playground for ease of use. * REST API v1 (Deprecated) + -The xref:rest-api-reference.adoc[legacy REST v1 endpoints] to create, edit, administer and manage ThoughtSpot objects and data. +The xref:rest-api-reference.adoc[legacy REST API v1 endpoints] let you create, edit, administer, and manage ThoughtSpot objects and data. + include::{path}/rest-apiv1-deprecation-note.adoc[] @@ -57,12 +57,12 @@ In the Playground, you can: == Rate limits for API requests To ensure operational stability, optimize resource usage, and maintain service quality for all users, ThoughtSpot enforces rate limits on the number of public API requests allowed per client. -By default, a global rate limit of 100 requests per second per client IP is enforced at the cluster level for all public APIs. This limit applies per client IP across all public APIs combined, not per individual endpoint. If a client IP exceeds this combined rate limit, a burst of requests up to 10 is allowed before rejecting the requests with the 'HTTP 429: Too Many Requests' error. +By default, a global rate limit of 100 requests per second (RPS) per client IP is enforced at the cluster level for all public APIs. This limit applies per client IP across all public APIs combined, not per individual endpoint. If a client IP exceeds this combined rate limit, a burst of up to 10 requests is allowed before requests are rejected with the `HTTP 429: Too Many Requests` error. -For async status endpoints such as `/api/rest/2.0/metadata/tml/async/status`, up to 100 requests per minute per client IP are allowed, with a burst of 100 requests before requests are rejected with an HTTP 429 error. +For async status endpoints such as `/api/rest/2.0/metadata/tml/async/status`, up to 100 requests per minute per client IP are allowed, with a burst of 100 requests before requests are rejected with an `HTTP 429` error. === Org-level rate limit -On ThoughtSpot Cloud instances with Orgs enabled, a rate limit of *50 RPS* per Org is enforced at the application layer. This limit is applied per Org across all public REST API endpoints combined. +Starting from the 26.11.0.cl release, a rate limit of 50 RPS per Org is enforced at the application layer in ThoughtSpot instances with Orgs enabled. This limit is applied per Org across all public REST API endpoints combined. The Org-level rate limit provides noisy-neighbor protection in multi-Org deployments. It ensures that API usage from one Org does not impact the service quality of other Orgs on the same cluster. If the Org-level limit is exceeded, the API returns an `HTTP 429: Too Many Requests` error. @@ -74,10 +74,10 @@ The Org-level and cluster-level rate limits operate independently. A request can === Rate limit response When a request is rejected due to rate limiting, the API returns the `HTTP/1.1 429 Too Many Requests` response. -If your application receives an HTTP 429 response, reduce the request frequency or implement a retry mechanism with exponential backoff. +If your application receives an `HTTP 429` response, reduce the request frequency or implement a retry mechanism with exponential backoff. === Adjusting rate limits -The default rate limits are designed for typical production workloads. To update rate limits or adjust the rate limit settings for your deployment, contact ThoughtSpot Support. +The default rate limits are designed for typical production workloads. To request a change to the rate limits for your deployment, contact ThoughtSpot Support. == REST API SDKs To integrate v2.0 APIs into your applications faster, ThoughtSpot provides SDK libraries in several languages, including TypeScript and Python. The SDKs wrap endpoint calls, authentication, and typed request and response models. For more information, see xref:rest-api-sdk-libraries.adoc[REST API SDK libraries]. diff --git a/modules/ROOT/pages/hosteventsv2-migration.adoc b/modules/ROOT/pages/hosteventsv2-migration.adoc index 1b19c7d0f..4cb3e2669 100644 --- a/modules/ROOT/pages/hosteventsv2-migration.adoc +++ b/modules/ROOT/pages/hosteventsv2-migration.adoc @@ -21,11 +21,6 @@ The V2 framework supports the page context feature, which allows developers to e * Validates event payloads more strictly; for example, types, required fields, allowed values. * Standardizes event structures to reduce ambiguity and improve compatibility. -[NOTE] -==== -Currently, the Host Events V2 framework is in beta and not enabled by default on ThoughtSpot Embedded instances. -==== - === Host Events v1 and v2 comparison The following table lists the host event behavior in v1 and v2 framework: diff --git a/modules/ROOT/pages/partials/rest-apiv1-deprecation-note.adoc b/modules/ROOT/pages/partials/rest-apiv1-deprecation-note.adoc index 39bb2a047..c0dab4853 100644 --- a/modules/ROOT/pages/partials/rest-apiv1-deprecation-note.adoc +++ b/modules/ROOT/pages/partials/rest-apiv1-deprecation-note.adoc @@ -1,4 +1,4 @@ [IMPORTANT] ==== -The REST API v1 endpoints are deprecated and replaced with the xref:rest-api-v2-reference.adoc[REST API v2 endpoints]. Your existing integrations with REST API v1 endpoints will continue to function without disruption until further notice. ThoughtSpot strongly recommends migrating your integrations to the xref:rest-api-v2-getstarted.adoc[REST API v2 endpoints]. +The REST API v1 endpoints are deprecated and replaced with the xref:rest-api-v2-reference.adoc[REST API v2 endpoints]. Your existing integrations with REST API v1 endpoints will continue to function without disruption until March 2027. ThoughtSpot strongly recommends migrating your integrations to the xref:rest-api-v2-getstarted.adoc[REST API v2 endpoints]. ==== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index e9f128fbd..e71d52f10 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -26,7 +26,7 @@ This page lists new features, enhancements, and deprecated functionality introdu == October 2026 **Release version**: ThoughtSpot Cloud 26.10.0.cl + -*Upgrade notes*: No breaking changes in this release. + +*Upgrade notes*: ⚠️ Includes a deprecation and an upcoming change to API rate limits. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.53.0 or later [.cl-table, cols="2,4", frame=none, grid=none] @@ -43,20 +43,20 @@ a| Embed Spotter Analyst:: You can now embed a single, pinned Spotter Analyst in your application using the Visual Embed SDK. The `spotterAnalystConfig.analystId` property in `SpotterEmbed` locks the embed to one governed Analyst experience. For more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst]. - -REST API:: +Spotter Analyst APIs:: Spotter Analysts are governed AI agents you can create, configure, and manage via the REST API. Four new endpoints are available under `/api/rest/2.0/ai/agent/analysts/` to create, search, update, and delete Analysts programmatically. Each Analyst is configured with a name, description, one or more data sources, and optional instructions, MCP connectors, and starter prompts. For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. --- [discrete] ==== Pinning Spotter conversations -Users can now pin Spotter conversations in the embedded view and also via REST API. so they appear at the top of the conversation list for quick access. For more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst] and xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Spotter conversation APIs]. +Users can now pin Spotter conversations in the embedded view and through the REST API, so that pinned conversations appear at the top of the conversation list for quick access. For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations] and xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Spotter conversation APIs]. + --- [discrete] ==== Feature management through APIs -ThoughtSpot now supports programmatic feature management with new REST APIv2 endpoints available under `/api/rest/2.0/configurations/features/`. Cluster and Org admins can search feature configurations, assign features to Orgs, and set feature values without using the link:https://docs.thoughtspot.com/cloud/latest/admin-portal-2#_feature_management[new Admin portal, window=_blank]. For more information, see xref:feature-management-api.adoc[Feature Management]. +ThoughtSpot now supports programmatic feature management with new REST API v2 endpoints available under `/api/rest/2.0/configurations/features/`. Cluster and Org admins can search feature configurations, assign features to Orgs, and set feature values without using the link:https://docs.thoughtspot.com/cloud/latest/admin-portal-2#_feature_management[new Admin portal, window=_blank]. For more information, see xref:feature-management-api.adoc[Feature Management]. --- @@ -64,29 +64,37 @@ ThoughtSpot now supports programmatic feature management with new REST APIv2 end ==== Liveboard enhancements * *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# + -Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:embed-pinboard.adoc#contextual-liveboard-filtering[Embed a Liveboard]. +Liveboard filters now have a three-tier hierarchy: Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:embed-pinboard.adoc#contextual-liveboard-filtering[Embed a Liveboard]. * *Host Events* + -** The `HostEvent.GetGroups` event returns group details for the Liveboard, and the `applicability` attribute on `HostEvent.UpdateFilters` and `HostEvent.UpdateParameters` scopes filter updates to a specific tab or group. For more information, see xref:embed-events.adoc[Events and app interactions]. -** The `HostEvent.OpenParameter` event opens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group. +** The xref:HostEvent.adoc#_getgroups[`HostEvent.GetGroups`] event returns group details for the Liveboard, and the `applicability` attribute on `HostEvent.UpdateFilters` and `HostEvent.UpdateParameters` scopes filter updates to a specific tab or group. For more information, see xref:embed-events.adoc[Events and app interactions]. +** The xref:HostEvent.adoc#_openparameter[`HostEvent.OpenParameter`] event opens the parameter panel for a specific parameter on the Liveboard. It accepts an optional `applicability` object to scope the action to a tab or group. * *Centralized filter modal* in Liveboards is now generally available and enabled by default on ThoughtSpot embedded instances. * *Column security rules on Liveboards* + -Liveboards that were previously blocked by Column Security Rules (CSR) now open and work normally, with column security fully enforced, including in embedded Liveboards. Filter values from inaccessible columns are masked instead of blocking the Liveboard, and scheduled Liveboard deliveries apply CSR separately for each recipient. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards]. +Liveboards that were previously blocked by column security rules (CSR) now open and work normally, with column security fully enforced, including in embedded Liveboards. Filter values from inaccessible columns are masked instead of blocking the Liveboard, and scheduled Liveboard deliveries apply CSR separately for each recipient. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards]. + +--- + +[discrete] +==== HostEvent v1 framework deprecated [.version-badge.deprecated]#Deprecated# +Starting from ThoughtSpot Cloud 26.10.0.cl, the HostEvent v1 framework is deprecated and replaced by the HostEvent v2 framework, which provides context-aware event routing and stricter payload validation. If your embedded application uses HostEvent objects to trigger actions, evaluate the event behavior and its impact on your custom workflows in a development environment. For more information, see xref:deprecated-features.adoc#hostEventv1[HostEvent v1 framework deprecation] and the xref:hosteventsv2-migration.adoc[HostEvent v2 migration guide]. --- [discrete] ==== Upcoming changes to API rate limits -Starting from 26.11.0.cl, ThoughtSpot enforces an API rate limit of 50 requests per second (RPS) per Org for all public REST API endpoints. This Org-level limit operates independently of the existing cluster-level limit of 100 RPS per client IP. +Starting from 26.11.0.cl, ThoughtSpot will enforce an API rate limit of 50 requests per second (RPS) per Org for all public REST API endpoints on instances with Orgs. This Org-level limit operates independently of the existing cluster-level limit of 100 RPS per client IP. -ThoughtSpot recommends reviewing your existing API integrations to identify any workflows that may exceed 50 RPS within a single Org. Where possible, implement request throttling to handle `HTTP 429: Too Many Requests` responses gracefully. If your workflows require a higher rate limit, contact ThoughtSpot Support to discuss your requirements. +ThoughtSpot recommends reviewing your existing API integrations to identify any workflows that may exceed 50 RPS within a single Org. Where possible, implement request throttling, and retry with exponential backoff when you receive an `HTTP 429: Too Many Requests` response. If your workflows require a higher rate limit, contact ThoughtSpot Support to discuss your requirements. For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. +--- + [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.53.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. @@ -188,7 +196,6 @@ For more information, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 chang --- - |=== == August 2026 From aba96c0fb548a7f3f3b16b1310ff4fca9ae17fe7 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 6 Oct 2026 21:52:17 +0530 Subject: [PATCH 006/169] review feedback for Spotter Analyst --- modules/ROOT/pages/embed-spotter-analyst.adoc | 40 +++---------------- 1 file changed, 6 insertions(+), 34 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter-analyst.adoc b/modules/ROOT/pages/embed-spotter-analyst.adoc index ad3f5772e..371b9e0ed 100644 --- a/modules/ROOT/pages/embed-spotter-analyst.adoc +++ b/modules/ROOT/pages/embed-spotter-analyst.adoc @@ -14,9 +14,8 @@ This page shows how to embed one Analyst using the `SpotterEmbed` component. Before you embed an Analyst, make sure that you have the following: -* Your ThoughtSpot instance is on version 26.10.0.cl or later. Embedding a Spotter Analyst also requires Visual Embed SDK version 1.53.0 or later. -* GUID of the Analyst to embed. You can copy the GUID from the URL of the Spotter Analyst page or find the GUID using the xref:spotter-analyst-api.adoc#search-analysts[search Analysts] API endpoint. -* GUID of the data model to use for queries. You can use the model that the Analyst is already configured with. If the Analyst spans multiple models, you need the GUID of each model. +* A ThoughtSpot instance on version 26.10.0.cl or later. Embedding a Spotter Analyst also requires Visual Embed SDK version 1.53.0 or later. +* The GUID of the Analyst to embed. You can copy the GUID from the URL of the Spotter Analyst page or find the GUID using the xref:spotter-analyst-api.adoc#search-analysts[search Analysts] API endpoint. * Access for the users who see the embed. Users must have access to the Analyst and its data sources. To grant access, share the Analyst with the users or groups. To share an Analyst programmatically, see xref:spotter-analyst-api.adoc#share-analyst[Share an Analyst]. * Your embedding app's domain in the Content Security Policy (CSP) Visual Embed hosts and Cross-Origin Resource Sharing (CORS) allowlists. For more information, see xref:security-settings.adoc[Security settings]. @@ -68,41 +67,18 @@ init({ }); ---- -== Specify the Analyst and data source to embed +== Specify the Analyst to embed Create an instance of the `SpotterEmbed` object, and pin it to one Analyst by using `spotterAnalystConfig.analystId`. -The `analystId` is the GUID of the Analyst to embed. When you specify it, the embed opens with this Analyst and doesn't show the default Spotter or the *Show all* Analysts list. +The `analystId` is the GUID of the Analyst to embed. When you specify it, the embed opens with this Analyst and doesn't show the default Spotter or the *Show all* Analysts list. Ensure that the Analyst is already configured with its data sources. -Optionally, specify the data source that Spotter queries: - -* `worksheetId` + -GUID of the model to query. Include it alongside `analystId`. -* `dataSources` + -Array that contains one GUID for each model, for an Analyst that spans multiple models. If you set both `dataSources` and `worksheetId`, `dataSources` takes precedence. - -The following example embeds one Analyst that uses a single model: - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { width: '100%', height: '100%' }, - worksheetId: '{model-guid}', - - // Specify the Analyst ID - spotterAnalystConfig: { - analystId: '{analyst-guid}', - }, -}); ----- - -If the Analyst spans multiple models, use `dataSources` instead of `worksheetId`: +The following example embeds one Analyst: [source,JavaScript] ---- const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%' }, - dataSources: ['{model-guid-1}', '{model-guid-2}'], // Specify the Analyst ID spotterAnalystConfig: { @@ -226,7 +202,7 @@ If you want to show only the chat interface, without extra options such as start ==== Hiding the data source selector -To keep users on the data source that you specify, set `hideSourceSelection` to `true`. This hides the data source selector. To show the selected data source but prevent users from changing it, set `disableSourceSelection` to `true` instead. +To keep users on the data source configured for the Analyst, set `hideSourceSelection` to `true`. This hides the data source selector. To show the selected data source but prevent users from changing it, set `disableSourceSelection` to `true` instead. [source,JavaScript] ---- @@ -330,10 +306,6 @@ if (container) { width: '100%', // Set the width of the embedded frame }, - // ID of the model to query. For an Analyst that spans multiple models, - // use dataSources: ['{model-guid-1}', '{model-guid-2}'] instead. - worksheetId: '{model-guid}', - // Specify the Analyst ID spotterAnalystConfig: { analystId: '{analyst-guid}' }, From 8f25820ed452733d64cdff671cd26e9894f9b298 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 6 Oct 2026 21:48:56 +0530 Subject: [PATCH 007/169] v1 API cleanup --- modules/ROOT/pages/api-user-management.adoc | 30 +- modules/ROOT/pages/audit-logs.adoc | 5 +- modules/ROOT/pages/connections.adoc | 2368 +---------------- modules/ROOT/pages/org-manage-api.adoc | 56 +- .../pages/rest-api-v2-metadata-search.adoc | 20 +- modules/ROOT/pages/rest-api-v2-search.adoc | 4 +- .../ROOT/pages/rest-api-v2-users-search.adoc | 4 +- modules/ROOT/pages/roles.adoc | 32 +- modules/ROOT/pages/runtime-sort.adoc | 22 - 9 files changed, 33 insertions(+), 2508 deletions(-) diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index 15312afc7..4989e7a95 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -10,7 +10,7 @@ To provide access to ThoughtSpot content or define privileges, you must add user == User creation and update -You can create users and update user profiles using xref:rest-api-reference.adoc#_user_management[REST API v1] or xref:rest-api-v2-reference.adoc#_users[v2 endpoints]. +#You can create users and update user profiles using the xref:rest-api-v2-reference.adoc#_users[REST API v2 user endpoints].# While you can delete users, it is preferable to deactivate a user, which maintains the user's references within the system. @@ -75,27 +75,22 @@ The common user state transitions include: To check the status of a user account, use one of the following API endpoints: * +++POST /api/rest/2.0/users/search+++ (REST API v2) -* xref:user-api.adoc[GET /tspublic/v1/user/] (REST API v1) To create a user in the `SUSPENDED` state, use one of the following API endpoints: * +++POST /api/rest/2.0/users/create+++ (Rest API v2) -* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1) To update user status from `ACTIVE` or `PENDING` to `SUSPENDED`, or reactivate a `SUSPENDED` user to the ACTIVE or PENDING state, use one of the following API endpoints: * +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) -* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) To deactivate an `ACTIVE` user, use one of these API endpoints: * +++POST /api/rest/2.0/users/deactivate+++ (Rest API v2) -* xref:user-api.adoc#deactivate-user[POST /tspublic/v1/user/inactivate] (Rest API v1) To activate an `INACTIVE` user account, use one of these API endpoints: * +++POST /api/rest/2.0/users/activate+++ (Rest API v2) -* xref:user-api.adoc#activate-user[POST /tspublic/v1/user/activate] (Rest API v1) //// @@ -118,13 +113,11 @@ Administrators can manage the user account status for all users. For IAMv2 users To create a user: -* +++POST /api/rest/2.0/users/create+++ (Rest API v2) -* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1) +* #+++POST /api/rest/2.0/users/create+++# To update user details: -* +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) -* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) +* #+++POST /api/rest/2.0/users/{user_identifier}/update+++# [NOTE] ==== @@ -172,28 +165,21 @@ For more information, see the following pages: == User group creation and update -Groups can be created via xref:rest-api-v2-reference.adoc#_groups[REST API v2] or xref:rest-api-reference.adoc#_groups_and_privileges[REST API v1] API endpoint. +#Groups can be created via the xref:rest-api-v2-reference.adoc#_groups[REST API v2 group endpoints].# The xref:api-user-management.adoc#group-privileges[Group privileges] are set directly on groups, either during group creation or via a group update API call. == User association to groups You can add users to specific groups when creating a user or group via REST API endpoints. -The REST API v1 xref:group-api.adoc#addMembers[group/addmemberships] endpoint allows adding multiple users to multiple groups in a single request. - -To get a list of users assigned to a group, you can use the +++POST /api/rest/2.0/groups/search+++ v2 endpoint or the xref:group-api.adoc#get-usersInGroup[/tspublic/v1/group/{groupid}/users] v1 endpoint. - -To remove a user from a group, use the update group REST v2 endpoint, or the following REST API v1 endpoints: +#To add users to an existing group or remove users from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint with the `user_identifiers` parameter and the `ADD`, `REMOVE`, or `REPLACE` operation. To update the groups of a single user, use the +++POST /api/rest/2.0/users/{user_identifier}/update+++ endpoint with the `group_identifiers` parameter.# -* xref:group-api.adoc#delete-user-assoc[POST /tspublic/v1/group/{groupid}/user/{userid}] + -removes a user from a specific group -* xref:group-api.adoc#removeMembers[POST /tspublic/v1/group/removememberships] + -removes a list of users from many groups at once. +#To get a list of users assigned to a group, use the +++POST /api/rest/2.0/groups/search+++ endpoint.# == Access control (sharing) Access to objects is determined by content *shared* directly to the user or the groups they belong to. It is easier to manage and audit sharing through groups rather than object sharing at the individual user level. -Users can share objects or modify sharing properties through the UI or via an API call to the `POST /api/rest/2.0/security/metadata/share` or xref:security-api.adoc#share-object[/tspublic/v1/security/share] endpoint. +Users can share objects or modify sharing properties through the UI or via an API call to the #`POST /api/rest/2.0/security/metadata/share` endpoint#. [#group-privileges] == Group privileges @@ -222,7 +208,7 @@ When creating or updating a group using the REST API v2 endpoints, use the `role [NOTE] ==== -Roles must be available before they can be assigned. Use the xref:roles-api.adoc[Roles API] to create roles programmatically before calling the group create or update endpoints. +Roles must be available before they can be assigned. #Use the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fcreate-role[`POST /api/rest/2.0/roles/create`] endpoint# to create roles programmatically before calling the group create or update endpoints. ==== For a complete list of available privileges and role categories, see xref:roles.adoc[Role-based access control]. diff --git a/modules/ROOT/pages/audit-logs.adoc b/modules/ROOT/pages/audit-logs.adoc index 8269969f2..817593b88 100644 --- a/modules/ROOT/pages/audit-logs.adoc +++ b/modules/ROOT/pages/audit-logs.adoc @@ -43,10 +43,9 @@ Error Message: Cannot use first or last name in the password.","userId":"e3dc495 Org ID if your ThoughtSpot application instance has Orgs. == Fetch logs via API -To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. You can use any of the following APIs: +To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. #Use the following API endpoint:# -* +++POST /api/rest/2.0/logs/fetch+++ (Recommended) -* xref:logs-api.adoc[GET /tspublic/v1/logs/topics/{topic}] (REST API v1) +* #+++POST /api/rest/2.0/logs/fetch+++# On Orgs-enabled clusters, the API fetches security logs for the current Org text. However, the administrator of the primary Org (Org 0) can fetch logs not just for the primary Org, but also for all other Orgs if the `get_all_logs` parameter is set to `true` in the API request. diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index bccbca98d..ca0b2e3ea 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -73,10 +73,7 @@ ThoughtSpot supports connecting to external data warehouses and using these as d This article describes the procedures for setting and managing data connections through the REST APIs. For information about how to set up a data connection, see link:https://docs.thoughtspot.com/cloud/latest/connections[Data Connections in ThoughtSpot, window=_blank]. == Data Connection APIs -The connection API endpoints allow you to create, edit, delete, export, and query data connections on a ThoughtSpot cluster. For more information about the API endpoints, see the following pages: - -* xref:connections-api.adoc[REST API v1, window=_blank] -* https://developers.thoughtspot.com/docs/rest-apiv2-reference#_connections[REST APIs v2, window=_blank] +The connection API endpoints allow you to create, edit, delete, export, and query data connections on a ThoughtSpot cluster. #For more information about the API endpoints, see https://developers.thoughtspot.com/docs/rest-apiv2-reference#_connections[REST API v2 Connection endpoints, window=_blank].# === Required permissions @@ -634,10 +631,7 @@ To understand about the data catalog tools supported by ThoughtSpot, see the fol * https://docs.thoughtspot.com/cloud/latest/catalog-integration-atlan[Atlan, window=_blank] * https://docs.thoughtspot.com/cloud/latest/catalog-integration-collibra[Collibra, window=_blank] -To understand the metadata API endpoints, see the following pages: - -* https://developers.thoughtspot.com/docs/catalog-and-audit[REST APIs v1, window=_blank] -* https://developers.thoughtspot.com/docs/rest-apiv2-reference#_metadata[REST APIs v2, window=_blank] +#To understand the metadata API endpoints, see https://developers.thoughtspot.com/docs/rest-apiv2-reference#_metadata[REST API v2 Metadata endpoints, window=_blank].# == Connection Configuration ThoughtSpot supports multiple configurations per data Connection. This feature allows data engineers to define and manage several distinct Connection configurations under a single data Connection object in ThoughtSpot. @@ -658,2361 +652,3 @@ Gets custom calendars for the connection ID specified in the API request. Deletes a custom calendar. * `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + Updates a custom calendar. - - - -//// -[#cre-connection] -== Add a data connection for live query service - -ThoughtSpot supports connecting to external data warehouses and using these as data sources for analytics and visualizations. To create a connection to an external data source and set up a live query service, use the `/tspublic/v1/connection/create` API endpoint. - - -=== Resource URL ----- -POST /tspublic/v1/connection/create ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form parameter|Description -|`name` |__String__. Name of the connection. -|`description` |__String__ A short description of data connection. -|`type`|__String__. Type of the data connection. For example, `RDBMS_SNOWFLAKE`, `RDBMS_REDSHIFT`. - -Valid values for `type` map to the *name* property in the API response returned by the xref:connections-api.adoc#connection-types[/tspublic/v1/connection/types API endpoint]. -|`createEmpty`|__Boolean__. Allows creating a connection without tables. If you want to store only the configuration attributes and import tables later, you can set this attribute to `true`. The default value is `false`. -|`metadata` a|__String__. A JSON map of the connection metadata. The metadata must include xref:connections-api.adoc#connection-attr[configuration attributes], database, schema, and table objects. However, you can create a connection without tables by setting the `createEmpty` attribute to `true`. -|`state`|_Integer_. The GUID of the OAuth redirect URI. This attribute is automatically populated and cannot be set by users. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'name=Snowflake&description=Snowflake_connection&type=RDBMS_SNOWFLAKE&metadata=' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/create' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/create ----- - -==== Example metadata JSON without tables - -The following example shows the metadata JSON map for creating a Snowflake data connection without tables. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"TestConn123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - - ] -} ----- - - -==== Example metadata JSON with tables - -The following example shows the metadata JSON map for creating a Snowflake data connection. Note that the example shows the configuration attributes required to authenticate to the data source, and the object metadata (database, schema, and tables) to add to the connection. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"TestConn123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - { - "name":"AllDatatypes", - "isAutoCreated":false, - "schemas":[ - { - "name":"alldatatypes", - "tables":[ - { - "name":"allDatatypes", - "type":"TABLE", - "description":"", - "selected":true, - "linked":true, - "columns":[ - { - "name":"CNUMBER", - "type":"INT64", - "canImport":true, - "selected":true, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - }, - { - "name":"CDECIMAL", - "type":"INT64", - "canImport":true, - "selected":true, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - } - ] - } - ] - } - ] - } - ] -} ----- - -=== Example response - -If the connection creation is successful, the API returns a response body with the connection metadata header: - -[source,JSON] ----- -{ - "header": { - "id": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "indexVersion": 0, - "generationNum": 0, - "name": "TEST_conn_1", - "description": "TEST_conn_private_1", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531177, - "modified": 1632118531177, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "logicalTableList": [ - { - "columns": [ - { - "physicalColumnGUID": "61d10324-ac22-43e2-8623-fa96f503bab5", - "position": 0, - "header": { - "id": "fd718c83-5e9c-45ae-a4cd-1cb13b03db2f", - "indexVersion": 381, - "generationNum": 384, - "name": "CNUMBER", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "isDerived": false, - "dataType": "INT64", - "type": "MEASURE", - "defaultAggrType": "SUM", - "physicalColumnName": "CNUMBER", - "ownerName": "allDatatypes", - "ownerType": "ONE_TO_ONE_LOGICAL", - "entityCategory": "DEFAULT", - "columnMappingInfo": { - "columnName": "CNUMBER" - }, - "spotiqPreference": "DEFAULT", - "isAdditive": true, - "indexType": "DONT_INDEX", - "indexPriority": 1, - "sources": [], - "synonyms": [], - "customActionTags": [], - "injectedInlineValues": [], - "precision": -1, - "scale": 0, - "schemaVersion": "4", - "isPrimaryKey": false, - "isAttributionDimension": true - }, - { - "physicalColumnGUID": "86c34243-9637-4737-993f-6ed30d3e682c", - "position": 1, - "header": { - "id": "6eed0b58-d195-4236-a376-f135f9b24204", - "indexVersion": 381, - "generationNum": 384, - "name": "CDECIMAL", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "isDerived": false, - "dataType": "INT64", - "type": "MEASURE", - "defaultAggrType": "SUM", - "physicalColumnName": "CDECIMAL", - "ownerName": "allDatatypes", - "ownerType": "ONE_TO_ONE_LOGICAL", - "entityCategory": "DEFAULT", - "columnMappingInfo": { - "columnName": "CDECIMAL" - }, - "spotiqPreference": "DEFAULT", - "isAdditive": true, - "indexType": "DONT_INDEX", - "indexPriority": 1, - "sources": [], - "synonyms": [], - "customActionTags": [], - "injectedInlineValues": [], - "precision": -1, - "scale": 0, - "schemaVersion": "4", - "isPrimaryKey": false, - "isAttributionDimension": true - } - ], - "tableFilters": [], - "physicalTableVersion": 0, - "logicalTableContent": { - "joinType": "INNER", - "joinOverrides": {}, - "physicalTableName": "allDatatypes", - "worksheetType": "VIEW", - "isAggregatedWorksheet": false, - "bypassRLS": false, - "shardingInfo": { - "primaryKeyColumns": [], - "shardingKeyColumns": [], - "numberOfShards": 0 - }, - "tableMappingInfo": { - "databaseName": "AllDatatypes", - "schemaName": "alldatatypes", - "tableName": "allDatatypes", - "tableType": "TABLE", - "cachingInfo": { - "isCached": false, - "lastLoadTime": 0, - "type": "UNKNOWN" - } - }, - "isOptimized": false, - "schemaVersion": "4" - }, - "type": "ONE_TO_ONE_LOGICAL", - "generationType": "DEFAULT", - "physicalTableGUID": "14b7589b-8a98-4786-a0c5-0396e05b91ba", - "relationships": [], - "dataSourceId": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "dataSourceTypeEnum": "DEFAULT", - "header": { - "id": "b0248372-5e68-4815-8682-67715456efb2", - "indexVersion": 381, - "generationNum": 382, -## "name": "allDatatypes", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "su", - "authorDisplayName": "Administrator Super-User", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "type": "ONE_TO_ONE_LOGICAL", - "isExternal": true, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "destinationRelationships": [], - "relationshipsWithin": "", - "isCached": false - } - ], - "dataSourceContent": { - "statistics": {}, - "dataLoadInfo": { - "tableToTaskIdMap": {} - }, - "schemaVersion": "4", - "configuration": { - "password": "", - "role": "DEVELOPER", - "warehouse": "MEDIUM_WH", - "accountName": "thoughtspot_partner", - "user": "tsadmin" - } - } -} - ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful creation of the connection object - -| **401** -| Unauthorized or wrong credentials - -| **500** -| The connection could not be created -|=== - - -[#edit-connection] -== Edit an existing data connection - -To update or modify the connection attributes of a data connection, use the `/tspublic/v1/connection/update` API. - -=== Resource URL ----- -POST /tspublic/v1/connection/update ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form parameter|Description -|`name` |__String__. Name of the connection. -|`description` |__String__. The description of the data connection. -|`type`|__String__. Type of the data connection. For example, `RDBMS_SNOWFLAKE`, `RDBMS_REDSHIFT`. Valid values for `type` map to the *name* attribute from the in the response to the xref:connections-api.adoc#connection-types[/tspublic/v1/connection/types API endpoint]. -|`createEmpty`|__Boolean__. Allows updating a connection without importing tables. If you want to update only the configuration attributes, you can set this attribute to `true`. The default value is `false`. -|`metadata` a|__String__. A JSON map of the connection metadata. The metadata must include xref:connections-api.adoc#connection-attr[configuration attributes], database, schema, and table objects. However, if the `createEmpty` attribute to `true`, you can update the connection attributes without importing tables. -|`id`|__String__. The GUID of the data connection that you want to modify. -|`state`|_Integer_. The GUID of the OAuth redirect URI. This attribute is automatically populated and cannot be set by users. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'name=Snow_TEST&description=Test_connection&type=RDBMS_SNOWFLAKE&id=9114f105-fc9e-48c9-a8f1-57f2fda4f056&metadata=' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/update' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/update ----- - -==== Example metadata JSON without tables - -The following example shows the metadata JSON map for modifying a Snowflake connection without importing tables. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"Embrace123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - - ] -} ----- - - -==== Example metadata JSON with tables - -The following example shows the metadata JSON for modifying a Snowflake data connection. Note that the example shows the configuration attributes to authenticate to the data source, tables, and column data for connection modification. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"Embrace123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - { - "name":"AllDatatypes", - "isAutoCreated":false, - "schemas":[ - { - "name":"alldatatypes", - "tables":[ - { - "name":"allDatatypes", - "type":"TABLE", - "description":"", - "selected":true, - "linked":true, - "columns":[ - { - "name":"CDECIMAL", - "type":"INT64", - "canImport":false, - "selected":true, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - }, - { - "name":"CBIGINT", - "type":"INT64", - "canImport":false, - "selected":false, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - } - ] - } - ] - } - ] - } - ] -} ----- - -=== Example response - -If the connection modification is successful, the API returns a response body with the updated details: - -[source,JSON] ----- -{ - "dataSource": { - "header": { - "id": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "indexVersion": 385, - "generationNum": 385, - "name": "TEST_conn_1", - "description": "TEST_conn_private_1", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1632118531177, - "modified": 1632118751633, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "isDeleted": false, - "isHidden": false, - "isAutoCreated": false, - "statistics": { - "dataLoadStatistics": { - "scheduled": false, - "connectionType": "", - "connectionDisplayName": "", - "dataLoadStatusList": [], - "header": { - "id": "a2352b8c-e85e-4d58-8f6a-ac42c0252f2d", - "indexVersion": 385, - "generationNum": 385, - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "isDeleted": false, - "isHidden": false, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [] - } - }, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "logicalTableList": [ - { - "columns": [ - { - "physicalColumnGUID": "86c34243-9637-4737-993f-6ed30d3e682c", - "position": 1, - "header": { - "id": "6eed0b58-d195-4236-a376-f135f9b24204", - "indexVersion": 382, - "generationNum": 382, - "name": "CDECIMAL", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "isDerived": false, - "dataType": "INT64", - "type": "MEASURE", - "defaultAggrType": "SUM", - "physicalColumnName": "CDECIMAL", - "ownerName": "allDatatypes", - "ownerType": "ONE_TO_ONE_LOGICAL", - "entityCategory": "DEFAULT", - "columnMappingInfo": { - "columnName": "CDECIMAL" - }, - "spotiqPreference": "DEFAULT", - "isAdditive": true, - "indexType": "DONT_INDEX", - "indexPriority": 1, - "sources": [], - "synonyms": [], - "customActionTags": [], - "injectedInlineValues": [], - "precision": -1, - "scale": 0, - "isPrimaryKey": false, - "isAttributionDimension": true - } - ], - "tableFilters": [], - "physicalTableVersion": 0, - "logicalTableContent": { - "joinType": "INNER", - "joinOverrides": {}, - "physicalTableName": "allDatatypes", - "worksheetType": "VIEW", - "isAggregatedWorksheet": false, - "bypassRLS": false, - "shardingInfo": { - "primaryKeyColumns": [], - "shardingKeyColumns": [], - "numberOfShards": 0 - }, - "tableMappingInfo": { - "databaseName": "AllDatatypes", - "schemaName": "alldatatypes", - "tableName": "allDatatypes", - "tableType": "TABLE", - "cachingInfo": { - "isCached": false, - "lastLoadTime": 0, - "type": "UNKNOWN" - } - }, - "isOptimized": false - }, - "type": "ONE_TO_ONE_LOGICAL", - "generationType": "DEFAULT", - "physicalTableGUID": "14b7589b-8a98-4786-a0c5-0396e05b91ba", - "relationships": [], - "dataSourceId": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "dataSourceTypeEnum": "RDBMS_SNOWFLAKE", - "header": { - "id": "b0248372-5e68-4815-8682-67715456efb2", - "indexVersion": 384, - "generationNum": 384, - "name": "allDatatypes", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "type": "ONE_TO_ONE_LOGICAL", - "isExternal": true, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "destinationRelationships": [], - "relationshipsWithin": "", - "isCached": false - } - ], - "dataSourceContent": { - "statistics": {}, - "dataLoadInfo": { - "tableToTaskIdMap": {} - }, - "configuration": { - "password": "", - "role": "DEVELOPER", - "warehouse": "MEDIUM_WH", - "accountName": "thoughtspot_partner", - "user": "tsadmin" - } - } - }, - "deletedObjects": { - "deleteStatus": "SUCCESS", - "deleteFailTables": [], - "deleteFailColumns": {} - } -} - ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful update operation -| **401** -| Unauthorized or wrong credentials - -| **500** -| Invalid parameters -|=== - - -[#connection-types] -== Get a list of data connections -To get a list of data connections and their associated attributes, send a `GET` request to the `/tspublic/v1/connection/types` API endpoint. - -=== Resource URL ----- -GET /tspublic/v1/connection/types ----- - -=== Request parameters - -None - -=== Example request - -.cURL -[source,cURL] ----- -curl -X GET \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/types' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/types ----- - -=== Example response - -[source,JSON] ----- -[ - { - "name": "RDBMS_SNOWFLAKE", - "displayName": "Snowflake", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_REDSHIFT", - "displayName": "Amazon Redshift", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_GCP_BIGQUERY", - "displayName": "Google BigQuery", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_AZURE_SQL_DATAWAREHOUSE", - "displayName": "Azure Synapse", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_PRESTO", - "displayName": "Starburst", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_ORACLE_ADW", - "displayName": "Oracle ADW", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_DATABRICKS", - "displayName": "Databricks", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - } -] ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful retrieval of connection types - -| **401** -| Unauthorized or wrong credentials - -| **500** -| No data connections set up on the cluster -|=== - -[#live-query-connections] -== Get a list of live query connections - -To get a list of data connections that are set up as data sources for live query, send a `GET` request to the `GET /tspublic/v1/connection/list` API endpoint. - -=== Resource URL ----- -GET /tspublic/v1/connection/list ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Query parameter|Description -|`category` __Optional__ a|__String__. Type of the live query object. Valid values are: - -* `All` -+ -Gets all live query objects set up on the cluster - -* `MY` -+ -Gets a list of live query objects that are set up on your cluster. - -|`sort` __Optional__ a|__String__. Sort order for the headers. Valid values are: - -* `DEFAULT` to use the default sort order in the response. -* `NAME` to sort headers by the connection name. -* `DISPLAY_NAME` to sort headers by the display name of the connections. -* `AUTHOR` to sort the headers by the author who set up the live query connection. -* `CREATED` to sort headers by the timestamp at which live query connections were set up. -* `MODIFIED` to sort headers by the timestamp at which the live query connections were modified. -| `sortascending` + a|__Boolean__. A flag to specify the sort order. A null value defines the default order. -* To set an ascending order, specify `true`. -* To set a descending order, specify `false`. -|`offset` __Optional__|__Integer__. Batch offset to value to fetch page headers. The default value is `-1`, which implies first page. -|`batchsize` __Optional__ |__Integer__. Number of batches in which you want to fetch page headers in a single query. The default value is `-1`, which implies no pagination. -|`tagname` __Optional__ |__Array of strings__. A JSON array of tag names to filter response headers by tags. A tag is a label applied to a ThoughtSpot object. -|`pattern` __Optional__ |__String__. A pattern to match the name of the object. This parameter supports matching case-insensitive strings. For a wildcard match, use `%`. -|==== - -=== Example request - -.cURL - -[source,curl] ----- -curl -X GET \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/list' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/list ----- - -=== Example response - -[source,JSON] ----- -{ - "headers": [ - { - "id": "c1f17251-b2b1-4230-b10b-c81254d5189f", - "indexVersion": 149, - "generationNum": 149, - "name": "test", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1625126133409, - "modified": 1625126133410, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "c1f17251-b2b1-4230-b10b-c81254d5189f", - "isDeleted": false, - "isHidden": false, - "statistics": { - "dataLoadStatistics": { - "scheduled": false, - "connectionType": "", - "connectionDisplayName": "", - "dataLoadStatusList": [], - "header": { - "id": "c4831f2f-c0a2-498b-9ac5-98b8bd222058", - "indexVersion": 149, - "generationNum": 149, - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "c1f17251-b2b1-4230-b10b-c81254d5189f", - "isDeleted": false, - "isHidden": false, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [] - } - }, - "tags": [], - "type": "RDBMS_SNOWFLAKE", - "isExternal": false, - "isDeprecated": false - }, - { - "id": "55bf4728-bea1-4e89-ae29-822413660daf", - "indexVersion": 328, - "generationNum": 328, - "name": "testsnow", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1625139996582, - "modified": 1625139996583, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "55bf4728-bea1-4e89-ae29-822413660daf", - "isDeleted": false, - "isHidden": false, - "statistics": { - "dataLoadStatistics": { - "scheduled": false, - "connectionType": "", - "connectionDisplayName": "", - "dataLoadStatusList": [], - "header": { - "id": "179697ab-5212-4da8-9508-e0550b7b2327", - "indexVersion": 328, - "generationNum": 328, - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "55bf4728-bea1-4e89-ae29-822413660daf", - "isDeleted": false, - "isHidden": false, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [] - } - }, - "tags": [], - "type": "RDBMS_SNOWFLAKE", - "isExternal": false, - "isDeprecated": false - } - ], - "isLastBatch": true, - "debugInfo": {} -} ----- - - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful retrieval of live query connections list - -| **401** -| Unauthorized or wrong credentials - -| **500** -| No live query connections on the cluster -|=== - -[#connMetadata] -== Get details of a specific connection - -To get details of a specific data connection and its associated columns, send a `POST` request to the `/tspublic/v1/connection/fetchConnection` endpoint. - - -=== Resource URL - ----- -POST /tspublic/v1/connection/fetchConnection ----- - -=== Request parameters - -[width="100%" cols="2,6"] -[options='header'] -|==== -|Form Data Parameter|Description -|`id` + a|__String__. GUID of the data connection. -|`includeColumns` + a|__Boolean__. A flag to include or exclude column metadata in the API response. By default, the API returns data for all columns in the response. -|`config` + -__Optional__ a|__String__. Configuration attributes to override the connection metadata details in the API response. Use this attribute to query data from a specific database. For example, if your connection has a database named `PROD`, and you want to fetch details with the database name as `DEVELOPMENT`, you can define the `config` string as `{"database":"DEVELOPMENT"}`. - -[NOTE] -==== -Note that the `config` attribute does not update the connection metadata in the ThoughtSpot system. It only allows you to modify the metadata in the API response. To update a connection, you must use the `/tspublic/v1/connection/update` endpoint. -==== -|`authentication_type` + a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + - -* `SERVICE_ACCOUNT` + -For data connections that require service account credentials to authenticate to the Cloud Data Warehouse and fetch data. - -* `OAUTH` + -For data connections that require OAuth credentials to authenticate to the Cloud Data Warehouse and fetch data. + -ThoughtSpot data connections to Teradata, Oracle, and Presto Cloud Data Warehouse do not support the `OAuth` authentication type. - -* `IAM` + -For data connections that have the IAM OAuth set up. This authentication type is supported on Amazon Redshift connections only. - -* `EXTOAUTH` + -For data connections that have external OAuth set up. ThoughtSpot supports external OAuth with Microsoft Azure Active Directory (AD) and Okta for Snowflake data connections. For more information, see link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-okta-oauth[Configure Okta OAuth for a Snowflake connection, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-azure-ad-oauth[Configure Azure AD external OAuth for a Snowflake connection, window=_blank]. -|==== - -=== Example request - -.cURL - -[source,CURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'id=abb64e33-1f06-4994-9af7-f6ea8729c9f1&includeColumns=false&config={"database":"RETAILAPPAREL-DEV"}' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchConnection' ----- - -.Request URL - ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchConnection ----- - -=== Example response - -.Sample response with column data -[%collapsible] -==== -[source,JSON] ----- -{ - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "externalDatabases": [ - { - "name": "RETAILAPPAREL", - "isAutoCreated": false, - "schemas": [ - { - "name": "INFORMATION_SCHEMA", - "tables": [ - { - "name": "APPLICABLE_ROLES", - "type": "VIEW", - "description": "The roles that can be applied to the current user.", - "selected": false, - "linked": true, - "columns": [ - { - "name": "SCHEMA_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FILE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_LOAD_TIME", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STATUS", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROW_COUNT", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROW_PARSED", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_MESSAGE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_LINE_NUMBER", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_CHARACTER_POSITION", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_COL_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ERROR_COUNT", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ERROR_LIMIT", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "relationships": [] - }, - { - "name": "SCHEMATA", - "type": "VIEW", - "description": "The schemas defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [ - { - "name": "CATALOG_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SCHEMA_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SCHEMA_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_TRANSIENT", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_MANAGED_ACCESS", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "RETENTION_TIME", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DEFAULT_CHARACTER_SET_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DEFAULT_CHARACTER_SET_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DEFAULT_CHARACTER_SET_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SQL_PATH", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "COMMENT", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "relationships": [] - }, - { - "name": "FACT_RETAPP_SALES", - "type": "TABLE", - "description": "", - "selected": true, - "linked": true, - "columns": [ - { - "name": "SALESID", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "PRODUCTID", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "STOREID", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "QUANTITYPURCHASED", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "ITEMPRICE", - "type": "DOUBLE", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "SALES", - "type": "DOUBLE", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "RECORDDATE", - "type": "DATE", - "canImport": true, - "selected": true, - "isLinkedActive": true - } - ], - "relationships": [] - } - ] - } - ] - } - ], - "tables": [], - "selectedTables": [], - "selectedColumns": [], - "configuration": { - "password": "", - "database": "RETAILAPPAREL-DEV", - "role": "PUBLIC", - "accountName": "coa41300.us-east-1", - "warehouse": "DEMO_WH", - "user": "tsuser" - } -} ----- -==== - -.Sample response without column data -[%collapsible] -==== -[source,JSON] ----- -{ - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "externalDatabases": [ - { - "name": "RETAILAPPAREL", - "isAutoCreated": false, - "schemas": [ - { - "name": "INFORMATION_SCHEMA", - "tables": [ - { - "name": "APPLICABLE_ROLES", - "type": "VIEW", - "description": "The roles that can be applied to the current user.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "COLUMNS", - "type": "VIEW", - "description": "The columns of tables defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "DATABASES", - "type": "VIEW", - "description": "The databases that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "ENABLED_ROLES", - "type": "VIEW", - "description": "The roles that are enabled to the current user.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "EXTERNAL_TABLES", - "type": "VIEW", - "description": "The external tables defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "FILE_FORMATS", - "type": "VIEW", - "description": "The file formats defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "FUNCTIONS", - "type": "VIEW", - "description": "The user-defined functions defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "INFORMATION_SCHEMA_CATALOG_NAME", - "type": "VIEW", - "description": "Identifies the database (or catalog, in SQL terminology) that contains the information_schema", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "LOAD_HISTORY", - "type": "VIEW", - "description": "The loading information of the copy command", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "SCHEMATA", - "type": "VIEW", - "description": "The schemas defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - } - ] - }, - { - "name": "PUBLIC", - "tables": [ - { - "name": "FACT_RETAPP_SALES", - "type": "TABLE", - "description": "", - "selected": true, - "linked": true, - "columns": [], - "relationships": [] - } - ] - } - ] - } - ], - "tables": [], - "selectedTables": [], - "selectedColumns": [], - "configuration": { - "password": "", - "database": "RETAILAPPAREL-DEV", - "role": "PUBLIC", - "accountName": "coa41300.us-east-1", - "warehouse": "DEMO_WH", - "user": "tsuser" - } -} ----- -==== - -=== Response codes - -[width="100%" cols="1,4"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful operation -| **400** -| Invalid parameter values -| **500** -| Invalid connection object ID -|=== - -[#fetchLiveColums] -== Get column data for connections with external tables - -To get column data for a connection with external tables, send a `POST` request to the `/tspublic/v1/connection/fetchLiveColumns` endpoint. - -=== Resource URL - ----- -POST /tspublic/v1/connection/fetchLiveColumns ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form Data Parameter|Description -|`connection_id` + a|__String__. GUID of the data connection. -|`tables` + a|__String__. The external tables to include in the output. The `tables` string allows you to fetch one or several tables from multiple external databases. - -* To get column data for a specific table, specify the string as shown here: + -`[{"tableName":"PIPES"}]` -* To get column data for multiple tables, specify the string as shown here: + -`[{"tableName":"PIPES"},{"tableName":"STAGES"},{"tableName":"SEQUENCES"}]` -* To get column data for tables with a specific schema, specify the string as shown here: + -`[{"databaseName":"RETAILAPPAREL","schemaName":"INFORMATION_SCHEMA"}]` -* To get column data for a specific table from a specific database, specify the string as shown here: + -`[{"databaseName":"RETAILAPPAREL","tableName":"PIPES"}]` -* To get column data for a specific table in an external database with a schema, specify the string as shown here: + -`[{"databaseName":"RETAILAPPAREL","schemaName":"INFORMATION_SCHEMA","tableName":"PIPES"}]` -* To get column data for multiple tables in a specific database, you can specify the string as shown here: + -`[{"databaseName": "RETAILAPPAREL"},{"tableName": "PIPES"},{"tableName":"STAGES"},{"tableName": "SEQUENCES"}]` -* To get column data for specific tables from multiple databases, you can specify the `tables` string as shown here: + -`[{"databaseName": "RETAILAPPAREL","tableName": "PIPES"},{"databaseName": "RETAILAPPAREL-DEV","tableName": "STAGES"}]` - -|`config` + -__Optional__ a|__String__. Configuration attributes to override the metadata details in the API response. Use this attribute to query data from a specific database. For example, if your connection has a database named `PROD`, and you want to fetch details with the database name as `DEVELOPMENT`, you can define the `config` string as `{"database":"DEVELOPMENT"}`. - -[IMPORTANT] -==== -Note that the `config` attribute does not update the connection metadata in the ThoughtSpot system. It only allows you to modify the metadata in the API response. To update the connection metadata, you must use the `/tspublic/v1/connection/update` endpoint. -==== -|`authentication_type` + a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + - -* `SERVICE_ACCOUNT` __Default__ + -For data connections that require service account credentials to authenticate to the Cloud Data Warehouse and fetch data. - -* `OAUTH` + -For data connections that require OAuth credentials to authenticate to the Cloud Data Warehouse and fetch data. + -ThoughtSpot data connections to Teradata, Oracle, and Presto Cloud Data Warehouse do not support the `OAuth` authentication type. - -* `IAM` + -For data connections that have the IAM OAuth set up. This authentication type is supported on Amazon Redshift connections only. - -* `EXTOAUTH` + -For data connections that have external OAuth set up. ThoughtSpot supports external OAuth with Microsoft Azure Active Directory (AD) and Okta for Snowflake data connections. For more information, see link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-okta-oauth[Configure Okta OAuth for a Snowflake connection, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-azure-ad-oauth[Configure Azure AD external OAuth for a Snowflake connection, window=_blank]. -|==== - -=== Example request - -.cURL - -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'connection_id=2aa36dbd-dda6-4497-a6db-bc47e128862e&tables=[{"tableName":"PIPES"},{"tableName":"STAGES"},{"tableName":"SEQUENCES"}]&config={"database":"DEVELOPMENT"}' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchLiveColumns' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchLiveColumns ----- - -=== Example response - -.Sample response with a single table - -[%collapsible] -==== -[source,JSON] ----- -{ - "..PIPES": [ - { - "name": "PIPE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ] -} ----- -==== - -.Sample response with multiple tables -[%collapsible] -==== -[source,JSON] ----- -{ - "..STAGES": [ - { - "name": "STAGE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_URL", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_REGION", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "..PIPES": [ - { - "name": "PIPE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "..SEQUENCES": [ - { - "name": "SEQUENCE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATA_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ] -} ----- -==== - -.Sample response with tables associated to a specific schema -[%collapsible] -==== -[source,JSON] ----- -{ - "RETAILAPPAREL.INFORMATION_SCHEMA.": [ - { - "name": "GRANTEE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROLE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROLE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_GRANTABLE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "TABLE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "TABLE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "TABLE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "COLUMN_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATA_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DOMAIN_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DOMAIN_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DOMAIN_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATABASE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATABASE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_TRANSIENT", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_URL", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_REGION", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ] -} ----- -==== - -.Sample response with a single table from a specific database -[%collapsible] -==== -[source,JSON] ----- -{ -"RETAILAPPAREL..PIPES": [ -{ -"name": "PIPE_CATALOG", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_SCHEMA", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_NAME", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_OWNER", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "DEFINITION", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "CREATED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "LAST_ALTERED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -} -] -} ----- -==== - -.Sample response with multiple tables from one or more external databases - -[%collapsible] -==== -[source,JSON] ----- -{ -"RETAIL.INFORMATION_SCHEMA.PIPES": [ -{ -"name": "PIPE_CATALOG", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_SCHEMA", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_NAME", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_OWNER", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "DEFINITION", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "CREATED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "LAST_ALTERED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "COMMENT", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PATTERN", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -} -], -"RETAILCLOUD.INFORMATION_SCHEMA.STAGES": [ - { - "name": "STAGE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_URL", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_REGION", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } -] -} ----- -==== - -=== Response codes -[width="100%" cols="1,4"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful operation -| **400** -| Invalid connection ID -| **500** -| Invalid string format -|=== - - -[#export-connections] -== Export a connection map - -To export the metadata of an active connection map, send a `GET` request to the `/tspublic/v1/connection/export` API. - -=== Resource URL ----- -GET /tspublic/v1/connection/export ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Query parameter|Description -|`id` + a|__String__. The GUID of the data connection you want to export. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X GET ---header 'Accept: text/yaml' ---header 'X-Requested-By: ThoughtSpot' -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/export?id=627c35cb-768d-45c7-b41d-346a2220cd82' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/export?id=627c35cb-768d-45c7-b41d-346a2220cd82 ----- -=== Example response - -If the specified GUID is valid and points to an existing data connection on your cluster, the API returns a YAML file containing the connection mapping data. - -Click the link in the `Response body` to download the YAML file. - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful export of the connection object -| **401** -| Unauthorized request or wrong credentials - -| **500** -| Invalid connection ID -|=== - -[#del-connection] -== Delete a data connection - -To delete a data connection, send a `POST` request to the `/tspublic/v1/connection/delete` API. - -[IMPORTANT] -==== -A connection can be used in multiple data sources or visualizations. If a data connection has dependent objects, make sure you remove its associations before running the delete operation. -==== - -=== Resource URL ----- -POST /tspublic/v1/connection/delete ----- -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form parameter|Description -|`ids` + a|__Array of Strings__. A JSON array of data connection GUIDs to delete. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'ids=%5B%229114f105-fc9e-48c9-a8f1-57f2fda4f056%22%5D' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/delete' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/delete ----- - -=== Example response - -If the connection deletion is successful, the following response code is returned: - ----- -Response Code -204 ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **204** -|Successful deletion of the connection object - -| **401** -| Unauthorized request or wrong credentials - -| **500** -| The connection could not be deleted due to table dependencies -|=== - diff --git a/modules/ROOT/pages/org-manage-api.adoc b/modules/ROOT/pages/org-manage-api.adoc index efea5a898..27679ef1d 100644 --- a/modules/ROOT/pages/org-manage-api.adoc +++ b/modules/ROOT/pages/org-manage-api.adoc @@ -17,9 +17,9 @@ include::{path}/rest-apiv1-deprecation-note.adoc[] If you do not see the Orgs feature enabled on your instance, contact ThoughtSpot Support. . Log in to your application instance as an administrator. -. Create Orgs in the *Admin* page of the UI or via xref:org-api.adoc#createOrg[REST API]. +. Create Orgs in the *Admin* page of the UI or via #the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Forgs%2Fcreate-org[`POST /api/rest/2.0/orgs/create`] endpoint#. + -To create and manage Orgs, you must set the Org context to `All`. To do this, you can switch to the *All Orgs* tab in the Admin page of UI or pass the Org scope `ALL` in your API requests to Orgs API endpoints. For more information, see xref:org-api.adoc[Org API]. +To create and manage Orgs, you must set the Org context to `All`. To do this, you can switch to the *All Orgs* tab in the Admin page of UI or pass the Org scope `ALL` in your API requests to Orgs API endpoints. #For more information, see <<_create_and_manage_orgs,Org management operations>>.# . Create users and map the users to Orgs. + You can create an administrator profile for each Org and let these Org administrators manage users, groups, and role privileges in their respective Orgs. @@ -35,55 +35,28 @@ To create an Org on a multi-tenant ThoughtSpot instance, you need cluster admini === REST API v2.0 endpoints -For Orgs CRUD operations, you can also use the following REST API v2.0 Org endpoints: +#For Orgs CRUD operations, use the following REST API v2.0 Org endpoints:# * +++/api/rest/2.0/orgs/create+++ * +++ /api/rest/2.0/orgs/search+++ * +++/api/rest/2.0/orgs/{org_identifier}/update +++ * +++ /api/rest/2.0/orgs/{org_identifier}/delete+++ -//// -=== REST API v1 endpoints - -For Orgs CRUD operations, use the xref:org-api.adoc[`/tspublic/v1/org/`] endpoints. To access Org API endpoints, you must log in to ThoughtSpot as a cluster administrator: - -Note that for all Org operations, you must set the org scope to `ALL` in your API request and pass it as a query parameter in the request URL. - -* To create an Org, send a xref:org-api.adoc#createOrg[`POST` request to the `/tspublic/v1/org/` endpoint] with the Org name and description text in the request body. -+ -If the API operation is successful, ThoughtSpot creates an Org and assigns a system-generated number as Org ID. -* To view the Orgs configured on a ThoughtSpot instance, use the xref:org-api.adoc#getOrgs[`/tspublic/v1/org/search`] or xref:org-api.adoc#getOrg[`GET /tspublic/v1/org/`] API endpoint. -* To edit the properties of an Org object, use the xref:org-api.adoc#editOrg[`PUT /tspublic/v1/org/`] endpoint. -+ -The `PUT` request allows modifying the name and description properties of an Org object. -* To delete an Org object, send a `DELETE` request to the xref:org-api.adoc#deleteOrg[`/tspublic/v1/org/` endpoint] with Org ID or name in the request body. -//// - == Manage users and groups On a multi-tenant instance, the cluster and Org administrators can create users and associate these users to Orgs and groups within these Orgs. The cluster administrator can perform CRUD operations on Org objects at the All Orgs level and assign users, whereas the Org administrator can create users and groups within the context of their Org workspace. [NOTE] ==== -The xref:session-api.adoc#orgSwitch[`/tspublic/v1/session/orgs`] REST API v1 endpoint allows administrators to switch between Org contexts. For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests. +#For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests.# ==== -[width="100%" cols="5,8,7"] +[width="100%" cols="5,15"] [options='header'] |===== -|Operation type|REST API v1 endpoints|REST API v2 endpoints - -|Authentication a| -**Basic authentication** + -To log in to a specific Org context with basic authentication, specify the Org ID in the xref:session-api.adoc#session-login[`/tspublic/v1/session/login`] API request. +|#Operation type#|#REST API v2 endpoints# -**Token-based authentication** + -For xref:trusted-authentication.adoc[trusted authentication], use the xref:session-api.adoc#session-authToken[`/tspublic/v1/session/auth/token`] API endpoint. If a user is mapped to a specific org, you can pass the `orgid` in the API request to obtain an authentication token to log in the user to the relevant Org context. + -You can also create a user just-in-time and assign Orgs, groups, and privileges in this API call. - -For more information, see xref:api-auth-session.adoc[REST API v1 authentication]. - -a| **Basic authentication** + +|Authentication a| **Basic authentication** + To log in to a specific Org context with basic authentication, specify the Org ID in the +++ /api/rest/2.0/auth/session/login +++ API request. **Token-based authentication** + @@ -94,22 +67,13 @@ Use the following API endpoints: These above endpoints also support just-in-time provisioning of users to Orgs and groups. For more information, see xref:authentication.adoc[REST API v2 authentication]. -|User provisioning a|To create users, use the xref:user-api.adoc#create-user[`POST /tspublic/v1/user/`] API endpoint. This endpoint also allows assigning a user to Orgs. + - -To add multiple users to an Org in bulk, use the xref:user-api.adoc#addOrg[`/tspublic/v1/user/addtoorg`] API endpoint. + - -To remove a user from an Org, use the xref:user-api.adoc#delete-user[`DELETE /tspublic/v1/user/{userid}`] endpoint. If a user belongs only to the Org specified in the `DELETE` request, the user will be deleted from the Org and ThoughtSpot system. If the user belongs to more than one Org, the `DELETE` operation removes the user from only the Org specified in the API request. To remove the user from the ThoughtSpot system and all Orgs, you must set the `orgid` to `-1` in your API request. -|To create users and assign users to one or several Orgs, use the +++ /api/rest/2.0/users/create +++ API endpoint. + +|User provisioning a|To create users and assign users to one or several Orgs, use the +++ /api/rest/2.0/users/create +++ API endpoint. + To assign an existing user to new Orgs or remove a user from an Org, use the +++ /api/rest/2.0/users/{user_identifier}/update +++ API endpoint. -|Group provisioning a|To create a group in an Org, log in to the Org context or xref:session-api.adoc#orgSwitch[switch to the Org context] and send an API request to the xref:group-api.adoc#create-group[`/tspublic/v1/group/`] endpoint. -a|To create a group in an Org, use the +++ /api/rest/2.0/groups/create +++ API endpoint. - -|Fetching Orgs a| * To get a list of Orgs for the currently logged-in user, use the xref:session-api.adoc#getOrgs[/tspublic/v1/session/orgs] API endpoint. + +|Group provisioning a|To create a group in an Org, use the +++ /api/rest/2.0/groups/create +++ API endpoint. -* To get Orgs for a specific user, use the xref:session-api.adoc#getOrgsForUser[/tspublic/v1/session/orgs/users/{userid}] endpoint. Set the Org scope to `ALL` to get all Orgs for a given user. -a| The REST API v2 endpoints allow you to perform query operations to get Org details: +|Fetching Orgs a| The REST API v2 endpoints allow you to perform query operations to get Org details: * To get a list of all Orgs on the cluster, use +++/api/rest/2.0/orgs/search +++ (Requires cluster administrator privileges) diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index a7620633d..a6a9e2f28 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -6,7 +6,7 @@ :page-pageid: rest-apiv2-metadata-search :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. +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. == Overview @@ -94,7 +94,7 @@ The response from any call to `metadata/search` returns an array of link:https:/ You'll notice a number of other keys with a `null` value. Various request parameters cause those sections of the response to be filled in with additional details. -The `metadata_header` key is always returned with values, regardless of the request. This section resembles the V1 REST API response from the xref:metadata-api.adoc#metadata-list[`metadata/list`] and xref:metadata-api.adoc#object-header[`metadata/listobjectheaders`] endpoints. +The `metadata_header` key is always returned with values, regardless of the request. The value of `metadata_header` is a complex object with the most important set of attributes of the item. Note that `author` is the creator or current user who has been assigned the __ownership__ of the object, while `owner` describes a hierarchical relationship between ThoughtSpot objects (for example, this Liveboard has an `owner` property identical to its own `id` property): @@ -3574,7 +3574,7 @@ If you need multiple levels of sorting, you'll have to parse the response progra === permissions You can filter responses based on who can access the object, that is, who the content has been shared to, using the `permissions` parameter. -While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint for a full listing, which replaces the individual `security` endpoints in the v1 REST API, such as the xref:security-api.adoc#obj-permission-all[get object permission details for a specific object type] endpoint. +While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint #for a full listing.# The `permissions` object takes an array of objects that define a `principal` and a `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fenumerations%2Fshare-mode[share_mode, target=_blank]`. `principal` is an object with a `type` of `USER` or `USER_GROUP` and an `identifier`, either the name or the GUID of the principal: @@ -3695,12 +3695,10 @@ The `exclude_objects` parameter takes an array of objects that can exclude items ---- == Additional response details -There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to answer questions that require multiple API calls in the v1 REST API. +There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint #to return related details in a single API call.# === include_visualization_headers -The v1 REST API endpoint xref:metadata-api.adoc#viz-header[`metadata/listvizheaders`] retrieves the header details of all individual visualizations on a Liveboard. - -In v2, the `include_visualization_headers` parameter adds the visualization headers to the response. +#The `include_visualization_headers` parameter adds the header details of all individual visualizations on a Liveboard to the response.# [source,JSON] ---- @@ -3719,9 +3717,7 @@ Note from above that the response to **every** request has the `visualization_he The `include_visualization_headers` adds the array of visualization headers for every element in the response, so you can request a list of all Liveboards and all the visualizations on those Liveboards all at once. === include_details -The v1 REST API has an endpoint called `metadata/details` for retrieving a very large and complex object containing as much detail as possible about the requested object and its relationships with other objects within ThoughtSpot. - -The `include_details` parameter in the `metadata/search` API request adds the equivalent details object to each element retrieved by `metadata/search` to the response under the `metadata_detail` key. +The `include_details` parameter in the `metadata/search` API request adds #a detailed object, with as much detail as possible about each requested object and its relationships with other objects within ThoughtSpot,# to each element retrieved by `metadata/search` to the response under the `metadata_detail` key. [source,JSON] ---- @@ -3830,9 +3826,7 @@ Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects* An object can only be deleted if all of its dependent objects are deleted first. -The v1 REST API had an entire set of xref:dependency-apis.adoc[dependent objects APIs] for retrieving these relationships. - -The equivalent information is retrieved from `metadata/search` by setting the `include_dependent_objects` parameter to `true`: +#To retrieve these relationships from `metadata/search`, set the `include_dependent_objects` parameter to `true`:# [source,JSON] ---- diff --git a/modules/ROOT/pages/rest-api-v2-search.adoc b/modules/ROOT/pages/rest-api-v2-search.adoc index 208d16cfd..f0de4a393 100644 --- a/modules/ROOT/pages/rest-api-v2-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-search.adoc @@ -8,7 +8,7 @@ The REST API v2 endpoints that end in `/search` have very flexible request formats that solve a number of use cases. -Some capabilities that have separate endpoints in the V1 REST API are done using the correct request on the smaller subset of `/search` endpoints in v2.0. +#A small set of `/search` endpoints covers many capabilities, depending on the request parameters you send.# Note that many parameters in the requests are *optional*, and leaving the parameter name out entirely has a different effect from including the parameter and specific values. @@ -25,7 +25,7 @@ Assume every request you see has the following parameters in addition to what is ---- == Search metadata -The `/metadata/search` endpoint in the V2 REST API replaces a large set of distinct endpoints in REST API V1. +#The `/metadata/search` endpoint retrieves metadata objects and their details, such as headers, permissions, and dependent objects.# For more information about this API, xref:rest-api-v2-metadata-search.adoc[Search metadata]. diff --git a/modules/ROOT/pages/rest-api-v2-users-search.adoc b/modules/ROOT/pages/rest-api-v2-users-search.adoc index 1d7ebcb58..7ad9e269c 100644 --- a/modules/ROOT/pages/rest-api-v2-users-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-users-search.adoc @@ -144,8 +144,6 @@ If you need multiple levels of sorting, you'll have to parse the response progra === group_identifiers You can filter responses based on which groups the user belongs to. -This replaces some of the individual group endpoints in the V1 REST API, such as the xref:group-api.adoc#get-users-group[`/tspublic/v1/group/listuser/{groupid}`] endpoint. - The `group_identifiers` parameter takes an array of strings of either **group name** or **group GUID**. Note that groups have a `display_name` property which is different from **group_name** and cannot be used in the `group_identifiers` array. [source,JSON] @@ -254,7 +252,7 @@ The `notify_on_share`, `show_onboarding_experience`, and `onboarding_experience_ Note that the *absence* of the parameter is how you remove the filtering. If the parameter value is present as a key, the value must be set to `true` or `false`, so that the response can be filtered to get only those users that match the condition. == Additional response details -There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to answer questions that require multiple API calls in the V1 REST API. +There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint #to return related details in a single API call.# === include_favorite_metadata The `user` object in the response always includes a `favorite_metadata` key, but it will always be an empty array unless the `include_favorite_metadata` parameter is added to the request set to `true`: diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index 4ee8fb39d..e51afc451 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -196,37 +196,7 @@ UI: **Can download Data**| Allows users to download data from objects such as Li == How to create and assign Roles -You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the REST API v1 and v2 endpoints. - -=== REST API v1 endpoints for Role administration and assignment - -[width="100%" cols="2,4"] -[options='header'] -|=== -|Operation type|API endpoints -|CRUD operations -a| To create, edit, and manage Role objects, use the following endpoints: - -* xref:roles-api.adoc#createRole[`POST /tspublic/v1/role`] + -Create a Role -* xref:roles-api.adoc#editRole[`PUT /tspublic/v1/role/{role_identifier}`] + -Edit properties of a Role object. -* xref:roles-api.adoc#searchRole[`POST /tspublic/v1/role/search`] + -Get a list of Role objects -* xref:roles-api.adoc#deleteRole[`DELETE /tspublic/v1/role/{role_identifier}`] + -Delete a Role object -|Role assignment to groups a| * xref:group-api.adoc#addRole[`POST /tspublic/v1/group/addrole`] + -Allows group administrators to assign a specific Role to a group -* xref:group-api.adoc#create-group[`/tspublic/v1/group/`] + -Allows group administrators to assign one or several Roles to a group -* xref:group-api.adoc#removeRole[`POST /tspublic/v1/group/removerole`] + -Removes the Roles assigned to a group -* xref:group-api.adoc#update-group[`PUT /tspublic/v1/group/{groupid}`] + -Edit Role associations of a group object -|Object query|To get the details of Roles assigned to a group object, use the following API endpoint: -* xref:group-api.adoc#get-users-group[`GET /tspublic/v1/group/`] + -Note that the API response shows the assigned Roles and privileges in the `assignedRoles` and `granularPrivileges` arrays. -|=== +You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the #REST API v2 endpoints#. === REST API v2 endpoints for Role administration and assignment diff --git a/modules/ROOT/pages/runtime-sort.adoc b/modules/ROOT/pages/runtime-sort.adoc index 136026a8c..ac8033a58 100644 --- a/modules/ROOT/pages/runtime-sort.adoc +++ b/modules/ROOT/pages/runtime-sort.adoc @@ -161,25 +161,3 @@ curl -X POST \ } } ---- - -=== REST API v1 (Legacy endpoints) - -If you are using REST API v1 endpoints, runtime sorts can be applied when fetching a Liveboard or Answer object from ThoughtSpot. - -To sort columns when fetching data from a Liveboard object, add sort properties to the Liveboard data API request URL as shown in the example here: - ----- -http://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false ----- ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false&sortCol2=Tea ----- - -To sort columns of an Answer object, add the sort attributes to the search data API request URL as shown in the following examples: ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false ----- - ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false&sortCol2=Tea ----- From 7b6fc510c5611e3069927dc5aca5da29779909d0 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 6 Oct 2026 22:04:47 +0530 Subject: [PATCH 008/169] v1 API cleanup --- .idea/.gitignore | 3 --- .idea/developer-docs.iml | 9 --------- .idea/misc.xml | 6 ------ .idea/modules.xml | 8 -------- .idea/vcs.xml | 6 ------ 5 files changed, 32 deletions(-) delete mode 100644 .idea/.gitignore delete mode 100644 .idea/developer-docs.iml delete mode 100644 .idea/misc.xml delete mode 100644 .idea/modules.xml delete mode 100644 .idea/vcs.xml diff --git a/.idea/.gitignore b/.idea/.gitignore deleted file mode 100644 index 26d33521a..000000000 --- a/.idea/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -# Default ignored files -/shelf/ -/workspace.xml diff --git a/.idea/developer-docs.iml b/.idea/developer-docs.iml deleted file mode 100644 index d6ebd4805..000000000 --- a/.idea/developer-docs.iml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml deleted file mode 100644 index 639900d13..000000000 --- a/.idea/misc.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index aff6e430d..000000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 35eb1ddfb..000000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - \ No newline at end of file From e0ee01c2544793e450a54927e9bdd940ac615c3f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 7 Oct 2026 10:35:33 +0530 Subject: [PATCH 009/169] v1 cleanup --- modules/ROOT/pages/api-user-management.adoc | 47 ++++++++++++++++++- modules/ROOT/pages/authentication.adoc | 13 +++++ modules/ROOT/pages/connections.adoc | 19 ++++++-- modules/ROOT/pages/data-apis-v2.adoc | 4 +- modules/ROOT/pages/org-manage-api.adoc | 16 ++++++- modules/ROOT/pages/report-apis-v2.adoc | 41 +++++++++++----- .../pages/rest-api-v2-metadata-search.adoc | 9 ++++ modules/ROOT/pages/roles.adoc | 6 ++- modules/ROOT/pages/tml-export.adoc | 2 +- modules/ROOT/pages/tml-import.adoc | 14 +++--- modules/ROOT/pages/tml.adoc | 4 +- 11 files changed, 142 insertions(+), 33 deletions(-) diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index 4989e7a95..d21949c07 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -18,12 +18,35 @@ When configuring xref:configure-saml.adoc[SAML SSO] in ThoughtSpot UI, you can s By default, ThoughtSpot sends e-mail messages to a new user and enables onboarding workflows when they log in for the first time, even when you are embedding ThoughtSpot content. To alter this behavior at a system-wide level, you need to xref:customize-email-settings.adoc[Customize the onboarding settings]. The user update API also allows setting onboarding experience values for an individual user. If you need to modify the default behavior beyond the available UI options, contact your ThoughtSpot team. +#To specify whether an activation email is sent to a new user, set the `trigger_activation_email` parameter in the `POST /api/rest/2.0/users/create` request.# [NOTE] ==== ThoughtSpot supports local management of users. For initial development and testing purposes, you can create users in ThoughtSpot and manage their profiles locally. However, in large production environments, avoid creating local user profiles to reduce administration overhead. ==== +=== #Required privileges# +#To create, edit, or delete users, assign users to groups, transfer objects from one user to another, or activate, deactivate, or log out users, you need administrator privileges (`ADMINISTRATION`).# + +#If Role-Based Access Control (RBAC) is enabled on your instance, the `USER_ADMINISTRATION` (*Can manage users*) privilege is required. On instances with Orgs, this privilege allows managing users only within the Org context of the API request. For more information, see xref:roles.adoc[Role-based access control].# + +=== #User attributes# +#Note the following points about user attributes:# + +* #*Username*: The username must be unique. An API request to create a user with a username that already exists returns an error.# +* #*Account type*: The `account_type` attribute indicates how the user was created and how the user authenticates. Valid values are:# +** #`LOCAL_USER`: A user created and authenticated locally in ThoughtSpot. This is the default account type.# +** #`LDAP_USER`: A user imported from an LDAP server.# +** #`SAML_USER`: A user authenticated through SAML SSO.# +** #`OIDC_USER`: A user authenticated through OpenID Connect (OIDC).# +** #`REMOTE_USER`: A user authenticated by an external system.# ++ +#When users are imported from an external server, such as an LDAP server or an IdP, ThoughtSpot assigns the account type automatically. For example, a user imported from an LDAP server is added as `LDAP_USER`.# +* #*Visibility*: The `visibility` attribute determines whether other users can share objects with the user. By default, users are set to `SHARABLE`, which allows other users and groups to share objects with them. To prevent other users from finding the user and sharing objects with them, set `visibility` to `NON_SHARABLE`. In multi-tenant deployments, users are commonly set to `NON_SHARABLE`.# + +=== #Password reset# +#After you reset a user's password with the `POST /api/rest/2.0/users/reset-password` endpoint, you can log the user out of their active sessions by using the `POST /api/rest/2.0/users/force-logout` endpoint. The user must then log in again with the new password.# + //// === User account status @@ -107,7 +130,7 @@ ThoughtSpot is gradually migrating its users to link:https://docs.thoughtspot.co * The `email` attribute is mandatory when creating a user in ThoughtSpot Okta. ThoughtSpot recommends that users provide a valid email address during user creation. * You must set a password during user creation if you do not want to trigger an activation email. -* The default value for `usertype` will be `OIDC_USER`. +* The default value for #`account_type`# will be `OIDC_USER`. Administrators can manage the user account status for all users. For IAMv2 users, the API response for the following APIs will also include `SUSPENDED` as a user state: @@ -167,13 +190,22 @@ For more information, see the following pages: == User group creation and update #Groups can be created via the xref:rest-api-v2-reference.adoc#_groups[REST API v2 group endpoints].# +#To create, edit, or delete groups, you need administrator privileges. If RBAC is enabled on your instance, the `GROUP_ADMINISTRATION` (*Can manage groups*) privilege is required. To assign Roles to a group or remove Roles from a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges.# + The xref:api-user-management.adoc#group-privileges[Group privileges] are set directly on groups, either during group creation or via a group update API call. +=== #Group hierarchy# +#ThoughtSpot supports hierarchical groups. You can create a parent group and add other groups to it as sub-groups. For example, you can create a parent group called `Site` and add your tenant groups to it. Sub-groups inherit the privileges of the parent group.# + +#To add sub-groups to a group or remove sub-groups from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint. Removing a sub-group from a group removes only the association; it does not delete the sub-group from ThoughtSpot.# + == User association to groups -You can add users to specific groups when creating a user or group via REST API endpoints. +You can add users to specific groups when creating a user or group via REST API endpoints. #When you assign a user to a group, the user inherits the privileges and Roles assigned to that group.# #To add users to an existing group or remove users from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint with the `user_identifiers` parameter and the `ADD`, `REMOVE`, or `REPLACE` operation. To update the groups of a single user, use the +++POST /api/rest/2.0/users/{user_identifier}/update+++ endpoint with the `group_identifiers` parameter.# +#Removing a user from a group removes only the group association; it does not delete the user from ThoughtSpot. To delete a user, use the +++POST /api/rest/2.0/users/{user_identifier}/delete+++ endpoint.# + #To get a list of users assigned to a group, use the +++POST /api/rest/2.0/groups/search+++ endpoint.# == Access control (sharing) @@ -181,6 +213,17 @@ Access to objects is determined by content *shared* directly to the user or the Users can share objects or modify sharing properties through the UI or via an API call to the #`POST /api/rest/2.0/security/metadata/share` endpoint#. +#Note the following points about sharing objects via REST API:# + +* #To share an object, you must have edit access to the object.# +* #The `share_mode` attribute can be set to `READ_ONLY` (*Can view*), `MODIFY` (*Can edit*), or `NO_ACCESS`. Setting `share_mode` to `NO_ACCESS` removes any access previously granted to a user or group.# +* #To send a share notification to the users and groups with whom the object is shared, set `notify_on_share` to `true`.# +* #To make a shared Liveboard or Answer discoverable, set `has_lenient_discoverability` to `true`.# + +#To audit access, use the `POST /api/rest/2.0/security/metadata/fetch-permissions` endpoint to get the users and groups that have access to an object, or the `POST /api/rest/2.0/security/principals/fetch-permissions` endpoint to get the objects a user or group can access.# + +#For more information and examples, see xref:access-control-sharing.adoc[Access control and sharing].# + [#group-privileges] == Group privileges Each user group includes a set of privileges for its users. When a user is assigned to a group in ThoughtSpot, the default privileges associated with a group are assigned to its users. The group privileges allow users belonging to a group to perform specific operations and access workflows. If a user belongs to more than one group, they will have the highest level of privileges from all the groups they belong to. diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 6e72126ab..5b922944c 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -972,6 +972,17 @@ If the API request is successful, ThoughtSpot returns the following response: |**500**|Failed operation |=== //// +[#switch-org] +== #Switching Org context# +#On ThoughtSpot instances with Orgs, only cluster administrators and users who belong to more than one Org can switch between Orgs.# + +#For REST API v2 requests, the Org context is determined by the session or token used in the request. To send API requests in a different Org:# + +* #For cookie-based authentication, log in again by sending a request to the `/api/rest/2.0/auth/session/login` endpoint with the ID or name of the Org in the `org_identifier` attribute.# +* #For token-based authentication, request a new token with the ID of the Org in the `org_id` attribute, or use a <>.# + +#To view the Org context of the current session and the Orgs available to the user, send a request to the `/api/rest/2.0/auth/session/user` endpoint and check the `current_org` and `orgs` properties in the API response. For more information, see <<_viewing_session_information,Viewing session information>>.# + == Logging out of a session To log out of your current session, send a `POST` request to the `/api/rest/2.0/auth/session/logout` API endpoint. @@ -986,6 +997,8 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' ---- +#If you send the logout request as an AJAX call from a browser with cookie-based authentication, include credentials in the request so that the session cookie is sent. For example, set `xhrFields: { withCredentials: true }` in a jQuery AJAX request, or `credentials: 'include'` in a Fetch API request.# + === API response If the API request is successful, ThoughtSpot returns a 204 status code and ends the user session. diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index ca0b2e3ea..ddf1dcfd4 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -585,8 +585,7 @@ To create or modify data connections through REST APIs, you need to provide a ma } ] } - ] -} + ], "validate": true } ---- @@ -607,13 +606,25 @@ To create or modify data connections through REST APIs, you need to provide a ma }, "externalDatabases":[ - ] -} + ], "validate": false } ---- +[#export-connection] +== #Export a connection# +#To export a connection, export its TML by using the `POST /api/rest/2.0/metadata/tml/export` endpoint. To include the Tables of the connection in the export, set `export_dependent` to `true`. For more information, see xref:tml-export.adoc[Export TML].# + +[#delete-connection] +== #Delete a connection# +#To delete a connection, use the `POST /api/rest/2.0/connections/{connection_identifier}/delete` endpoint.# + +[IMPORTANT] +==== +#A connection can be used by multiple Tables, Models, and visualizations. If a connection has dependent objects, remove the dependent objects or their associations before you delete the connection.# +==== + == Integrate with dbt ThoughtSpot’s dbt sync allows you to easily provide your existing dbt models and automatically create ThoughtSpot Worksheets, which you can use to search your data. Integration with dbt is certified only for Amazon Redshift, Databricks, Google BigQuery, and Snowflake connections. diff --git a/modules/ROOT/pages/data-apis-v2.adoc b/modules/ROOT/pages/data-apis-v2.adoc index bf259489d..2670cd006 100644 --- a/modules/ROOT/pages/data-apis-v2.adoc +++ b/modules/ROOT/pages/data-apis-v2.adoc @@ -82,6 +82,8 @@ curl -X POST \ }' ---- +#To verify your query string, run an equivalent search in the ThoughtSpot UI search bar and check whether it returns the same data. Note that the search syntax in the UI differs slightly from the query string syntax.# + //// === Using tokens generated from Spotter APIs as raw data @@ -113,7 +115,7 @@ If the API request is successful, ThoughtSpot returns the Answer data for the qu == Fetch Liveboard Data API To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. #If `visualization_identifiers` is not specified, the API returns data for all visualizations on the Liveboard.# === Liveboard data request example [source,cURL] diff --git a/modules/ROOT/pages/org-manage-api.adoc b/modules/ROOT/pages/org-manage-api.adoc index 27679ef1d..06644b07e 100644 --- a/modules/ROOT/pages/org-manage-api.adoc +++ b/modules/ROOT/pages/org-manage-api.adoc @@ -40,7 +40,21 @@ To create an Org on a multi-tenant ThoughtSpot instance, you need cluster admini * +++/api/rest/2.0/orgs/create+++ * +++ /api/rest/2.0/orgs/search+++ * +++/api/rest/2.0/orgs/{org_identifier}/update +++ -* +++ /api/rest/2.0/orgs/{org_identifier}/delete+++ +* +++ /api/rest/2.0/orgs/{org_identifier}/delete+++ + +#Note the following points about Org names and descriptions:# + +* #The Org name must be unique and must not exceed 48 characters. The name can contain only letters (a-z, A-Z), digits (0-9), and hyphens (-). Spaces and other special characters are not supported.# +* #The Org description must not exceed 124 characters.# + +=== #Deleting an Org# +[NOTE] +==== +* #ThoughtSpot does not allow deleting the Primary Org (Org 0).# +* #When an Org is deleted, the Org and its objects become inaccessible immediately. However, the objects remain in the ThoughtSpot system for seven days from the deletion date.# +* #To restore a deleted Org, contact ThoughtSpot Support within seven days of deletion.# +* #To remove the objects of a deleted Org before the seven-day period ends, or to reuse a deleted Org name or object names immediately after deletion, contact ThoughtSpot Support.# +==== == Manage users and groups diff --git a/modules/ROOT/pages/report-apis-v2.adoc b/modules/ROOT/pages/report-apis-v2.adoc index a6f42fe91..b7705e344 100644 --- a/modules/ROOT/pages/report-apis-v2.adoc +++ b/modules/ROOT/pages/report-apis-v2.adoc @@ -95,6 +95,15 @@ curl -X POST \ For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. +#The following `pdf_options` attributes determine the content of the PDF:# + +* #`include_cover_page`: Adds a cover page with the Liveboard title.# +* #`include_filter_page`: Adds a page that lists the filters applied to the Liveboard.# +* #`include_custom_logo`: Adds the custom wide logo, if one is configured for your instance, to the footer of each page.# +* #`page_footer_text`: Adds the specified text to the footer of each page.# +* #`include_page_number`: Adds the page number to the footer of each page.# +* #`truncate_table`: Includes only the first page of each table visualization in the PDF.# + 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` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. @@ -232,22 +241,28 @@ include::{path}/transient-lb-content.adoc[] [source,JavaScript] ---- -< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> -< script src = "/path/to/liveboard.js" > < /script> -< script > - const embed = new LiveboardEmbed("#embed", { - frameParams: {}, - }); - async function liveboardData() { +const embed = new LiveboardEmbed("#embed", { + frameParams: {}, + liveboardId: "", +}); + +async function downloadLiveboardReport() { const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); - const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { + const payload = { + metadata_identifier: "", + file_format: "PDF", + transient_content: JSON.stringify(transientPinboardContent.data), + }; + const response = await fetch("https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard", { method: "POST", - body: createFormDataObjectWith({ - "transient_content": transientPinboardContent, - }), + headers: { + Authorization: "Bearer {access-token}", + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), }); - } -< /script> + const file = await response.blob(); +} ---- See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index a6a9e2f28..857815c4f 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -3576,6 +3576,11 @@ You can filter responses based on who can access the object, that is, who the co While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint #for a full listing.# +#The `/security/metadata/fetch-permissions` endpoint supports the following permission types in the `permission_type` attribute:# + +* #`DEFINED`: Returns the access granted to users and groups through object sharing.# +* #`EFFECTIVE`: Returns the access that users have, including the access granted through the privileges of the groups to which they belong.# + The `permissions` object takes an array of objects that define a `principal` and a `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fenumerations%2Fshare-mode[share_mode, target=_blank]`. `principal` is an object with a `type` of `USER` or `USER_GROUP` and an `identifier`, either the name or the GUID of the principal: [source,JSON] @@ -3826,6 +3831,10 @@ Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects* An object can only be deleted if all of its dependent objects are deleted first. +#A dependency is a relationship between a referenced object and the objects that reference it. For example, consider a Model (`Model1`) with a formula column (`Column1`) that refers to a base column (`Column2`). In this example, `Model1` is a referencing object and `Column2` is a referenced object. You cannot delete `Column2` until you delete or modify `Column1` and `Model1`.# + +#Before you delete a data object such as a Table, Model, or column by using the `POST /api/rest/2.0/metadata/delete` endpoint, check whether the object has dependent objects, and remove the dependent objects or their references first.# + #To retrieve these relationships from `metadata/search`, set the `include_dependent_objects` parameter to `true`:# [source,JSON] diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index e51afc451..1e0883bc7 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -198,6 +198,8 @@ UI: **Can download Data**| Allows users to download data from objects such as Li You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the #REST API v2 endpoints#. +#To create and manage Roles, you need the `ROLE_ADMINISTRATION` (*Can manage roles*) privilege. To assign Roles to a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges.# + === REST API v2 endpoints for Role administration and assignment [width="100%" cols="2,4"] @@ -220,8 +222,8 @@ Delete a Role object * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[`POST /api/rest/2.0/groups/{group_identifier}/update`] |Object query a| * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fsearch-roles[`POST /api/rest/2.0/roles/search`] + -To get Roles assigned to specific groups, specify the name or GUID of the Role in the `group_identifiers` attribute. + -Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. +To get Roles assigned to specific groups, specify the name or GUID of the #group# in the `group_identifiers` attribute. + +Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. #If `org_identifiers` is not specified, the API returns the Roles for the Org context from which the API request is sent.# * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups[`POST /api/rest/2.0/groups/search`] + To filter group objects assigned to a particular Role, specify the name or GUID of the Role in the `role_identifiers` attribute. * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fsearch-users[`POST /api/rest/2.0/users/search`] + diff --git a/modules/ROOT/pages/tml-export.adoc b/modules/ROOT/pages/tml-export.adoc index 7bfd58583..60bc3c777 100644 --- a/modules/ROOT/pages/tml-export.adoc +++ b/modules/ROOT/pages/tml-export.adoc @@ -34,7 +34,7 @@ When set to `true`, exports the associated objects for the `export_ids` specifie * `export_dependent` + Specifies if the Tables of the referenced Connection object must be included in the export. * `export_connection_as_dependent` + -Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. +Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. #This attribute works only when `export_associated` is set to `true`.# == Export FQNs diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc index ea1ae5f5e..1e13480b3 100644 --- a/modules/ROOT/pages/tml-import.adoc +++ b/modules/ROOT/pages/tml-import.adoc @@ -27,8 +27,8 @@ To import TML representation of the metadata objects into ThoughtSpot, use the f There are multiple kinds of imports possible: -* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. -* `ALL_OR_NONE` imports the objects that validate successfully. +* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully #and the objects that depend on them#. +* `ALL_OR_NONE` #imports all objects only if all objects validate successfully. If the import fails for one object, no objects are imported.# * `VALIDATE_ONLY` validates the objects but does not import them. * `PARTIAL_OBJECT` imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. @@ -279,8 +279,8 @@ You can import TML objects asynchronously by scheduling TML import tasks via `PO |Form parameter|Description| Default |`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ |`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` -|`all_orgs_context` + +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. #When set to `true`, a `guid` in the imported TML that is already used by another object is replaced with a new GUID. If the `guid` in the imported TML is not used by any other object, ThoughtSpot creates the new object with that `guid`.# | `false` +|#`all_orgs_override`# + __Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. __Requires Org administration privileges to access TML objects across all Orgs.__| `false` @@ -324,7 +324,7 @@ curl -X POST \ "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" ], "create_new": true, - "all_orgs_context": false, + "all_orgs_override": false, }' ---- @@ -537,7 +537,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- . Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the other TML. @@ -550,7 +550,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- + diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index aba737cd2..1f20c1543 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -89,7 +89,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- . Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the otehr TML. @@ -102,7 +102,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- + From be93c1a8a5cc26021b61c169f8939cd367bb59c4 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 7 Oct 2026 14:04:37 +0530 Subject: [PATCH 010/169] v1 cleanup --- modules/ROOT/pages/api-user-management.adoc | 11 +++++++++++ modules/ROOT/pages/audit-logs.adoc | 4 ++-- modules/ROOT/pages/connections.adoc | 1 - modules/ROOT/pages/embed-pinboard.adoc | 2 +- modules/ROOT/pages/liveboard-data-downloads.adoc | 2 +- 5 files changed, 15 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index d21949c07..1d7194cae 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -215,6 +215,7 @@ Users can share objects or modify sharing properties through the UI or via an AP #Note the following points about sharing objects via REST API:# +* #You can share the following types of objects: Liveboards, visualizations, Answers, Models, Views, Connections, and Collections.# * #To share an object, you must have edit access to the object.# * #The `share_mode` attribute can be set to `READ_ONLY` (*Can view*), `MODIFY` (*Can edit*), or `NO_ACCESS`. Setting `share_mode` to `NO_ACCESS` removes any access previously granted to a user or group.# * #To send a share notification to the users and groups with whom the object is shared, set `notify_on_share` to `true`.# @@ -224,6 +225,16 @@ Users can share objects or modify sharing properties through the UI or via an AP #For more information and examples, see xref:access-control-sharing.adoc[Access control and sharing].# +=== #Sharing a visualization# +#Note the following points about sharing a visualization:# + +* #Sharing a visualization implicitly shares the entire Liveboard with the recipient.# +* #The object permissions set for a shared visualization also apply to the Liveboard, unless they are overridden by another API request or in the UI.# +* #If email notifications for object sharing are enabled, the recipient receives a notification with a link to the shared visualization. Although this link opens the shared visualization, the recipient can also access other visualizations on the Liveboard.# + +=== #Sharing a Collection# +#Collections support separate permissions for the Collection and for the objects within it. For more information, see xref:collections.adoc#_share_a_collection[Share a Collection].# + [#group-privileges] == Group privileges Each user group includes a set of privileges for its users. When a user is assigned to a group in ThoughtSpot, the default privileges associated with a group are assigned to its users. The group privileges allow users belonging to a group to perform specific operations and access workflows. If a user belongs to more than one group, they will have the highest level of privileges from all the groups they belong to. diff --git a/modules/ROOT/pages/audit-logs.adoc b/modules/ROOT/pages/audit-logs.adoc index 817593b88..bc907d6f5 100644 --- a/modules/ROOT/pages/audit-logs.adoc +++ b/modules/ROOT/pages/audit-logs.adoc @@ -43,9 +43,9 @@ Error Message: Cannot use first or last name in the password.","userId":"e3dc495 Org ID if your ThoughtSpot application instance has Orgs. == Fetch logs via API -To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. #Use the following API endpoint:# +To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. Use the following API endpoint: -* #+++POST /api/rest/2.0/logs/fetch+++# +* +++POST /api/rest/2.0/logs/fetch+++ On Orgs-enabled clusters, the API fetches security logs for the current Org text. However, the administrator of the primary Org (Org 0) can fetch logs not just for the primary Org, but also for all other Orgs if the `get_all_logs` parameter is set to `true` in the API request. diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index ddf1dcfd4..99ed03d24 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -642,7 +642,6 @@ To understand about the data catalog tools supported by ThoughtSpot, see the fol * https://docs.thoughtspot.com/cloud/latest/catalog-integration-atlan[Atlan, window=_blank] * https://docs.thoughtspot.com/cloud/latest/catalog-integration-collibra[Collibra, window=_blank] -#To understand the metadata API endpoints, see https://developers.thoughtspot.com/docs/rest-apiv2-reference#_metadata[REST API v2 Metadata endpoints, window=_blank].# == Connection Configuration ThoughtSpot supports multiple configurations per data Connection. This feature allows data engineers to define and manage several distinct Connection configurations under a single data Connection object in ThoughtSpot. diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 54067ac77..5033c55a4 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -110,7 +110,7 @@ The *xref:LiveboardViewConfig.adoc[LiveboardViewConfig]* object includes several [width="100%",cols="2,4",options="header"] |==== -|#Page# |#Covers# +|#Page# |#Customization impact# |#xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# |#Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling.# |#xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# diff --git a/modules/ROOT/pages/liveboard-data-downloads.adoc b/modules/ROOT/pages/liveboard-data-downloads.adoc index dc5697326..a393bfb7e 100644 --- a/modules/ROOT/pages/liveboard-data-downloads.adoc +++ b/modules/ROOT/pages/liveboard-data-downloads.adoc @@ -38,7 +38,7 @@ image::./images/liveboard-refresh.png[Liveboard refresh] The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow. -[width="100%",cols="2,4"] +[width="100%",cols="3,4"] |==== |ID | Description From ec931fb8c71d5411aead4b60a5f02b20ede5913f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 7 Oct 2026 14:18:44 +0530 Subject: [PATCH 011/169] floating widget fix --- src/components/FloatingAssistant/index.tsx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/components/FloatingAssistant/index.tsx b/src/components/FloatingAssistant/index.tsx index 658f36daa..a3d6b683f 100644 --- a/src/components/FloatingAssistant/index.tsx +++ b/src/components/FloatingAssistant/index.tsx @@ -50,6 +50,14 @@ const FloatingAssistant: React.FC = () => { const [isTutorialsPage, setIsTutorialsPage] = useState( () => typeof window !== 'undefined' && isTutorialsPath(window.location.pathname), ); + // Older-version wrapper pages (e.g. /docs/26.9.0.cl) load the frozen version's site in a + // nested iframe (VersionIframe, src carries ?_iframe=1). The wrapper already mounts its own + // assistant, so the nested copy must not render a second one. Read once at load: the flag + // is on the iframe's initial URL, and in-page navigation inside it may drop the param. + const [isNestedIframe] = useState( + () => typeof window !== 'undefined' + && new URLSearchParams(window.location.search).get('_iframe') === '1', + ); // The 404 page has no fixed pathname to match against (it renders for // whatever bogus URL the user hit), so detect it via document.title // instead. NOTE: a DOM marker (id) doesn't work here — in production, @@ -495,6 +503,7 @@ const FloatingAssistant: React.FC = () => { if (pageId === CUSTOM_PAGE_ID.API_PLAYGROUND) return null; if (isTutorialsPage) return null; if (isNotFoundPage) return null; + if (isNestedIframe) return null; return ( <> From 549fc57bc3b802f3dbe92bedb2be4ffe33f68cf1 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 7 Oct 2026 15:13:07 +0530 Subject: [PATCH 012/169] broken link and typo fixes --- modules/ROOT/pages/customize-liveboard-layout.adoc | 2 +- modules/ROOT/pages/filters_overview.adoc | 2 +- modules/ROOT/pages/whats-new.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/customize-liveboard-layout.adoc b/modules/ROOT/pages/customize-liveboard-layout.adoc index adc1a7835..bcb535aff 100644 --- a/modules/ROOT/pages/customize-liveboard-layout.adoc +++ b/modules/ROOT/pages/customize-liveboard-layout.adoc @@ -151,7 +151,7 @@ The following rules apply to the `liveboardGutter` value: ==== `liveboardGutter` controls the spacing between tiles and groups, not the spacing within a group. -The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#lb-header-margin[Liveboard CSS variables]. +The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#_liveboard[Liveboard CSS variables]. ==== [#noteTiles] diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index 98d1a6ea3..fa7ac754b 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -230,7 +230,7 @@ Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parame * *Tab*: applies only to visualizations on a specific tab. * *Group*: applies only to visualizations in a specific group on a tab. -To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:embed-pinboard.adoc#scoped-liveboard-filtering[Scoped Liveboard filtering]. +To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]. To scope an update to a tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`. Set `level` to `TAB` or `GROUP`, and set `targetId` to the ID of the tab or group. To get the group IDs on a Liveboard, use `HostEvent.GetGroups`. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 4f037ec52..93387a262 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -64,7 +64,7 @@ ThoughtSpot now supports programmatic feature management with new REST API v2 en ==== Liveboard enhancements * *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# + -Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see #xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]#. +Liveboard filters now have a three-tier filter hierarchy: Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see #xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]#. * *Host Events* + From 27339286fc734f81da63043353959ef0dc6786ce Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 7 Oct 2026 16:49:32 +0530 Subject: [PATCH 013/169] final changes for lb embed split and v1 cleanup --- modules/ROOT/pages/api-changelog.adoc | 10 +- modules/ROOT/pages/api-user-management.adoc | 94 +++++++++---------- modules/ROOT/pages/authentication.adoc | 14 +-- modules/ROOT/pages/common/nav-embedding.adoc | 2 +- .../pages/common/nav-in-product-help.adoc | 2 +- modules/ROOT/pages/connections.adoc | 12 +-- .../pages/customize-liveboard-filters.adoc | 32 +++---- .../pages/customize-liveboard-layout.adoc | 80 ++++++++-------- modules/ROOT/pages/data-apis-v2.adoc | 4 +- modules/ROOT/pages/data-security.adoc | 2 +- modules/ROOT/pages/embed-pinboard.adoc | 20 ++-- modules/ROOT/pages/filters_overview.adoc | 2 +- .../ROOT/pages/liveboard-data-downloads.adoc | 20 ++-- modules/ROOT/pages/org-manage-api.adoc | 26 ++--- modules/ROOT/pages/report-apis-v2.adoc | 16 ++-- .../pages/rest-api-v2-metadata-search.adoc | 20 ++-- modules/ROOT/pages/rest-api-v2-search.adoc | 4 +- .../ROOT/pages/rest-api-v2-users-search.adoc | 2 +- modules/ROOT/pages/roles.adoc | 8 +- modules/ROOT/pages/tml-export.adoc | 2 +- modules/ROOT/pages/tml-import.adoc | 8 +- .../ROOT/pages/whats-new-prev-history.adoc | 10 +- modules/ROOT/pages/whats-new.adoc | 10 +- 23 files changed, 200 insertions(+), 200 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 407da9247..3435deff8 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -263,11 +263,11 @@ The SDK includes the following new features and enhancements in Liveboard embedd `liveboardGutter` embed config property:: A new `liveboardGutter` property is available on `LiveboardViewConfig`. Use this property to set the gutter spacing between tiles on an embedded Liveboard. -For more information, see #xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter]# +For more information, see xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter] 12-column layout for Liveboard tile positioning:: A new embed config property is available on `LiveboardViewConfig` to always use a 12-column grid layout for Liveboard tile positioning. When enabled, tile placement and sizing follow a fixed 12-column grid regardless of the Liveboard's default layout settings. -For more information, see #xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards]# +For more information, see xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards] New host events for the Liveboard edit page:: * `HostEvent.OpenAddFilterModal` + @@ -316,7 +316,7 @@ Enables compact header layout in embedded Liveboards. * `coverAndFilterOptionInPDF` + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * `isLiveboardMasterpiecesEnabled` + -Enables the #xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping]# feature. +Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. * `isEnhancedFilterInteractivityEnabled` + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. @@ -387,7 +387,7 @@ Trigger a manual cache refresh from the host application. * `Action.RefreshLiveboardBrowserCache` + Action ID to show or hide the cache refresh button. -For more information, see #xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh]#. +For more information, see xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh]. |[tag greenBackground]#NEW# a| [discrete] @@ -1731,7 +1731,7 @@ For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources |[tag greenBackground]#NEW#| For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. -For more information, see #xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]#. +For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]. |[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index 1d7194cae..acc6c4697 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -10,7 +10,7 @@ To provide access to ThoughtSpot content or define privileges, you must add user == User creation and update -#You can create users and update user profiles using the xref:rest-api-v2-reference.adoc#_users[REST API v2 user endpoints].# +You can create users and update user profiles using the xref:rest-api-v2-reference.adoc#_users[REST API v2 user endpoints]. While you can delete users, it is preferable to deactivate a user, which maintains the user's references within the system. @@ -18,34 +18,34 @@ When configuring xref:configure-saml.adoc[SAML SSO] in ThoughtSpot UI, you can s By default, ThoughtSpot sends e-mail messages to a new user and enables onboarding workflows when they log in for the first time, even when you are embedding ThoughtSpot content. To alter this behavior at a system-wide level, you need to xref:customize-email-settings.adoc[Customize the onboarding settings]. The user update API also allows setting onboarding experience values for an individual user. If you need to modify the default behavior beyond the available UI options, contact your ThoughtSpot team. -#To specify whether an activation email is sent to a new user, set the `trigger_activation_email` parameter in the `POST /api/rest/2.0/users/create` request.# +To specify whether an activation email is sent to a new user, set the `trigger_activation_email` parameter in the `POST /api/rest/2.0/users/create` request. [NOTE] ==== ThoughtSpot supports local management of users. For initial development and testing purposes, you can create users in ThoughtSpot and manage their profiles locally. However, in large production environments, avoid creating local user profiles to reduce administration overhead. ==== -=== #Required privileges# -#To create, edit, or delete users, assign users to groups, transfer objects from one user to another, or activate, deactivate, or log out users, you need administrator privileges (`ADMINISTRATION`).# +=== Required privileges +To create, edit, or delete users, assign users to groups, transfer objects from one user to another, or activate, deactivate, or log out users, you need administrator privileges (`ADMINISTRATION`). -#If Role-Based Access Control (RBAC) is enabled on your instance, the `USER_ADMINISTRATION` (*Can manage users*) privilege is required. On instances with Orgs, this privilege allows managing users only within the Org context of the API request. For more information, see xref:roles.adoc[Role-based access control].# +If Role-Based Access Control (RBAC) is enabled on your instance, the `USER_ADMINISTRATION` (*Can manage users*) privilege is required. On instances with Orgs, this privilege allows managing users only within the Org context of the API request. For more information, see xref:roles.adoc[Role-based access control]. -=== #User attributes# -#Note the following points about user attributes:# +=== User attributes +Note the following points about user attributes: -* #*Username*: The username must be unique. An API request to create a user with a username that already exists returns an error.# -* #*Account type*: The `account_type` attribute indicates how the user was created and how the user authenticates. Valid values are:# -** #`LOCAL_USER`: A user created and authenticated locally in ThoughtSpot. This is the default account type.# -** #`LDAP_USER`: A user imported from an LDAP server.# -** #`SAML_USER`: A user authenticated through SAML SSO.# -** #`OIDC_USER`: A user authenticated through OpenID Connect (OIDC).# -** #`REMOTE_USER`: A user authenticated by an external system.# +* *Username*: The username must be unique. An API request to create a user with a username that already exists returns an error. +* *Account type*: The `account_type` attribute indicates how the user was created and how the user authenticates. Valid values are: +** `LOCAL_USER`: A user created and authenticated locally in ThoughtSpot. This is the default account type. +** `LDAP_USER`: A user imported from an LDAP server. +** `SAML_USER`: A user authenticated through SAML SSO. +** `OIDC_USER`: A user authenticated through OpenID Connect (OIDC). +** `REMOTE_USER`: A user authenticated by an external system. + -#When users are imported from an external server, such as an LDAP server or an IdP, ThoughtSpot assigns the account type automatically. For example, a user imported from an LDAP server is added as `LDAP_USER`.# -* #*Visibility*: The `visibility` attribute determines whether other users can share objects with the user. By default, users are set to `SHARABLE`, which allows other users and groups to share objects with them. To prevent other users from finding the user and sharing objects with them, set `visibility` to `NON_SHARABLE`. In multi-tenant deployments, users are commonly set to `NON_SHARABLE`.# +When users are imported from an external server, such as an LDAP server or an IdP, ThoughtSpot assigns the account type automatically. For example, a user imported from an LDAP server is added as `LDAP_USER`. +* *Visibility*: The `visibility` attribute determines whether other users can share objects with the user. By default, users are set to `SHARABLE`, which allows other users and groups to share objects with them. To prevent other users from finding the user and sharing objects with them, set `visibility` to `NON_SHARABLE`. In multi-tenant deployments, users are commonly set to `NON_SHARABLE`. -=== #Password reset# -#After you reset a user's password with the `POST /api/rest/2.0/users/reset-password` endpoint, you can log the user out of their active sessions by using the `POST /api/rest/2.0/users/force-logout` endpoint. The user must then log in again with the new password.# +=== Password reset +After you reset a user's password with the `POST /api/rest/2.0/users/reset-password` endpoint, you can log the user out of their active sessions by using the `POST /api/rest/2.0/users/force-logout` endpoint. The user must then log in again with the new password. //// @@ -130,17 +130,17 @@ ThoughtSpot is gradually migrating its users to link:https://docs.thoughtspot.co * The `email` attribute is mandatory when creating a user in ThoughtSpot Okta. ThoughtSpot recommends that users provide a valid email address during user creation. * You must set a password during user creation if you do not want to trigger an activation email. -* The default value for #`account_type`# will be `OIDC_USER`. +* The default value for `account_type` will be `OIDC_USER`. Administrators can manage the user account status for all users. For IAMv2 users, the API response for the following APIs will also include `SUSPENDED` as a user state: To create a user: -* #+++POST /api/rest/2.0/users/create+++# +* +++POST /api/rest/2.0/users/create+++ To update user details: -* #+++POST /api/rest/2.0/users/{user_identifier}/update+++# +* +++POST /api/rest/2.0/users/{user_identifier}/update+++ [NOTE] ==== @@ -188,52 +188,52 @@ For more information, see the following pages: == User group creation and update -#Groups can be created via the xref:rest-api-v2-reference.adoc#_groups[REST API v2 group endpoints].# +Groups can be created via the xref:rest-api-v2-reference.adoc#_groups[REST API v2 group endpoints]. -#To create, edit, or delete groups, you need administrator privileges. If RBAC is enabled on your instance, the `GROUP_ADMINISTRATION` (*Can manage groups*) privilege is required. To assign Roles to a group or remove Roles from a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges.# +To create, edit, or delete groups, you need administrator privileges. If RBAC is enabled on your instance, the `GROUP_ADMINISTRATION` (*Can manage groups*) privilege is required. To assign Roles to a group or remove Roles from a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges. The xref:api-user-management.adoc#group-privileges[Group privileges] are set directly on groups, either during group creation or via a group update API call. -=== #Group hierarchy# -#ThoughtSpot supports hierarchical groups. You can create a parent group and add other groups to it as sub-groups. For example, you can create a parent group called `Site` and add your tenant groups to it. Sub-groups inherit the privileges of the parent group.# +=== Group hierarchy +ThoughtSpot supports hierarchical groups. You can create a parent group and add other groups to it as sub-groups. For example, you can create a parent group called `Site` and add your tenant groups to it. Sub-groups inherit the privileges of the parent group. -#To add sub-groups to a group or remove sub-groups from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint. Removing a sub-group from a group removes only the association; it does not delete the sub-group from ThoughtSpot.# +To add sub-groups to a group or remove sub-groups from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint. Removing a sub-group from a group removes only the association; it does not delete the sub-group from ThoughtSpot. == User association to groups -You can add users to specific groups when creating a user or group via REST API endpoints. #When you assign a user to a group, the user inherits the privileges and Roles assigned to that group.# +You can add users to specific groups when creating a user or group via REST API endpoints. When you assign a user to a group, the user inherits the privileges and Roles assigned to that group. -#To add users to an existing group or remove users from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint with the `user_identifiers` parameter and the `ADD`, `REMOVE`, or `REPLACE` operation. To update the groups of a single user, use the +++POST /api/rest/2.0/users/{user_identifier}/update+++ endpoint with the `group_identifiers` parameter.# +To add users to an existing group or remove users from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint with the `user_identifiers` parameter and the `ADD`, `REMOVE`, or `REPLACE` operation. To update the groups of a single user, use the +++POST /api/rest/2.0/users/{user_identifier}/update+++ endpoint with the `group_identifiers` parameter. -#Removing a user from a group removes only the group association; it does not delete the user from ThoughtSpot. To delete a user, use the +++POST /api/rest/2.0/users/{user_identifier}/delete+++ endpoint.# +Removing a user from a group removes only the group association; it does not delete the user from ThoughtSpot. To delete a user, use the +++POST /api/rest/2.0/users/{user_identifier}/delete+++ endpoint. -#To get a list of users assigned to a group, use the +++POST /api/rest/2.0/groups/search+++ endpoint.# +To get a list of users assigned to a group, use the +++POST /api/rest/2.0/groups/search+++ endpoint. == Access control (sharing) Access to objects is determined by content *shared* directly to the user or the groups they belong to. It is easier to manage and audit sharing through groups rather than object sharing at the individual user level. -Users can share objects or modify sharing properties through the UI or via an API call to the #`POST /api/rest/2.0/security/metadata/share` endpoint#. +Users can share objects or modify sharing properties through the UI or via an API call to the `POST /api/rest/2.0/security/metadata/share` endpoint. -#Note the following points about sharing objects via REST API:# +Note the following points about sharing objects via REST API: -* #You can share the following types of objects: Liveboards, visualizations, Answers, Models, Views, Connections, and Collections.# -* #To share an object, you must have edit access to the object.# -* #The `share_mode` attribute can be set to `READ_ONLY` (*Can view*), `MODIFY` (*Can edit*), or `NO_ACCESS`. Setting `share_mode` to `NO_ACCESS` removes any access previously granted to a user or group.# -* #To send a share notification to the users and groups with whom the object is shared, set `notify_on_share` to `true`.# -* #To make a shared Liveboard or Answer discoverable, set `has_lenient_discoverability` to `true`.# +* You can share the following types of objects: Liveboards, visualizations, Answers, Models, Views, Connections, and Collections. +* To share an object, you must have edit access to the object. +* The `share_mode` attribute can be set to `READ_ONLY` (*Can view*), `MODIFY` (*Can edit*), or `NO_ACCESS`. Setting `share_mode` to `NO_ACCESS` removes any access previously granted to a user or group. +* To send a share notification to the users and groups with whom the object is shared, set `notify_on_share` to `true`. +* To make a shared Liveboard or Answer discoverable, set `has_lenient_discoverability` to `true`. -#To audit access, use the `POST /api/rest/2.0/security/metadata/fetch-permissions` endpoint to get the users and groups that have access to an object, or the `POST /api/rest/2.0/security/principals/fetch-permissions` endpoint to get the objects a user or group can access.# +To audit access, use the `POST /api/rest/2.0/security/metadata/fetch-permissions` endpoint to get the users and groups that have access to an object, or the `POST /api/rest/2.0/security/principals/fetch-permissions` endpoint to get the objects a user or group can access. -#For more information and examples, see xref:access-control-sharing.adoc[Access control and sharing].# +For more information and examples, see xref:access-control-sharing.adoc[Access control and sharing]. -=== #Sharing a visualization# -#Note the following points about sharing a visualization:# +=== Sharing a visualization +Note the following points about sharing a visualization: -* #Sharing a visualization implicitly shares the entire Liveboard with the recipient.# -* #The object permissions set for a shared visualization also apply to the Liveboard, unless they are overridden by another API request or in the UI.# -* #If email notifications for object sharing are enabled, the recipient receives a notification with a link to the shared visualization. Although this link opens the shared visualization, the recipient can also access other visualizations on the Liveboard.# +* Sharing a visualization implicitly shares the entire Liveboard with the recipient. +* The object permissions set for a shared visualization also apply to the Liveboard, unless they are overridden by another API request or in the UI. +* If email notifications for object sharing are enabled, the recipient receives a notification with a link to the shared visualization. Although this link opens the shared visualization, the recipient can also access other visualizations on the Liveboard. -=== #Sharing a Collection# -#Collections support separate permissions for the Collection and for the objects within it. For more information, see xref:collections.adoc#_share_a_collection[Share a Collection].# +=== Sharing a Collection +Collections support separate permissions for the Collection and for the objects within it. For more information, see xref:collections.adoc#_share_a_collection[Share a Collection]. [#group-privileges] == Group privileges @@ -262,7 +262,7 @@ When creating or updating a group using the REST API v2 endpoints, use the `role [NOTE] ==== -Roles must be available before they can be assigned. #Use the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fcreate-role[`POST /api/rest/2.0/roles/create`] endpoint# to create roles programmatically before calling the group create or update endpoints. +Roles must be available before they can be assigned. Use the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fcreate-role[`POST /api/rest/2.0/roles/create`] endpoint to create roles programmatically before calling the group create or update endpoints. ==== For a complete list of available privileges and role categories, see xref:roles.adoc[Role-based access control]. diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 5b922944c..c310b82e7 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -973,15 +973,15 @@ If the API request is successful, ThoughtSpot returns the following response: |=== //// [#switch-org] -== #Switching Org context# -#On ThoughtSpot instances with Orgs, only cluster administrators and users who belong to more than one Org can switch between Orgs.# +== Switching Org context +On ThoughtSpot instances with Orgs, only cluster administrators and users who belong to more than one Org can switch between Orgs. -#For REST API v2 requests, the Org context is determined by the session or token used in the request. To send API requests in a different Org:# +For REST API v2 requests, the Org context is determined by the session or token used in the request. To send API requests in a different Org: -* #For cookie-based authentication, log in again by sending a request to the `/api/rest/2.0/auth/session/login` endpoint with the ID or name of the Org in the `org_identifier` attribute.# -* #For token-based authentication, request a new token with the ID of the Org in the `org_id` attribute, or use a <>.# +* For cookie-based authentication, log in again by sending a request to the `/api/rest/2.0/auth/session/login` endpoint with the ID or name of the Org in the `org_identifier` attribute. +* For token-based authentication, request a new token with the ID of the Org in the `org_id` attribute, or use a <>. -#To view the Org context of the current session and the Orgs available to the user, send a request to the `/api/rest/2.0/auth/session/user` endpoint and check the `current_org` and `orgs` properties in the API response. For more information, see <<_viewing_session_information,Viewing session information>>.# +To view the Org context of the current session and the Orgs available to the user, send a request to the `/api/rest/2.0/auth/session/user` endpoint and check the `current_org` and `orgs` properties in the API response. For more information, see <<_viewing_session_information,Viewing session information>>. == Logging out of a session @@ -997,7 +997,7 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' ---- -#If you send the logout request as an AJAX call from a browser with cookie-based authentication, include credentials in the request so that the session cookie is sent. For example, set `xhrFields: { withCredentials: true }` in a jQuery AJAX request, or `credentials: 'include'` in a Fetch API request.# +If you send the logout request as an AJAX call from a browser with cookie-based authentication, include credentials in the request so that the session cookie is sent. For example, set `xhrFields: { withCredentials: true }` in a jQuery AJAX request, or `credentials: 'include'` in a Fetch API request. === API response diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index 35d18dcd2..e9ea19007 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -22,7 +22,7 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] *** link:{{navprefix}}/customize-liveboard-layout[Customize Liveboard layout and UI] *** link:{{navprefix}}/customize-liveboard-filters[Customize Liveboard filters] -*** link:{{navprefix}}/liveboard-data-downloads[Liveboard data refresh and downloads] +*** link:{{navprefix}}/liveboard-data-downloads[Customize data refresh and download options] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index a7173bacf..86cc82b95 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -41,7 +41,7 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] *** link:{{navprefix}}/customize-liveboard-layout[Customize Liveboard layout and UI] *** link:{{navprefix}}/customize-liveboard-filters[Customize Liveboard filters] -*** link:{{navprefix}}/liveboard-data-downloads[Liveboard data refresh and downloads] +*** link:{{navprefix}}/liveboard-data-downloads[Customize data refresh and download options] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index 99ed03d24..25b3f67cb 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -73,7 +73,7 @@ ThoughtSpot supports connecting to external data warehouses and using these as d This article describes the procedures for setting and managing data connections through the REST APIs. For information about how to set up a data connection, see link:https://docs.thoughtspot.com/cloud/latest/connections[Data Connections in ThoughtSpot, window=_blank]. == Data Connection APIs -The connection API endpoints allow you to create, edit, delete, export, and query data connections on a ThoughtSpot cluster. #For more information about the API endpoints, see https://developers.thoughtspot.com/docs/rest-apiv2-reference#_connections[REST API v2 Connection endpoints, window=_blank].# +The connection API endpoints allow you to create, edit, delete, export, and query data connections on a ThoughtSpot cluster. For more information about the API endpoints, see https://developers.thoughtspot.com/docs/rest-apiv2-reference#_connections[REST API v2 Connection endpoints, window=_blank]. === Required permissions @@ -613,16 +613,16 @@ To create or modify data connections through REST APIs, you need to provide a ma [#export-connection] -== #Export a connection# -#To export a connection, export its TML by using the `POST /api/rest/2.0/metadata/tml/export` endpoint. To include the Tables of the connection in the export, set `export_dependent` to `true`. For more information, see xref:tml-export.adoc[Export TML].# +== Export a connection +To export a connection, export its TML by using the `POST /api/rest/2.0/metadata/tml/export` endpoint. To include the Tables of the connection in the export, set `export_dependent` to `true`. For more information, see xref:tml-export.adoc[Export TML]. [#delete-connection] -== #Delete a connection# -#To delete a connection, use the `POST /api/rest/2.0/connections/{connection_identifier}/delete` endpoint.# +== Delete a connection +To delete a connection, use the `POST /api/rest/2.0/connections/{connection_identifier}/delete` endpoint. [IMPORTANT] ==== -#A connection can be used by multiple Tables, Models, and visualizations. If a connection has dependent objects, remove the dependent objects or their associations before you delete the connection.# +A connection can be used by multiple Tables, Models, and visualizations. If a connection has dependent objects, remove the dependent objects or their associations before you delete the connection. ==== == Integrate with dbt diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc index 27d7b95a4..c695e2606 100644 --- a/modules/ROOT/pages/customize-liveboard-filters.adoc +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -6,13 +6,13 @@ :page-pageid: customize-liveboard-filters :page-description: Use the Visual Embed SDK to control filter visibility, apply filters at load time, scope filters to tabs and groups, and update filters on an embedded Liveboard. -To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. #The Visual Embed SDK provides properties and host events to control which filter chips are visible, apply filters at load time, scope filters to specific tabs or groups, and update filters programmatically.# +To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. The Visual Embed SDK provides properties and host events to control which filter chips are visible, apply filters at load time, scope filters to specific tabs or groups, and update filters programmatically. -#Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component.# +Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component. [#filter-visibility] == Customizing filter visibility -To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. #For more information, see xref:customize-liveboard-layout.adoc#show-hide-ui-elements[Show/hide large UI elements].# +To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. For more information, see xref:customize-liveboard-layout.adoc#show-hide-ui-elements[Show/hide large UI elements]. If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. @@ -31,14 +31,14 @@ When `hideIrrelevantChipsInLiveboardTabs` is `true`: * A *Show irrelevant filters* toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips. * When the user clicks *Show irrelevant filters*, a complementary *Hide irrelevant filters* button appears to restore the filtered view. -#For more information about the compact header, see xref:customize-liveboard-layout.adoc#compact-header[Enable compact Liveboard header].# +For more information about the compact header, see xref:customize-liveboard-layout.adoc#compact-header[Enable compact Liveboard header]. [#masked-filter-chips] -=== #Masked filter chips# -#If a Liveboard includes filters on columns that a user cannot access because of column-level security, the filter values are masked for that user. Use the `showMaskedFilterChip` property to control whether these masked filter chips are visible:# +=== Masked filter chips +If a Liveboard includes filters on columns that a user cannot access because of column-level security, the filter values are masked for that user. Use the `showMaskedFilterChip` property to control whether these masked filter chips are visible: -* #`true`: the filter chips for inaccessible columns are displayed as masked.# -* #`false`: the filter chips for inaccessible columns are hidden.# +* `true`: the filter chips for inaccessible columns are displayed as masked. +* `false`: the filter chips for inaccessible columns are hidden. [source,JavaScript] ---- @@ -48,10 +48,10 @@ const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { }); ---- -#The `showMaskedFilterChip` property is also available in full application embedding. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards].# +The `showMaskedFilterChip` property is also available in full application embedding. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards]. [#filters-at-load] -== #Apply filters at load time# +== Apply filters at load time By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. [IMPORTANT] @@ -126,9 +126,9 @@ Use the following host events in the Visual Embed SDK to update filters: For more information and examples, see xref:filters_overview.adoc[Filter types and application layers]. -== #Related information# -* #xref:embed-pinboard.adoc[Embed a Liveboard]# -* #xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# -* #xref:liveboard-data-downloads.adoc[Liveboard data refresh and downloads]# -* #xref:runtime-filters.adoc[Runtime filters]# -* #xref:runtime-parameters.adoc[Runtime Parameter overrides]# +== Related information +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI] +* xref:liveboard-data-downloads.adoc[Customize data refresh and download options] +* xref:runtime-filters.adoc[Runtime filters] +* xref:runtime-parameters.adoc[Runtime Parameter overrides] diff --git a/modules/ROOT/pages/customize-liveboard-layout.adoc b/modules/ROOT/pages/customize-liveboard-layout.adoc index bcb535aff..046ee4f14 100644 --- a/modules/ROOT/pages/customize-liveboard-layout.adoc +++ b/modules/ROOT/pages/customize-liveboard-layout.adoc @@ -6,9 +6,9 @@ :page-pageid: customize-liveboard-layout :page-description: Use the LiveboardViewConfig properties in the Visual Embed SDK to customize the header, tabs, tiles, and layout of an embedded Liveboard. -#The xref:LiveboardViewConfig.adoc[LiveboardViewConfig] object includes several properties that control the look and layout of an embedded Liveboard, such as the header, tabs, tile spacing, responsive layout, and grouping and styling of tiles.# +The xref:LiveboardViewConfig.adoc[LiveboardViewConfig] object includes several properties that control the look and layout of an embedded Liveboard, such as the header, tabs, tile spacing, responsive layout, and grouping and styling of tiles. -#Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component.# +Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component. [#show-hide-ui-elements] == Show/hide large UI elements @@ -29,7 +29,7 @@ const embed = new LiveboardEmbed('#embed', { }); ---- -#When the header is hidden, you can trigger filter interactions programmatically using host events. For more information, see xref:customize-liveboard-filters.adoc#update-filters[Updating filters].# +When the header is hidden, you can trigger filter interactions programmatically using host events. For more information, see xref:customize-liveboard-filters.adoc#update-filters[Updating filters]. The following constructor disables the __sticky header__ and shows the Liveboard title, which is hidden by default: @@ -92,7 +92,7 @@ const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { }); ---- -#To hide filter chips that are not relevant to the active tab in the compact header, see xref:customize-liveboard-filters.adoc#filter-visibility[Customizing filter visibility].# +To hide filter chips that are not relevant to the active tab in the compact header, see xref:customize-liveboard-filters.adoc#filter-visibility[Customizing filter visibility]. [#liveboard-tabs] == Customize Liveboard tabs @@ -121,6 +121,37 @@ The `activeTabId` property is available only in the `LiveboardEmbed` package and For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). +[#noteTiles] +== Add Note tiles +You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. + +* Only users with edit access to a Liveboard can add a Note tile. +* Users require `Can upload data` privilege to upload an image to the note tile. +* If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. + +[#liveboard-grouping-styling] +== Liveboard grouping and styling + +You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. +To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. +Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. + +* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. +* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. +* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. ++ +[.bordered] +[.widthAuto] +-- +image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] +-- ++ +To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. + +For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. + +For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. + [#liveboard-gutter] == Set Liveboard tile gutter @@ -154,14 +185,6 @@ The following rules apply to the `liveboardGutter` value: The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#_liveboard[Liveboard CSS variables]. ==== -[#noteTiles] -== Add Note tiles -You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. - -* Only users with edit access to a Liveboard can add a Note tile. -* Users require `Can upload data` privilege to upload an image to the note tile. -* If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. - [#liveboard-breakpoints] == Redefine Liveboard breakpoint widths The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. @@ -216,31 +239,8 @@ For more information about the CSS layout variables available for Liveboard layo see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. ==== -[#liveboard-grouping-styling] -== Liveboard grouping and styling - -You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. -To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. -Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. - -* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. -* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. -* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. -+ -[.bordered] -[.widthAuto] --- -image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] --- -+ -To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. - -For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. - -For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. - -== #Related information# -* #xref:embed-pinboard.adoc[Embed a Liveboard]# -* #xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# -* #xref:liveboard-data-downloads.adoc[Liveboard data refresh and downloads]# -* #xref:LiveboardViewConfig.adoc[LiveboardViewConfig]# +== Related information +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +* xref:liveboard-data-downloads.adoc[Customize data refresh and download options] +* xref:LiveboardViewConfig.adoc[LiveboardViewConfig] diff --git a/modules/ROOT/pages/data-apis-v2.adoc b/modules/ROOT/pages/data-apis-v2.adoc index 2670cd006..372019d89 100644 --- a/modules/ROOT/pages/data-apis-v2.adoc +++ b/modules/ROOT/pages/data-apis-v2.adoc @@ -82,7 +82,7 @@ curl -X POST \ }' ---- -#To verify your query string, run an equivalent search in the ThoughtSpot UI search bar and check whether it returns the same data. Note that the search syntax in the UI differs slightly from the query string syntax.# +To verify your query string, run an equivalent search in the ThoughtSpot UI search bar and check whether it returns the same data. Note that the search syntax in the UI differs slightly from the query string syntax. //// === Using tokens generated from Spotter APIs as raw data @@ -115,7 +115,7 @@ If the API request is successful, ThoughtSpot returns the Answer data for the qu == Fetch Liveboard Data API To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. #If `visualization_identifiers` is not specified, the API returns data for all visualizations on the Liveboard.# +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. If `visualization_identifiers` is not specified, the API returns data for all visualizations on the Liveboard. === Liveboard data request example [source,cURL] diff --git a/modules/ROOT/pages/data-security.adoc b/modules/ROOT/pages/data-security.adoc index d1d997f7c..d9662010a 100644 --- a/modules/ROOT/pages/data-security.adoc +++ b/modules/ROOT/pages/data-security.adoc @@ -34,6 +34,6 @@ Starting with ThoughtSpot Cloud 26.10.0.cl, Liveboards that include columns rest * Filter chips from columns that the user cannot access are masked instead of blocking the Liveboard. Only one masked filter chip is shown, at the end of the filter bar, to indicate that one or more filters are inaccessible. For example, if five filters are inaccessible, the Liveboard still shows a single masked filter chip. * Scheduled Liveboard deliveries apply CSR separately for each recipient. -To control whether masked filter chips are visible in an embedded Liveboard, use the `showMaskedFilterChip` SDK property. For more information, see #xref:customize-liveboard-filters.adoc#masked-filter-chips[Masked filter chips]#. +To control whether masked filter chips are visible in an embedded Liveboard, use the `showMaskedFilterChip` SDK property. For more information, see xref:customize-liveboard-filters.adoc#masked-filter-chips[Masked filter chips]. For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards, window=_blank]. diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 5033c55a4..2664f383a 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -67,7 +67,7 @@ For more information about the Liveboard embed object, classes, methods, interfa The `LiveboardEmbed` component includes the `xref:LiveboardViewConfig.adoc[LiveboardViewConfig]` object. This object provides various attributes and properties to xref:css-customization.adoc[customize the look and feel of the Liveboard page], xref:embed-actions.adoc[control the visibility of menu actions] and features, and xref:embed-events.adoc[manage interactions between the host and embedded app]. -The most common customization is controlling the visibility of menu items in the embedded view by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of xref:Action.adoc[Action] IDs. For information about the other frequently used properties, see #<>#. +The most common customization is controlling the visibility of menu items in the embedded view by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of xref:Action.adoc[Action] IDs. For information about the other frequently used properties, see <>. == Register, handle, and trigger events @@ -106,22 +106,22 @@ image::./images/embed-lb.png[Liveboard embed] == Common customization options The *xref:LiveboardViewConfig.adoc[LiveboardViewConfig]* object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide the header, and more. -#The customization options are grouped into the following pages:# +The customization options are grouped into the following pages: [width="100%",cols="2,4",options="header"] |==== -|#Page# |#Customization impact# -|#xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# -|#Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling.# -|#xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# -|#Filter chip visibility, masked filter chips, filters at load time, contextual filtering at the Liveboard, tab, and group levels, and updating filters with host events.# -|#xref:liveboard-data-downloads.adoc[Liveboard data refresh and downloads]# -|#Browser data cache and refresh, PDF, XLSX, and CSV downloads, download action IDs and host events, and scheduled exports.# +|Page |Customization impact +|xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI] +|Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling. +|xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +|Filter chip visibility, masked filter chips, filters at load time, contextual filtering at the Liveboard, tab, and group levels, and updating filters with host events. +|xref:liveboard-data-downloads.adoc[Customize data refresh and download options] +|Browser data cache and refresh, PDF, XLSX, and CSV downloads, download action IDs and host events, and scheduled exports. |==== [IMPORTANT] ==== -#If a Liveboard is saved with Groups in the ThoughtSpot interface, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embed configuration. Otherwise, the embedded Liveboard fails to load. For more information, see xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard grouping and styling].# +If a Liveboard is saved with Groups in the ThoughtSpot interface, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embed configuration. Otherwise, the embedded Liveboard fails to load. For more information, see xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard grouping and styling]. ==== == Additional resources diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index fa7ac754b..7936588de 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -36,7 +36,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 are visible as UI components at the top of a Liveboard page. #By default, a Liveboard filter applies to all visualizations on the Liveboard. Starting with ThoughtSpot Cloud 26.10.0.cl, a filter can also be scoped to a specific tab or group. For more information, see <>.# When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + +Liveboard filters are visible as UI components at the top of a Liveboard page. By default, a Liveboard filter applies to all visualizations on the Liveboard. Starting with ThoughtSpot Cloud 26.10.0.cl, a filter can also be scoped to a specific tab or group. For more information, see <>. 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 `HostEvent.UpdateFilters`. 5. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters-cross[Liveboard cross filters, window=_blank] + diff --git a/modules/ROOT/pages/liveboard-data-downloads.adoc b/modules/ROOT/pages/liveboard-data-downloads.adoc index a393bfb7e..6b02d6e71 100644 --- a/modules/ROOT/pages/liveboard-data-downloads.adoc +++ b/modules/ROOT/pages/liveboard-data-downloads.adoc @@ -1,14 +1,14 @@ -= Liveboard data refresh and downloads += Customize data refresh and download options :toc: true :toclevels: 2 -:page-title: Liveboard data refresh and downloads +:page-title: Customize data refresh and download options :page-pageid: liveboard-data-downloads :page-description: Use the Visual Embed SDK to enable browser data caching and refresh, and to configure PDF, XLSX, and CSV downloads and scheduled exports on an embedded Liveboard. -#The Visual Embed SDK provides properties, action IDs, and events to control how users refresh Liveboard data and download or export Liveboards from the embedded view.# +The Visual Embed SDK provides properties, action IDs, and events to control how users refresh Liveboard data and download or export Liveboards from the embedded view. -#Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component.# +Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component. [#liveboard-data-cache] == Liveboard browser cache and refresh @@ -164,9 +164,9 @@ const embed = new LiveboardEmbed('#tsEmbed', { }); ---- -== #Related information# -* #xref:embed-pinboard.adoc[Embed a Liveboard]# -* #xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI]# -* #xref:customize-liveboard-filters.adoc[Customize Liveboard filters]# -* #xref:Action.adoc[Actions]# -* #xref:HostEvent.adoc[HostEvent]# +== Related information +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI] +* xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +* xref:Action.adoc[Actions] +* xref:HostEvent.adoc[HostEvent] diff --git a/modules/ROOT/pages/org-manage-api.adoc b/modules/ROOT/pages/org-manage-api.adoc index 06644b07e..304732c25 100644 --- a/modules/ROOT/pages/org-manage-api.adoc +++ b/modules/ROOT/pages/org-manage-api.adoc @@ -17,9 +17,9 @@ include::{path}/rest-apiv1-deprecation-note.adoc[] If you do not see the Orgs feature enabled on your instance, contact ThoughtSpot Support. . Log in to your application instance as an administrator. -. Create Orgs in the *Admin* page of the UI or via #the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Forgs%2Fcreate-org[`POST /api/rest/2.0/orgs/create`] endpoint#. +. Create Orgs in the *Admin* page of the UI or via the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Forgs%2Fcreate-org[`POST /api/rest/2.0/orgs/create`] endpoint. + -To create and manage Orgs, you must set the Org context to `All`. To do this, you can switch to the *All Orgs* tab in the Admin page of UI or pass the Org scope `ALL` in your API requests to Orgs API endpoints. #For more information, see <<_create_and_manage_orgs,Org management operations>>.# +To create and manage Orgs, you must set the Org context to `All`. To do this, you can switch to the *All Orgs* tab in the Admin page of UI or pass the Org scope `ALL` in your API requests to Orgs API endpoints. For more information, see <<_create_and_manage_orgs,Org management operations>>. . Create users and map the users to Orgs. + You can create an administrator profile for each Org and let these Org administrators manage users, groups, and role privileges in their respective Orgs. @@ -35,25 +35,25 @@ To create an Org on a multi-tenant ThoughtSpot instance, you need cluster admini === REST API v2.0 endpoints -#For Orgs CRUD operations, use the following REST API v2.0 Org endpoints:# +For Orgs CRUD operations, use the following REST API v2.0 Org endpoints: * +++/api/rest/2.0/orgs/create+++ * +++ /api/rest/2.0/orgs/search+++ * +++/api/rest/2.0/orgs/{org_identifier}/update +++ * +++ /api/rest/2.0/orgs/{org_identifier}/delete+++ -#Note the following points about Org names and descriptions:# +Note the following points about Org names and descriptions: -* #The Org name must be unique and must not exceed 48 characters. The name can contain only letters (a-z, A-Z), digits (0-9), and hyphens (-). Spaces and other special characters are not supported.# -* #The Org description must not exceed 124 characters.# +* The Org name must be unique and must not exceed 48 characters. The name can contain only letters (a-z, A-Z), digits (0-9), and hyphens (-). Spaces and other special characters are not supported. +* The Org description must not exceed 124 characters. -=== #Deleting an Org# +=== Deleting an Org [NOTE] ==== -* #ThoughtSpot does not allow deleting the Primary Org (Org 0).# -* #When an Org is deleted, the Org and its objects become inaccessible immediately. However, the objects remain in the ThoughtSpot system for seven days from the deletion date.# -* #To restore a deleted Org, contact ThoughtSpot Support within seven days of deletion.# -* #To remove the objects of a deleted Org before the seven-day period ends, or to reuse a deleted Org name or object names immediately after deletion, contact ThoughtSpot Support.# +* ThoughtSpot does not allow deleting the Primary Org (Org 0). +* When an Org is deleted, the Org and its objects become inaccessible immediately. However, the objects remain in the ThoughtSpot system for seven days from the deletion date. +* To restore a deleted Org, contact ThoughtSpot Support within seven days of deletion. +* To remove the objects of a deleted Org before the seven-day period ends, or to reuse a deleted Org name or object names immediately after deletion, contact ThoughtSpot Support. ==== == Manage users and groups @@ -62,13 +62,13 @@ On a multi-tenant instance, the cluster and Org administrators can create users [NOTE] ==== -#For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests.# +For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests. ==== [width="100%" cols="5,15"] [options='header'] |===== -|#Operation type#|#REST API v2 endpoints# +|Operation type|REST API v2 endpoints |Authentication a| **Basic authentication** + To log in to a specific Org context with basic authentication, specify the Org ID in the +++ /api/rest/2.0/auth/session/login +++ API request. diff --git a/modules/ROOT/pages/report-apis-v2.adoc b/modules/ROOT/pages/report-apis-v2.adoc index b7705e344..0d8764a8e 100644 --- a/modules/ROOT/pages/report-apis-v2.adoc +++ b/modules/ROOT/pages/report-apis-v2.adoc @@ -95,14 +95,14 @@ curl -X POST \ For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. -#The following `pdf_options` attributes determine the content of the PDF:# - -* #`include_cover_page`: Adds a cover page with the Liveboard title.# -* #`include_filter_page`: Adds a page that lists the filters applied to the Liveboard.# -* #`include_custom_logo`: Adds the custom wide logo, if one is configured for your instance, to the footer of each page.# -* #`page_footer_text`: Adds the specified text to the footer of each page.# -* #`include_page_number`: Adds the page number to the footer of each page.# -* #`truncate_table`: Includes only the first page of each table visualization in the PDF.# +The following `pdf_options` attributes determine the content of the PDF: + +* `include_cover_page`: Adds a cover page with the Liveboard title. +* `include_filter_page`: Adds a page that lists the filters applied to the Liveboard. +* `include_custom_logo`: Adds the custom wide logo, if one is configured for your instance, to the footer of each page. +* `page_footer_text`: Adds the specified text to the footer of each page. +* `include_page_number`: Adds the page number to the footer of each page. +* `truncate_table`: Includes only the first page of each table visualization in the PDF. You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index 857815c4f..40ee5ec97 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -3574,12 +3574,12 @@ If you need multiple levels of sorting, you'll have to parse the response progra === permissions You can filter responses based on who can access the object, that is, who the content has been shared to, using the `permissions` parameter. -While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint #for a full listing.# +While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint for a full listing. -#The `/security/metadata/fetch-permissions` endpoint supports the following permission types in the `permission_type` attribute:# +The `/security/metadata/fetch-permissions` endpoint supports the following permission types in the `permission_type` attribute: -* #`DEFINED`: Returns the access granted to users and groups through object sharing.# -* #`EFFECTIVE`: Returns the access that users have, including the access granted through the privileges of the groups to which they belong.# +* `DEFINED`: Returns the access granted to users and groups through object sharing. +* `EFFECTIVE`: Returns the access that users have, including the access granted through the privileges of the groups to which they belong. The `permissions` object takes an array of objects that define a `principal` and a `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fenumerations%2Fshare-mode[share_mode, target=_blank]`. `principal` is an object with a `type` of `USER` or `USER_GROUP` and an `identifier`, either the name or the GUID of the principal: @@ -3700,10 +3700,10 @@ The `exclude_objects` parameter takes an array of objects that can exclude items ---- == Additional response details -There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint #to return related details in a single API call.# +There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to return related details in a single API call. === include_visualization_headers -#The `include_visualization_headers` parameter adds the header details of all individual visualizations on a Liveboard to the response.# +The `include_visualization_headers` parameter adds the header details of all individual visualizations on a Liveboard to the response. [source,JSON] ---- @@ -3722,7 +3722,7 @@ Note from above that the response to **every** request has the `visualization_he The `include_visualization_headers` adds the array of visualization headers for every element in the response, so you can request a list of all Liveboards and all the visualizations on those Liveboards all at once. === include_details -The `include_details` parameter in the `metadata/search` API request adds #a detailed object, with as much detail as possible about each requested object and its relationships with other objects within ThoughtSpot,# to each element retrieved by `metadata/search` to the response under the `metadata_detail` key. +The `include_details` parameter in the `metadata/search` API request adds a detailed object, with as much detail as possible about each requested object and its relationships with other objects within ThoughtSpot, to each element retrieved by `metadata/search` to the response under the `metadata_detail` key. [source,JSON] ---- @@ -3831,11 +3831,11 @@ Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects* An object can only be deleted if all of its dependent objects are deleted first. -#A dependency is a relationship between a referenced object and the objects that reference it. For example, consider a Model (`Model1`) with a formula column (`Column1`) that refers to a base column (`Column2`). In this example, `Model1` is a referencing object and `Column2` is a referenced object. You cannot delete `Column2` until you delete or modify `Column1` and `Model1`.# +A dependency is a relationship between a referenced object and the objects that reference it. For example, consider a Model (`Model1`) with a formula column (`Column1`) that refers to a base column (`Column2`). In this example, `Model1` is a referencing object and `Column2` is a referenced object. You cannot delete `Column2` until you delete or modify `Column1` and `Model1`. -#Before you delete a data object such as a Table, Model, or column by using the `POST /api/rest/2.0/metadata/delete` endpoint, check whether the object has dependent objects, and remove the dependent objects or their references first.# +Before you delete a data object such as a Table, Model, or column by using the `POST /api/rest/2.0/metadata/delete` endpoint, check whether the object has dependent objects, and remove the dependent objects or their references first. -#To retrieve these relationships from `metadata/search`, set the `include_dependent_objects` parameter to `true`:# +To retrieve these relationships from `metadata/search`, set the `include_dependent_objects` parameter to `true`: [source,JSON] ---- diff --git a/modules/ROOT/pages/rest-api-v2-search.adoc b/modules/ROOT/pages/rest-api-v2-search.adoc index f0de4a393..33293e1d4 100644 --- a/modules/ROOT/pages/rest-api-v2-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-search.adoc @@ -8,7 +8,7 @@ The REST API v2 endpoints that end in `/search` have very flexible request formats that solve a number of use cases. -#A small set of `/search` endpoints covers many capabilities, depending on the request parameters you send.# +A small set of `/search` endpoints covers many capabilities, depending on the request parameters you send. Note that many parameters in the requests are *optional*, and leaving the parameter name out entirely has a different effect from including the parameter and specific values. @@ -25,7 +25,7 @@ Assume every request you see has the following parameters in addition to what is ---- == Search metadata -#The `/metadata/search` endpoint retrieves metadata objects and their details, such as headers, permissions, and dependent objects.# +The `/metadata/search` endpoint retrieves metadata objects and their details, such as headers, permissions, and dependent objects. For more information about this API, xref:rest-api-v2-metadata-search.adoc[Search metadata]. diff --git a/modules/ROOT/pages/rest-api-v2-users-search.adoc b/modules/ROOT/pages/rest-api-v2-users-search.adoc index 7ad9e269c..563415154 100644 --- a/modules/ROOT/pages/rest-api-v2-users-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-users-search.adoc @@ -252,7 +252,7 @@ The `notify_on_share`, `show_onboarding_experience`, and `onboarding_experience_ Note that the *absence* of the parameter is how you remove the filtering. If the parameter value is present as a key, the value must be set to `true` or `false`, so that the response can be filtered to get only those users that match the condition. == Additional response details -There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint #to return related details in a single API call.# +There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to return related details in a single API call. === include_favorite_metadata The `user` object in the response always includes a `favorite_metadata` key, but it will always be an empty array unless the `include_favorite_metadata` parameter is added to the request set to `true`: diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index 1e0883bc7..992e60f1c 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -196,9 +196,9 @@ UI: **Can download Data**| Allows users to download data from objects such as Li == How to create and assign Roles -You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the #REST API v2 endpoints#. +You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the REST API v2 endpoints. -#To create and manage Roles, you need the `ROLE_ADMINISTRATION` (*Can manage roles*) privilege. To assign Roles to a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges.# +To create and manage Roles, you need the `ROLE_ADMINISTRATION` (*Can manage roles*) privilege. To assign Roles to a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges. === REST API v2 endpoints for Role administration and assignment @@ -222,8 +222,8 @@ Delete a Role object * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[`POST /api/rest/2.0/groups/{group_identifier}/update`] |Object query a| * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fsearch-roles[`POST /api/rest/2.0/roles/search`] + -To get Roles assigned to specific groups, specify the name or GUID of the #group# in the `group_identifiers` attribute. + -Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. #If `org_identifiers` is not specified, the API returns the Roles for the Org context from which the API request is sent.# +To get Roles assigned to specific groups, specify the name or GUID of the group in the `group_identifiers` attribute. + +Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. If `org_identifiers` is not specified, the API returns the Roles for the Org context from which the API request is sent. * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups[`POST /api/rest/2.0/groups/search`] + To filter group objects assigned to a particular Role, specify the name or GUID of the Role in the `role_identifiers` attribute. * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fsearch-users[`POST /api/rest/2.0/users/search`] + diff --git a/modules/ROOT/pages/tml-export.adoc b/modules/ROOT/pages/tml-export.adoc index 60bc3c777..51aa94772 100644 --- a/modules/ROOT/pages/tml-export.adoc +++ b/modules/ROOT/pages/tml-export.adoc @@ -34,7 +34,7 @@ When set to `true`, exports the associated objects for the `export_ids` specifie * `export_dependent` + Specifies if the Tables of the referenced Connection object must be included in the export. * `export_connection_as_dependent` + -Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. #This attribute works only when `export_associated` is set to `true`.# +Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. This attribute works only when `export_associated` is set to `true`. == Export FQNs diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc index 1e13480b3..ceec8f09e 100644 --- a/modules/ROOT/pages/tml-import.adoc +++ b/modules/ROOT/pages/tml-import.adoc @@ -27,8 +27,8 @@ To import TML representation of the metadata objects into ThoughtSpot, use the f There are multiple kinds of imports possible: -* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully #and the objects that depend on them#. -* `ALL_OR_NONE` #imports all objects only if all objects validate successfully. If the import fails for one object, no objects are imported.# +* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully and the objects that depend on them. +* `ALL_OR_NONE` imports all objects only if all objects validate successfully. If the import fails for one object, no objects are imported. * `VALIDATE_ONLY` validates the objects but does not import them. * `PARTIAL_OBJECT` imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. @@ -279,8 +279,8 @@ You can import TML objects asynchronously by scheduling TML import tasks via `PO |Form parameter|Description| Default |`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ |`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. #When set to `true`, a `guid` in the imported TML that is already used by another object is replaced with a new GUID. If the `guid` in the imported TML is not used by any other object, ThoughtSpot creates the new object with that `guid`.# | `false` -|#`all_orgs_override`# + +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. When set to `true`, a `guid` in the imported TML that is already used by another object is replaced with a new GUID. If the `guid` in the imported TML is not used by any other object, ThoughtSpot creates the new object with that `guid`. | `false` +|`all_orgs_override` + __Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. __Requires Org administration privileges to access TML objects across all Orgs.__| `false` diff --git a/modules/ROOT/pages/whats-new-prev-history.adoc b/modules/ROOT/pages/whats-new-prev-history.adoc index eefffcd92..6cf22e9a4 100644 --- a/modules/ROOT/pages/whats-new-prev-history.adoc +++ b/modules/ROOT/pages/whats-new-prev-history.adoc @@ -736,7 +736,7 @@ For more information, see xref:selective-user-access.adoc[User access to non-emb ==== You can now customize the width of the Liveboard breakpoint on an embedded instance. To enable it, you must set the `enable2ColumnLayout` property to `true`. -For more information, see #xref:customize-liveboard-layout.adoc#liveboard-breakpoints[Redefine Liveboard breakpoint widths]#. +For more information, see xref:customize-liveboard-layout.adoc#liveboard-breakpoints[Redefine Liveboard breakpoint widths]. ==== .Visual Embed SDK @@ -1389,7 +1389,7 @@ We recommend using a development environment to test your customizations before ==== In the new Liveboard experience mode, you can now add Note tiles with custom text, images, and links. This feature is turned off by default and can be enabled by ThoughtSpot administrators. -For more information, see #xref:customize-liveboard-layout.adoc#noteTiles[Note tiles]#. +For more information, see xref:customize-liveboard-layout.adoc#noteTiles[Note tiles]. ==== .Visual Embed SDK [%collapsible] @@ -1407,7 +1407,7 @@ For information about REST API enhancements, see xref:rest-apiv1-changelog.adoc[ .New Liveboard experience [%collapsible] ==== -The #xref:embed-pinboard.adoc[new Liveboard experience]# is now Generally Available (GA) on embedded instances and is enabled by default. +The xref:embed-pinboard.adoc[new Liveboard experience] is now Generally Available (GA) on embedded instances and is enabled by default. ==== .New CSS variables for custom styling @@ -1605,7 +1605,7 @@ For more information, see xref:fixed-issues.adoc[Fixed issues]. ==== The new Liveboard experience[beta betaBackground]^Beta^ now supports organizing visualizations in tabs. Users with edit access to a Liveboard can add, edit, and move visualizations to tabs on a Liveboard. On embedded ThoughtSpot instances, developers can set a specific tab as an active tab using the Visual Embed SDK. -This feature is available only on deployments that have the new Liveboard experience enabled. For more information, see #xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]#. +This feature is available only on deployments that have the new Liveboard experience enabled. For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]. [IMPORTANT] The new Liveboard experience is in BETA on embedded ThoughtSpot instances. This feature is turned off by default on embedded ThoughtSpot instances. @@ -1665,7 +1665,7 @@ The new Liveboard experience is currently available in BETA on embedded ThoughtS In ThoughtSpot Cloud 8.6.0.cl:: -The new Liveboard experience is turned off by default on embedded ThoughtSpot instances. If you are using the Visual Embed SDK to embed ThoughtSpot, you can #xref:embed-pinboard.adoc[set the `liveboardV2` parameter]# in the SDK package to `true` and enable the new experience globally for all users on your instance. + +The new Liveboard experience is turned off by default on embedded ThoughtSpot instances. If you are using the Visual Embed SDK to embed ThoughtSpot, you can xref:embed-pinboard.adoc[set the `liveboardV2` parameter] in the SDK package to `true` and enable the new experience globally for all users on your instance. + + ThoughtSpot users with administrator privileges can also link:https://docs.thoughtspot.com/cloud/latest/liveboard-experience-new[turn on the new Liveboard experience, window=_blank] at the cluster level. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 93387a262..9628f34b3 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -64,7 +64,7 @@ ThoughtSpot now supports programmatic feature management with new REST API v2 en ==== Liveboard enhancements * *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# + -Liveboard filters now have a three-tier filter hierarchy: Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see #xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]#. +Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]. * *Host Events* + @@ -227,13 +227,13 @@ Embedded Spotter interface supports onboarding starter prompts to guide first-ti The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: * Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + -#xref:customize-liveboard-filters.adoc#filter-visibility[Hides filters]# that are not relevant to the displayed visualization in a tab. +xref:customize-liveboard-filters.adoc#filter-visibility[Hides filters] that are not relevant to the displayed visualization in a tab. * Compact header (`isLiveboardCompactHeaderEnabled`) + -Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see #xref:customize-liveboard-layout.adoc#compact-header[compact Liveboard header]#. +Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:customize-liveboard-layout.adoc#compact-header[compact Liveboard header]. * Cover page filtering options (`coverAndFilterOptionInPDF`) + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + -Enables the #xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping]# feature. +Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. * Filter interactivity (`isEnhancedFilterInteractivityEnabled`) + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. @@ -500,7 +500,7 @@ Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. Excel exports for pivot tables:: Pivot table visualizations can now be exported to Excel format. -For more information, see #xref:liveboard-data-downloads.adoc#liveboard-download-options[Liveboard download options]#. +For more information, see xref:liveboard-data-downloads.adoc#liveboard-download-options[Liveboard download options]. --- From aecfa87e8a77b6481169e66f851d3540b9712f96 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 8 Oct 2026 10:36:30 +0530 Subject: [PATCH 014/169] title text fix --- modules/ROOT/pages/onboarding-guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/onboarding-guide.adoc b/modules/ROOT/pages/onboarding-guide.adoc index 73d3fa9b9..bf000736f 100644 --- a/modules/ROOT/pages/onboarding-guide.adoc +++ b/modules/ROOT/pages/onboarding-guide.adoc @@ -32,7 +32,7 @@ If you’re using the Free Trial instance, note that it is already connected to To learn more about data connections, data models and objects, and how to search data and create Liveboards, see link:https://docs.thoughtspot.com/cloud/latest/ts-cloud-getting-started[ThoughtSpot product documentation, window=_blank]. -== Embed ThoughtSpotcontent +== Embed ThoughtSpot content This section provides a set of steps to quickly embed a xref:faqs.adoc#lbDef[Liveboard] from the link:https://www.thoughtspot.com/trial?tsiref=web-devsite[Free Trial, window=_blank] or your own ThoughtSpot application instance. The following figure shows a sample Liveboard with charts and a table: From 102d661ec626f72521f97637a493ffab4b5103db Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 8 Oct 2026 11:27:17 +0530 Subject: [PATCH 015/169] version fixes --- src/configs/doc-configs.js | 32 +------------------------------- 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 57ea8a723..cb02ca339 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -50,39 +50,9 @@ module.exports = { { label: '26.10.0.cl', link: ' ', - subLabel: 'Cloud (Latest)', + subLabel: 'Cloud', iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', }, - { - label: '26.9.0.cl', - link: '26.9.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', - }, - { - label: '26.8.0.cl', - link: '26.8.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/', - }, - { - label: '26.3.0.sw', - link: '26.3.0.sw', - subLabel: 'Software (Latest)', - iframeUrl: 'https://visual-embed-sdk-26-3.vercel.app/docs/', - }, - { - label: '10.10.0.sw', - link: '10.10.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-10.vercel.app/docs/', - }, - { - label: '10.1.0.sw', - link: '10.1.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', - }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', From b2242c0d234d5a4b277bd3d672dc34f702842fa7 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Thu, 8 Oct 2026 16:09:32 +0530 Subject: [PATCH 016/169] nested frame fix --- src/assets/styles/index.scss | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/src/assets/styles/index.scss b/src/assets/styles/index.scss index 32e85f14d..b05a6e1e8 100644 --- a/src/assets/styles/index.scss +++ b/src/assets/styles/index.scss @@ -1522,23 +1522,10 @@ a.anchor { } } -// In-product presentation only: override banner color to match product sidebar (#232F43), -// and suppress the page-wide gradient entirely. +// In-product presentation only: the walkthroughs hero keeps the product sidebar color (#232F43). +// The docs header banner (.header-banner) intentionally keeps the same radiance gradient as the +// public site, so it is not overridden here. .embedded-mode { - .radiance-bg { - display: none; - } - - .header-banner { - background: #232F43; - border-bottom: none; - box-shadow: none; - - .header-banner-text { - color: #fff; - } - } - .walkthroughs-page { background: #232F43; From 2e9e9625afc804f572fd01e67f7df8c03672f9ce Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 9 Oct 2026 16:49:30 +0530 Subject: [PATCH 017/169] object id revamped --- .../pages/common/nav-in-product-help.adoc | 2 + modules/ROOT/pages/common/nav.adoc | 2 + modules/ROOT/pages/deploy-with-tml-apis.adoc | 2 +- .../pages/development-and-deployment.adoc | 2 +- .../ROOT/pages/intro-thoughtspot-objects.adoc | 109 ++------ modules/ROOT/pages/object-id-in-urls.adoc | 122 +++++++++ modules/ROOT/pages/object-id.adoc | 236 ++++++++++++++++++ 7 files changed, 378 insertions(+), 97 deletions(-) create mode 100644 modules/ROOT/pages/object-id-in-urls.adoc create mode 100644 modules/ROOT/pages/object-id.adoc diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 86cc82b95..fc8fd0c2b 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -202,6 +202,8 @@ Integration with external tools Build and deploy ** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects] +*** link:{{navprefix}}/object-id[Object ID (obj_id)] +*** link:{{navprefix}}/object-id-urls[Object ID in URLs] ** link:{{navprefix}}/timezone-aware-filtering[Timezone-aware keywords and filters] ** link:{{navprefix}}/variables[Variables] ** link:{{navprefix}}/parameterize-metadata[Parameterize metadata] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 048ac0686..509eee2a1 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -55,6 +55,8 @@ Integration Guides Deployment guides * link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects overview] +** link:{{navprefix}}/object-id[Object ID (obj_id)] +*** link:{{navprefix}}/object-id-urls[Object ID in URLs] * link:{{navprefix}}/timezone-aware-filtering[Timezone-aware keywords and filters] * link:{{navprefix}}/publish-data-overview[Publish content to Orgs] * link:{{navprefix}}/development-and-deployment[Development and deployment] diff --git a/modules/ROOT/pages/deploy-with-tml-apis.adoc b/modules/ROOT/pages/deploy-with-tml-apis.adoc index 48ec1e6da..213c4f1b2 100644 --- a/modules/ROOT/pages/deploy-with-tml-apis.adoc +++ b/modules/ROOT/pages/deploy-with-tml-apis.adoc @@ -59,7 +59,7 @@ Properties of a Connection can also be parameterized. Parameterization works with both TML import and xref:publishing-overview.adoc[publishing]. === obj_id -Before implementing any deployment process, you should ensure that `obj_id` is enabled on your ThoughtSpot instance. +Before implementing any deployment process, you should ensure that `obj_id` is enabled on your ThoughtSpot instance. For information about supported object types, format rules, and resolution order, see xref:object-id.adoc[Object ID (obj_id)]. [NOTE] ==== diff --git a/modules/ROOT/pages/development-and-deployment.adoc b/modules/ROOT/pages/development-and-deployment.adoc index 60ee8af69..2abbb84d8 100644 --- a/modules/ROOT/pages/development-and-deployment.adoc +++ b/modules/ROOT/pages/development-and-deployment.adoc @@ -21,7 +21,7 @@ xref:orgs.adoc[Orgs] are fully separated tenants on a single ThoughtSpot instanc image::./images/instances_and_orgs.png[Instances and Orgs] -By setting the `xref:intro-thoughtspot-objects.adoc#object-identifiers[obj_id]` property of objects, objects in various Orgs that are related copies of one another will have the same `obj_id`, allowing for tracking related objects and updating them without concern for each object's unique GUID. +By setting the `xref:object-id.adoc[obj_id]` property of objects, objects in various Orgs that are related copies of one another will have the same `obj_id`, allowing for tracking related objects and updating them without concern for each object's unique GUID. [NOTE] ==== diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 2b9394169..d7f03d922 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -17,105 +17,24 @@ The following figure illustrates the object model hierarchy in ThoughtSpot withi image::./images/object_model_hierarchy.png[Object Model Hierarchy] == Object identifiers -Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. -Objects have an additional `obj_id` property that is *user-settable* and *unique per Org*. It appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. +[#object-identifiers] +Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID. -Each Org can have one object with a particular `obj_id`. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID. +[#_supported_object_types] +Supported objects also have an Object ID (`obj_id`) property that is *user-settable* and *unique per Org*. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID. The `obj_id` appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. -`obj_id` enables TML export and import across Orgs and instances, allowing ThoughtSpot to automatically determine the object's GUID without manual GUID mapping. +[#_obj_id_format_and_constraints] +Because you choose the `obj_id`, related copies of an object in different Orgs and instances can share the same value. This allows ThoughtSpot to match objects during TML import without manual GUID mapping, and allows you to reference objects in REST API requests and ThoughtSpot URLs with the same identifier in every environment. -=== Supported object types +[#_obj_id_resolution] +For more information, see the following pages: -Currently, `obj_id` is supported for the following object types: - -// SOURCE: PRD doc section "Requirements"; SCAL-317366 description - -* Answers -* Data Model -* Logical Tables -* Liveboards -* Visualizations -* Collections -* Personalized Views -* Roles -* Template variables - -=== obj_id format and constraints - -// SOURCE: PRD doc section "Identity Constraints and Object-ID Specification"; SCAL-314582 -`obj_id` values must meet the following requirements: - -[cols="2,3", options="header"] -|=== -|Constraint | Requirement - -|Allowed characters | Lowercase alphanumeric, dots, and hyphens: `[a-z0-9.-]` -|Casing | Strictly lowercase -|Maximum length | 64 characters -|GUID exclusion | Must not match a standard GUID format to prevent ambiguity -|=== - -*Valid examples:* `sales.pipeline.v1`, `finance-ledger-prod`, `ingestion-worker-01` - -=== obj_id resolution - -// SOURCE: PRD doc section "Deterministic Keying and Distributed Consistency"; SCAL-317366 -When an identifier is passed to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: - -. `obj_id` (user-defined identifier) -. GUID -. Name - -This resolution order enables `obj_id` to be used anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. - -[NOTE] -==== -`obj_id` resolution is scoped to the Org. An `obj_id` value is unique within a single Org. The `org_id` + `obj_id` combination uniquely identifies an object across the entire ThoughtSpot instance. -==== - -=== Setting and updating obj_id - -`obj_id` values can be set or updated using the following REST API endpoints: - -* `POST /api/rest/2.0/metadata/update-obj-id` + -Updates the `obj_id` for one or more metadata objects. Accepts the object's GUID (`metadata_identifier`) or its current `obj_id` (`current_obj_id`). - -// SOURCE: deploy-with-tml-apis.adoc; SCAL-317366 -[,json] ----- -{ - "metadata": [ - { - "metadata_identifier": "c1e4043a-4524-4fcb-a20f-9e7aff4dc972", - "new_obj_id": "sales-pipeline-v1" - } - ] -} ----- - -Or, using the current `obj_id`: - -[,json] ----- -{ - "metadata": [ - { - "current_obj_id": "sales-pipeline-v1-c1e4043a", - "new_obj_id": "sales-pipeline-v1" - } - ] -} ----- - -The request accepts an array, allowing multiple objects to be updated in a single API call. - -[NOTE] -==== -Objects are assigned an automatic `obj_id` after the first change to the object once the feature is enabled on your instance. The auto-generated format appends the first segment of the GUID: for example, `RetailSalesRAD-KPIs-c1e4043a`. If the `metadata_obj_id` property in the `/metadata/search` response is `null`, the object has not been updated since the feature was enabled. -==== - -For information about using `obj_id` in CI/CD workflows, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] and xref:development-and-deployment.adoc[Development and deployment]. +[#_setting_and_updating_obj_id] +* xref:object-id.adoc[Object ID (obj_id)] + +Supported object types, `obj_id` format and constraints, how identifiers are resolved, and how to set or update an `obj_id`. +* xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs] + +Use an `obj_id` instead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs. == Data modeling A data model requires at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. @@ -191,7 +110,7 @@ Object representations in the ThoughtSpot REST API include the following propert * `id` + GUID of the object. Unique within a given ThoughtSpot instance. * `obj_id` + -User-defined string identifier for the object. Unique within a given Org. +User-defined string identifier for the object. Unique within a given Org. For more information, see xref:object-id.adoc[Object ID (obj_id)]. * `author` + GUID of the user who created / uploaded the object, or had the object transferred to them. * `owner` + diff --git a/modules/ROOT/pages/object-id-in-urls.adoc b/modules/ROOT/pages/object-id-in-urls.adoc new file mode 100644 index 000000000..45e75d0b7 --- /dev/null +++ b/modules/ROOT/pages/object-id-in-urls.adoc @@ -0,0 +1,122 @@ += Object ID in ThoughtSpot URLs +:toc: true +:toclevels: 2 + +:page-title: Object ID in ThoughtSpot URLs +:page-pageid: object-id-urls +:page-description: Use an Object ID (obj_id) instead of a GUID in ThoughtSpot URLs so that deep links work in every environment + +You can use an object's xref:object-id.adoc[Object ID] (`obj_id`) in place of its GUID in a ThoughtSpot URL. Because you assign the same `obj_id` to an object in every environment, a URL built with an `obj_id` opens the correct object in development, staging, and production. + +Object ID in ThoughtSpot URLs is available from ThoughtSpot Cloud 26.11.0.cl and ThoughtSpot Software 27.3.0.sw. The feature is disabled by default. + +== When to use Object ID in URLs + +GUIDs are generated separately on each ThoughtSpot instance and in each Org. When content is promoted from one environment to another, every object gets a new GUID, so any URL built with a GUID works only in the environment where it was created. Without Object ID, embedded applications and deployment pipelines have to maintain a GUID mapping table for each environment and update it after every deployment. + +Use `obj_id` in URLs if: + +* Your host application builds ThoughtSpot URLs or deep links programmatically. +* You promote content across environments by using TML or a CI/CD pipeline. +* You want links to keep working after content is redeployed. + +With `obj_id`, you assign a stable identifier to an object once and use it in every environment. + +== Before you begin + +* Object ID must be enabled on your instance. For more information, see xref:object-id.adoc#_enable_object_id[Enable Object ID]. +* The objects you want to link to must have an `obj_id`. Objects created before Object ID was enabled do not have an `obj_id` until one is assigned or generated. For more information, see xref:object-id.adoc#_how_objects_get_an_obj_id[How objects get an obj_id]. + +== Enable Object ID in URLs + +Object ID in URLs is disabled by default and there is no setting for it in the ThoughtSpot UI. To enable it on your instance, contact ThoughtSpot Support. The feature is enabled without a restart. + +[NOTE] +==== +Enabling this feature affects only URLs. Object ID in REST APIs and TML works independently of this setting. +==== + +== Supported URLs + +You can use an `obj_id` in place of the GUID in the following URLs: + +[cols="2,4", options="header"] +|=== +|Object |URL format + +|Liveboard |`https://{ThoughtSpot-host}/#/insights/pinboard/{id}` +|Answer |`https://{ThoughtSpot-host}/#/insights/answer/{id}` +|Collection |`https://{ThoughtSpot-host}/insights/collections/{id}` + +In nested collection paths, each segment is resolved separately. +|Model, Worksheet, Table, or View |`https://{ThoughtSpot-host}/#/data/tables/{id}` +|Connection |`https://{ThoughtSpot-host}/#/data/embrace/{id}` +|=== + +In each URL, `{id}` can be either the object's GUID or its `obj_id`. Both formats are accepted on the same URLs. + +=== Example + +A Liveboard URL with a GUID differs in each environment: + +---- +https://{ThoughtSpot-host}/#/insights/pinboard/a3f9c2e1-7b44-4d8e-9f10-6c2b5e8d1a07 +---- + +The same Liveboard URL with an `obj_id` is identical in development, staging, and production: + +---- +https://{ThoughtSpot-host}/#/insights/pinboard/sales-weekly-performance +---- + +== How ThoughtSpot resolves the identifier in a URL + +ThoughtSpot resolves the identifier in a URL on the server, in the following order: + +. *GUID first.* If the identifier is a GUID that matches an existing object of the expected type, ThoughtSpot opens that object. An `obj_id` can never override a valid GUID. +. *Object ID.* Otherwise, ThoughtSpot looks up the identifier as an `obj_id` in the current user's Org. +. *Type check.* If the `obj_id` belongs to an object of a different type, for example, a Model `obj_id` in a Liveboard URL, the object is not opened. + +[IMPORTANT] +==== +Object names are never resolved in URLs. Only the GUID or the `obj_id` of an object can be used. +==== + +== Unsupported objects + +The following objects do not have a URL in ThoughtSpot, so `obj_id` cannot be used to open them in a URL. You can still reference them by `obj_id` through the REST APIs. + +* Groups +* Roles +* Custom actions +* Columns +* Personalized Views +* Visualizations and tabs within a Liveboard + +== Backward compatibility + +* All existing GUID-based URLs, bookmarks, and saved links continue to work. +* There is no breaking change to the Visual Embed SDK public API. +* You can adopt `obj_id` gradually. For example, you can move high-value deep links to `obj_id` and keep using GUIDs for other links. + +== Limitations + +* If you change an object's `obj_id`, URLs that use the previous value no longer resolve. Update any links that use the old value. +* `obj_id` values are unique within an Org. The same `obj_id` in two Orgs opens a different object in each Org. +* For the `obj_id` format and character limit, see xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format and constraints]. + +== Troubleshooting + +An obj_id in a URL returns an invalid identifier error (HTTP 400):: +Object ID in URLs is not enabled on your instance, or the object type is not supported in URLs. If the same `obj_id` works in REST API requests, the URL feature is not enabled. Contact ThoughtSpot Support to enable it. This is a configuration setting, not a defect. + +The URL opens a different object than expected:: +The `obj_id` is resolved in the Org of the user who opens the URL. Make sure the user is in the Org where the `obj_id` was set. + +An obj_id in GUID format does not resolve:: +A value in GUID format is always tried as a GUID first. If a real object has that GUID, that object is opened. Assign the object an `obj_id` that is not in GUID format. + +== Related resources + +* xref:object-id.adoc[Object ID (obj_id)] +* xref:intro-thoughtspot-objects.adoc[ThoughtSpot objects] +* xref:development-and-deployment.adoc[Development and deployment] diff --git a/modules/ROOT/pages/object-id.adoc b/modules/ROOT/pages/object-id.adoc new file mode 100644 index 000000000..079eef054 --- /dev/null +++ b/modules/ROOT/pages/object-id.adoc @@ -0,0 +1,236 @@ += Object ID (obj_id) +:toc: true +:toclevels: 2 + +:page-title: Object ID (obj_id) +:page-pageid: object-id +:page-description: Use Object ID (obj_id) to reference ThoughtSpot objects by a stable, user-defined identifier across Orgs and instances + +Every object in ThoughtSpot has a system-generated GUID. GUIDs are minted per instance, so the same Liveboard promoted from a development environment to a production environment has a different GUID in each one. + +An Object ID (`obj_id`) is a customer-defined, human-readable identifier that you assign to an object in addition to its GUID. An `obj_id` survives renames, TML export and import, and moves between Orgs and instances. Because you choose the value, related copies of an object in different Orgs can share the same `obj_id`, and your deployment scripts, Git-based CI/CD pipelines, and host application can reference the object without maintaining a GUID mapping for each environment. + +Object ID is generally available from ThoughtSpot Cloud 26.9.0.cl. + +== Key concepts + +* `obj_id` is *user-settable* and *unique per Org*. Each Org can have only one object with a particular `obj_id`. +* The combination of Org ID and `obj_id` is the uniqueness key, so the same `obj_id` in two Orgs refers to two different objects. This is by design. +* The `obj_id` of an object is returned as `metadata_obj_id` in the `POST /api/rest/2.0/metadata/search` API response, and as `obj_id` in TML. +* Object ID is the key that TML-based deployment, xref:publishing-overview.adoc[publishing], and xref:git-provider-integration.adoc[Git provider integration] build on. + +== Enable Object ID + +Object ID must be enabled on your ThoughtSpot instance before `obj_id` participates in TML export, TML import, and metadata search. Until it is enabled, ThoughtSpot continues to resolve objects by GUID and name. + +To use `obj_id` in ThoughtSpot URLs, an additional setting is required. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. + +== Supported object types + +The following object types support `obj_id`: + +[cols="2,2,4", options="header"] +|=== +|Object type |TML kind |Notes + +|Liveboard |`liveboard` |Exported in TML and resolved first on import. +|Answer |`answer` | +|Model |`model` |Includes Worksheets. +|Table |`table` | +|SQL View |`sql_view` | +|Column |None |Supported on columns within Tables and Models. +|Connection |`connection` | +|Collection |None | +|Custom action |None |Supported for custom actions managed through the API or the server. +|Personalized View |None |For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import]. +|Variable |None |Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl. +|Memory |None |Carries an Object ID through the Model it is tagged to. +|Group |None | +|Role |None | +|=== + +[IMPORTANT] +==== +The `obj_id` field appears in the TML of every object kind, but TML import honors it only for the supported object types. The presence of `obj_id` in a TML file does not mean that the object type supports Object ID. +==== + +=== Objects that do not support obj_id + +The following objects do not have an `obj_id`: + +[cols="2,5", options="header"] +|=== +|Object |Behavior + +|Visualization on a Liveboard +|In TML, a visualization is identified only by `viz_guid`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, depend on a GUID that differs between Orgs. + +|Liveboard tab +|A tab is identified only by its `id`, which is a GUID. + +|Monitor alert (KPI alert) +|The alert has no `obj_id` of its own. Its TML includes `pinboard_obj_id` and `answer_obj_id`, which resolve on import, but the visualization reference is a GUID that must already exist in the target environment. + +|Schedule +|Liveboard schedules reference visualizations through `included_viz_id`, which is a GUID. + +|Webhook +|The `obj_id` field is present in webhook TML but is ignored on import. + +|Parameter +|Parameters have no `obj_id` and do not migrate by name. + +|Semantic integration +|Semantic integrations have no `obj_id` and do not migrate by name. + +|User +|Users are identified by name in TML and migrate without an `obj_id`. + +|Tag +|Tags are identified by name in TML and migrate without an `obj_id`. + +|Org +|Orgs are part of the uniqueness key (Org ID + `obj_id`), so they do not have an `obj_id` themselves. +|=== + +=== TML kinds that ignore obj_id on import + +The `obj_id` field is present in the following TML kinds but is ignored during import: + +* `Join` +* `user_object` +* `webhook` +* `column_security_rules` +* `nl_instruction` +* `column_alias` +* `nls_feedback` +* `cohort` +* `monitor_alert` + +== obj_id format and constraints + +An `obj_id` value must meet the following requirements: + +[cols="2,4", options="header"] +|=== +|Constraint |Requirement + +|Length |1 to 64 characters +|Allowed characters |Letters, digits, and the special characters hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`). Spaces are not allowed. +|Uniqueness |Unique within an Org +|=== + +*Valid examples:* `sales-weekly-performance`, `finance_ledger.prod`, `retail~kpis-v2` + +[TIP] +==== +Do not use a value that has the same format as a GUID. When ThoughtSpot resolves an identifier in a URL, a GUID-shaped value is always tried as a GUID first, so a GUID-shaped `obj_id` might not resolve as expected. +==== + +== How objects get an obj_id + +* New objects are assigned an `obj_id` when they are created. +* Objects that existed before Object ID was enabled are not assigned an `obj_id` retroactively. They receive an automatically generated `obj_id` the first time the object is updated or imported through TML. +* You can assign or change the `obj_id` of any supported object at any time. For more information, see <<_setting_and_updating_obj_id,Setting and updating obj_id>>. + +An automatically generated `obj_id` appends the first segment of the object's GUID to the object name. For example, `RetailSalesRAD-KPIs-c1e4043a`. If the `metadata_obj_id` property in the `/metadata/search` API response is `null`, the object has not been updated since Object ID was enabled. + +== obj_id resolution + +How ThoughtSpot resolves an identifier depends on where you use it. + +=== REST API endpoints + +When an identifier is passed to a REST API v2.0 endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: + +. `obj_id` +. GUID +. Name + +This allows `obj_id` to be used anywhere a GUID or name is accepted in those fields. Existing integrations that use GUIDs or names continue to work. + +The `POST /api/rest/2.0/metadata/search` endpoint and the metadata update endpoints also accept an `obj_identifier` field. When you use `obj_identifier`, ThoughtSpot resolves the value strictly as an `obj_id`, without falling back to the object name. + +=== TML import + +During TML import, ThoughtSpot matches the TML to an existing object in the following order: + +. `obj_id` +. GUID +. Name + +If the `obj_id` in the TML does not match any object in the target Org, ThoughtSpot falls back to the GUID in the TML and updates that object. The import returns a `WARNING` status in this case. It does not create a duplicate object or fail the import. + +=== ThoughtSpot URLs + +In ThoughtSpot URLs, a GUID is always tried first, and object names are never resolved. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. + +[NOTE] +==== +`obj_id` resolution is always scoped to the Org of the user making the request. The Org ID + `obj_id` combination uniquely identifies an object across the entire ThoughtSpot instance. +==== + +== Setting and updating obj_id + +You can set or change the `obj_id` of an object by using the REST API or by editing the object's TML. + +=== Using the update-obj-id API + +The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. Identify each object by its GUID (`metadata_identifier`) or by its current `obj_id` (`current_obj_id`). + +Using the GUID: + +[,json] +---- +{ + "metadata": [ + { + "metadata_identifier": "c1e4043a-4524-4fcb-a20f-9e7aff4dc972", + "new_obj_id": "sales-pipeline-v1" + } + ] +} +---- + +Using the current `obj_id`: + +[,json] +---- +{ + "metadata": [ + { + "current_obj_id": "sales-pipeline-v1-c1e4043a", + "new_obj_id": "sales-pipeline-v1" + } + ] +} +---- + +The request accepts an array, so you can update multiple objects in a single API call. + +=== Using the metadata headers update API + +The `POST /api/rest/2.0/metadata/headers/update` endpoint also sets the `obj_id` in an object's header. From 26.10.0.cl, this endpoint and the `update-obj-id` endpoint support the `ROLE` and `TEMPLATE_VARIABLE` types. + +=== Using TML + +Set the `obj_id` property in the object's TML and import the TML. For examples, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs]. + +== Behavior and limitations + +Renaming an obj_id:: +After you change an object's `obj_id`, the previous value no longer resolves. Integrations, scripts, and URLs that use the old value must be updated to use the new value. + +Org scope:: +The same `obj_id` in two Orgs resolves to two different objects. Make sure requests are made in the context of the Org where the `obj_id` is set. + +Delete operations:: +The `POST /api/rest/2.0/metadata/delete` endpoint does not accept `obj_identifier`. Use GUIDs when deleting objects in automation scripts. + +== Related resources + +* xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs] +* xref:intro-thoughtspot-objects.adoc[ThoughtSpot objects] +* xref:development-and-deployment.adoc[Development and deployment] +* xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] +* xref:tml-import.adoc[TML import] From 5b3a9861f34f49aa729b566fe5347980b51cd994 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 9 Oct 2026 17:13:34 +0530 Subject: [PATCH 018/169] v1 elimination --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 48 ++++++++++++------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index d7f03d922..08322227f 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -98,19 +98,28 @@ ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/data-security[acces * The author can share the object with their groups using the *Shareable* property. * The author can share the object with other users in *Shareable* groups that the *author* belongs to, and if the other *user* is also marked *Shareable*. -An administrator can share any object with any group or user without restrictions. ThoughtSpot administrators can add users locally link:https://docs.thoughtspot.com/cloud/latest/user-management[in the UI, window=_blank] or via xref:user-api.adoc[REST API]. Similarly, they can manage groups and sharing privileges by using the *Groups* feature in the UI or via REST API. +An administrator can share any object with any group or user without restrictions. ThoughtSpot administrators can add users locally link:https://docs.thoughtspot.com/cloud/latest/user-management[in the UI, window=_blank] or via xref:api-user-management.adoc[REST API v2.0]. Similarly, they can manage groups and sharing privileges by using the *Groups* feature in the UI or via xref:api-user-management.adoc[REST API v2.0]. === Single sign-on If xref:configure-saml.adoc[SAML] or xref:configure-oidc.adoc[OpenID Connect (OIDC)] integration is enabled on your instance, users who authenticate with external identity providers (IdP) can log in to ThoughtSpot with their Single Sign-On credentials. Embedded ThoughtSpot instances also support the xref:trusted-authentication.adoc[trusted authentication] method to sign in application users. == Object properties in REST API -Object representations in the ThoughtSpot REST API include the following properties: +The `POST /api/rest/2.0/metadata/search` REST API v2.0 endpoint returns the following properties for each object: -* `id` + +* `metadata_id` + GUID of the object. Unique within a given ThoughtSpot instance. -* `obj_id` + -User-defined string identifier for the object. Unique within a given Org. For more information, see xref:object-id.adoc[Object ID (obj_id)]. +* `metadata_obj_id` + +User-defined string identifier for the object (`obj_id`). Unique within a given Org. For more information, see xref:object-id.adoc[Object ID (obj_id)]. +* `metadata_name` + +Name of the object. +* `metadata_type` + +Object type, for example, `LIVEBOARD`. For the list of types, see <<_object_names_in_rest_api_v1,Object types in REST API v2.0>>. + +The `metadata_header` object in the response includes the following properties: + +* `id` + +GUID of the object. Same as `metadata_id`. * `author` + GUID of the user who created / uploaded the object, or had the object transferred to them. * `owner` + @@ -124,26 +133,31 @@ GUID of the user who last modified the object. * `tags` + Array of tag objects representing the tags assigned to the object. -== Object names in REST API v1 -Object type names in ThoughtSpot REST API v1 differ from the current names shown in the ThoughtSpot UI. Data objects have both a `type` and a `subtypes` field in the REST API, allowing you to request all valid data objects or specify an individual subtype. +For more information, see xref:rest-api-v2-metadata-search.adoc[Metadata search API]. -The following notation is used in REST API v1 for object types: +[#_object_names_in_rest_api_v1] +== Object types in REST API v2.0 +Object type names in ThoughtSpot REST API v2.0 differ from the names shown in the ThoughtSpot UI. Use the following values in the `type` attribute of REST API v2.0 requests, such as `/metadata/search`: -* *Answers*: `QUESTION_ANSWER_BOOK` -* *Liveboards*: `PINBOARD_ANSWER_BOOK` -* *Connections*: `DATA_SOURCE` -* *Data objects*: `LOGICAL_TABLE`, with the following subtypes: -** *Tables*: `ONE_TO_ONE_LOGICAL` -** *Models*: `WORKSHEET` -** *Views*: `AGGR_WORKSHEET` -** *SQL views*: `SQL_VIEW` -** *CSV imported data*: `USER_DEFINED` +* *Liveboards*: `LIVEBOARD` +* *Answers*: `ANSWER` +* *Connections*: `CONNECTION` +* *Data objects*: `LOGICAL_TABLE` * *Joins*: `LOGICAL_RELATIONSHIP` * *Columns*: `LOGICAL_COLUMN` * *Tags*: `TAG` * *Users*: `USER` * *Groups*: `USER_GROUP` +For the `LOGICAL_TABLE` type, you can also specify the following values in the `subtypes` attribute to filter the results: + +* *Tables*: `ONE_TO_ONE_LOGICAL` +* *Models*: `WORKSHEET` +* *Private Models*: `PRIVATE_WORKSHEET` +* *Views*: `AGGR_WORKSHEET` +* *SQL Views*: `SQL_VIEW` +* *CSV imported data*: `USER_DEFINED` + Column and join objects with their own GUIDs do exist within the ThoughtSpot system, but they are connected to *Tables*, *Models*, or other data objects. Columns and joins can be viewed or modified only within the context of the data object to which they belong. == Related resources From b51312d446efde95bf2046bd95067708ac2cdec5 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 9 Oct 2026 17:48:21 +0530 Subject: [PATCH 019/169] v1 elimination --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 1 + modules/ROOT/pages/object-id.adoc | 63 ++++++++++++++++++- 2 files changed, 62 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 08322227f..ad5b32f96 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -148,6 +148,7 @@ Object type names in ThoughtSpot REST API v2.0 differ from the names shown in th * *Tags*: `TAG` * *Users*: `USER` * *Groups*: `USER_GROUP` +* *Collections*: `COLLECTION` For the `LOGICAL_TABLE` type, you can also specify the following values in the `subtypes` attribute to filter the results: diff --git a/modules/ROOT/pages/object-id.adoc b/modules/ROOT/pages/object-id.adoc index 079eef054..576aeca31 100644 --- a/modules/ROOT/pages/object-id.adoc +++ b/modules/ROOT/pages/object-id.adoc @@ -151,6 +151,18 @@ This allows `obj_id` to be used anywhere a GUID or name is accepted in those fie The `POST /api/rest/2.0/metadata/search` endpoint and the metadata update endpoints also accept an `obj_identifier` field. When you use `obj_identifier`, ThoughtSpot resolves the value strictly as an `obj_id`, without falling back to the object name. +In the `/metadata/search` API, `obj_identifier` is supported for the following object types: + +* `LIVEBOARD` +* `ANSWER` +* `LOGICAL_TABLE` +* `LOGICAL_COLUMN` +* `CONNECTION` +* `USER_GROUP` +* `COLLECTION` + +Other object types, such as Roles and Personalized Views, can have an `obj_id`, but you cannot search for them by `obj_identifier`. To find these objects, search by GUID or name and read the `metadata_obj_id` value in the response. + === TML import During TML import, ThoughtSpot matches the TML to an existing object in the following order: @@ -176,7 +188,22 @@ You can set or change the `obj_id` of an object by using the REST API or by edit === Using the update-obj-id API -The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. Identify each object by its GUID (`metadata_identifier`) or by its current `obj_id` (`current_obj_id`). +The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. The endpoint uses the metadata header update mechanism to apply the change. + +Required privileges:: +`DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*). If Role-Based Access Control (RBAC) is enabled, the `ORG_ADMINISTRATION` (*Can manage Orgs*) privilege is also required. + +Request parameters:: +For each object in the `metadata` array: ++ +* Identify the object by using either `current_obj_id` alone, or `metadata_identifier`. +* `metadata_identifier` accepts the object's GUID or name. If you use the name, you must also specify the object `type`, for example, `ANSWER` or `LOGICAL_TABLE`. +* `new_obj_id` is always required. The value must follow the xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format] and be unique within the Org. + +[TIP] +==== +Before updating Object IDs, export the TML of the objects as a backup. +==== Using the GUID: @@ -206,7 +233,39 @@ Using the current `obj_id`: } ---- -The request accepts an array, so you can update multiple objects in a single API call. +Using the object name and type: + +[,json] +---- +{ + "metadata": [ + { + "metadata_identifier": "Sales Pipeline", + "type": "ANSWER", + "new_obj_id": "sales-pipeline-answer" + } + ] +} +---- + +The request accepts an array, so you can update multiple objects in a single API call. Each object in the array can use a different identification method: + +[,json] +---- +{ + "metadata": [ + { + "current_obj_id": "retail-kpis-c1e4043a", + "new_obj_id": "retail-kpis" + }, + { + "metadata_identifier": "Sales Model", + "type": "LOGICAL_TABLE", + "new_obj_id": "sales-model" + } + ] +} +---- === Using the metadata headers update API From 627564a3d48f5df58ba2ca14d73af8d3ecb04ed5 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:31:43 +0530 Subject: [PATCH 020/169] docs: add Link Customization API page for 26.11.0.cl SCAL-337682, SCAL-337683 --- .../ROOT/pages/link-customization-api.adoc | 251 ++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 modules/ROOT/pages/link-customization-api.adoc diff --git a/modules/ROOT/pages/link-customization-api.adoc b/modules/ROOT/pages/link-customization-api.adoc new file mode 100644 index 000000000..ac3ebe20f --- /dev/null +++ b/modules/ROOT/pages/link-customization-api.adoc @@ -0,0 +1,251 @@ += Link Customization APIs +:toc: true +:toclevels: 2 + +:page-title: Link Customization APIs +:page-pageid: link-customization-api +:page-description: Use Link Customization APIs to programmatically manage the URL templates ThoughtSpot uses when generating shareable links. + +ThoughtSpot generates shareable links for Liveboards, Answers, visualizations, SpotIQ insights, Spotter conversations, and other objects. These links appear in scheduled emails, the Share dialog, and alert notifications. + +By default, shareable links point to your ThoughtSpot instance. If you embed ThoughtSpot in your own application, you can redirect these links to your application using the Link Customization APIs. When a user clicks a shared link, they are directed to your embedding application instead of the ThoughtSpot application. + +[NOTE] +==== +The Link Customization APIs are available on ThoughtSpot Cloud 26.11.0.cl and later. +==== + +== Overview + +The Link Customization APIs allow you to read and update the URL templates used when ThoughtSpot generates shareable links. Each link type has a URL template with placeholders that ThoughtSpot substitutes at generation time. + +Two endpoints are available: + +* **Search** — Retrieves the current URL templates. +* **Update** — Sets or resets URL templates. + +Templates can be managed at two scopes: + +* `CLUSTER` — Sets the default templates that all Orgs inherit. Available only to callers in the primary Org. +* `ORG` — Sets templates for the caller's Org, overriding the cluster default. Requires Orgs to be enabled. + +== Required privileges + +These endpoints require one of the following privileges: + +* `ADMINISTRATION` (**Can administer ThoughtSpot**) +* `DEVELOPER` (**Has developer privilege**) + +== Supported link types and placeholders + +Each link type requires specific placeholders in its URL template. A template missing a required placeholder is rejected. + +[width="100%" cols="2,2,3"] +[options='header'] +|=== +|Link type |Required placeholders |Example template + +|`LIVEBOARD_SHARE_URL` +|`{object-id}`, `{ts-query-params}` +|`\https://analytics.acme.com/dashboards/{object-id}?{ts-query-params}` + +|`VISUALIZATION_SHARE_URL` +|`{object-id}`, `{sub-object-id}`, `{ts-query-params}` +|`\https://analytics.acme.com/dashboards/{object-id}/charts/{sub-object-id}?{ts-query-params}` + +|`ANSWER_SHARE_URL` +|`{object-id}`, `{ts-query-params}` +|`\https://analytics.acme.com/answers/{object-id}?{ts-query-params}` + +|`SPOTIQ_ANALYSIS_URL` +|`{object-id}` +|`\https://analytics.acme.com/insights/{object-id}` + +|`UNSUBSCRIBE_URL` +|none +|`\https://analytics.acme.com/account/email-preferences` + +|`GENERIC_URL` +|`{path}` +|`\https://analytics.acme.com/{path}` + +|`CONVERSATION_SHARE_URL` +|`{conversation-id}`, `{ts-query-params}` +|`\https://analytics.acme.com/spotter/{conversation-id}?{ts-query-params}` +|=== + +`{ts-query-params}` is optional on any type that does not require it. ThoughtSpot substitutes it wherever it appears and removes it when there is nothing to substitute. + +[#search-link-customizations] +== Search link customizations + +Retrieves the URL templates at the cluster level or for the caller's Org. + +=== Endpoint + +---- +POST /api/rest/2.0/customization/links/search +---- + +=== Request parameters + +[width="100%" cols="2,1,1,4"] +[options='header'] +|=== +|Parameter |Type |Required |Description + +|`scope` +|String +|No +|`CLUSTER` or `ORG`. Omit to return whichever scope the caller can access. +|=== + +=== Response + +Returns an array of link preferences. Each entry includes the `scope`, a `templates` array with the `type`, `value`, and `is_overridden` flag for each link type. + +The `is_overridden` flag is `true` when the scope stores a value that differs from what it would otherwise inherit. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' \ + --data-raw '{}' +---- + +=== Example response + +[source,JSON] +---- +[ + { + "scope": "CLUSTER", + "templates": [ + { + "type": "LIVEBOARD_SHARE_URL", + "value": "https://acme.thoughtspot.cloud/#/pinboard/{object-id}?{ts-query-params}", + "is_overridden": false + }, + { + "type": "CONVERSATION_SHARE_URL", + "value": "https://acme.thoughtspot.cloud/#/insights/conv-assist/s/{conversation-id}?{ts-query-params}", + "is_overridden": false + } + ] + } +] +---- + +[#update-link-customizations] +== Update link customizations + +Updates the URL templates at the cluster level or for the caller's Org. + +=== Endpoint + +---- +POST /api/rest/2.0/customization/links/update +---- + +=== Request parameters + +[width="100%" cols="2,1,1,4"] +[options='header'] +|=== +|Parameter |Type |Required |Description + +|`scope` +|String +|No +|`CLUSTER` or `ORG` (default). `CLUSTER` is available only to callers in the primary Org. + +|`operation` +|String +|No +|`REPLACE` (default) sets each listed type to the `value` provided. `RESET` clears each listed type so it falls back to the inherited template. + +|`templates` +|Array +|Yes +|List of template objects. Each object requires a `type`. For `REPLACE`, include a `value` with the URL template. For `RESET`, omit `value`. +|=== + +=== Behavior + +* This is a partial update. Only the types listed in `templates` change. Unlisted types keep their current value. +* A repeated type in the `templates` array is rejected. +* `RESET` clears the override, so an Org falls back to the cluster template and the cluster falls back to the ThoughtSpot default. +* Supplying a `value` with a `RESET` operation is rejected. + +=== Example request — Replace a template + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' \ + --data-raw '{ + "scope": "ORG", + "operation": "REPLACE", + "templates": [ + { + "type": "LIVEBOARD_SHARE_URL", + "value": "https://analytics.acme.com/dashboards/{object-id}?{ts-query-params}" + } + ] +}' +---- + +=== Example request — Reset a template + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' \ + --data-raw '{ + "scope": "ORG", + "operation": "RESET", + "templates": [ + { + "type": "LIVEBOARD_SHARE_URL" + } + ] +}' +---- + +=== Response + +Returns `204 No Content` on success. + +== Error codes + +[width="80%" cols="1,3"] +[options='header'] +|=== +|HTTP status |Description + +|`400` +|Invalid request. For example, a missing required placeholder, a duplicate type, or a `value` supplied with `RESET`. + +|`401` +|Unauthorized. The caller is not authenticated. + +|`403` +|Forbidden. The caller does not have the required privilege. + +|`500` +|Unexpected server error. +|=== + +== Related information + +* xref:rest-api-v2-reference.adoc[REST API v2.0 Reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From 1954b1a5b3762092a2792ec30721dfe31c814958 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:32:31 +0530 Subject: [PATCH 021/169] docs: add Input Table API page for 26.11.0.cl SCAL-332820 --- modules/ROOT/pages/input-table-api.adoc | 282 ++++++++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 modules/ROOT/pages/input-table-api.adoc diff --git a/modules/ROOT/pages/input-table-api.adoc b/modules/ROOT/pages/input-table-api.adoc new file mode 100644 index 000000000..051efac6a --- /dev/null +++ b/modules/ROOT/pages/input-table-api.adoc @@ -0,0 +1,282 @@ += Input Table APIs +:toc: true +:toclevels: 2 + +:page-title: Input Table APIs +:page-pageid: input-table-api +:page-description: Use Input Table APIs to create, manage, and write data to input tables linked to ThoughtSpot models. + +Input tables are user-editable tables stored in an external Cloud Data Warehouse (CDW) and linked to a ThoughtSpot model (worksheet). They allow analysts to enter or import data directly from the ThoughtSpot UI without requiring access to the underlying warehouse. + +The Input Table REST API v2.0 endpoints allow you to create and manage input tables, add or remove columns, and write data programmatically. + +[NOTE] +==== +The Input Table APIs are available on ThoughtSpot Cloud 26.11.0.cl and later. +==== + +== Required privileges + +All Input Table API endpoints require one of the following privileges: + +* `DATAMANAGEMENT` (**Can manage data**) +* `ADMINISTRATION` (**Can administer ThoughtSpot**) + +If link:https://developers.thoughtspot.com/docs/rbac[Role-Based Access Control (RBAC), window=_blank] is enabled on your instance, the `CAN_MANAGE_INPUT_TABLES` (**Can manage input tables**) privilege is required. + +The caller must also have `MODIFY` permission on the input table or model object, depending on the operation. + +[#create-input-table] +== Create an input table + +Creates an input table and links it to a ThoughtSpot model. The physical table is created in the external CDW using the connection, database, and schema derived from the model's metadata. + +=== Endpoint + +---- +POST /api/rest/2.0/input-tables/create +---- + +=== Request body parameters + +[width="100%" cols="2,1,1,4"] +[options='header'] +|=== +|Parameter |Type |Required |Description + +|`table_name` +|String +|Yes +|Physical name of the table in the external warehouse. Must start with a letter or underscore, contain only letters, digits, and underscores, and be at most 128 characters. + +|`model_identifier` +|String +|Yes +|GUID or name of the model (worksheet) to link the input table to. + +|`table_definition` +|Object +|Yes +|Describes the table schema. See the table definition parameters below. +|=== + +==== Table definition + +[width="100%" cols="2,1,1,4"] +[options='header'] +|=== +|Parameter |Type |Required |Description + +|`referenced_columns` +|Array of Strings +|Yes +|Names of columns on the linked model to include as read-only reference (key) columns. At least one is required. Each name must match exactly one visible model column and resolve to exactly one physical base column. Formula, cohort, or constant columns cannot be referenced. + +|`new_columns` +|Array of Objects +|Yes +|List of new editable columns. Each column requires `name`, `data_type` (for example, `VARCHAR`, `DOUBLE`, `DATE`), and `type` (`ATTRIBUTE` or `MEASURE`). Optionally include `allowed_values` (at most 500 values) to create a fixed-choice column. + +|`referenced_column_time_dimensions` +|Array of Objects +|No +|Locks selected date columns to a specific time dimension (grain) at creation. Each entry has a `column_identifier` and a `time_dimension`. Accepted values: `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY`. +|=== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' \ + --data-raw '{ + "table_name": "forecast_data", + "model_identifier": "model-guid-here", + "table_definition": { + "referenced_columns": ["Region", "Quarter"], + "new_columns": [ + { + "name": "forecast_revenue", + "data_type": "DOUBLE", + "type": "MEASURE" + }, + { + "name": "confidence_level", + "data_type": "VARCHAR", + "type": "ATTRIBUTE", + "allowed_values": ["HIGH", "MEDIUM", "LOW"] + } + ] + } +}' +---- + +[#create-input-table-column] +== Add columns to an input table + +Adds one or more new editable columns to an existing input table. This widens the physical table in the CDW and refreshes the ThoughtSpot metadata. + +=== Endpoint + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create +---- + +=== Request body parameters + +[width="100%" cols="2,1,1,4"] +[options='header'] +|=== +|Parameter |Type |Required |Description + +|`column_definition.columns` +|Array of Objects +|Yes +|List of new editable columns. Each column requires `name`, `data_type`, and `type` (`ATTRIBUTE` or `MEASURE`). Optionally include `allowed_values`. +|=== + +=== Response + +Returns the added columns with their generated GUIDs. + +[source,JSON] +---- +{ + "columns": [ + { + "name": "forecast_revenue", + "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + } + ] +} +---- + +[#delete-input-table] +== Delete an input table + +Deletes an input table, unlinks it from its owner model, removes it from the connection metadata, and drops the physical table from the CDW. This action is irreversible. + +=== Endpoint + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/delete +---- + +=== Response + +Returns `204 No Content` on success. + +[NOTE] +==== +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. +==== + +[#delete-input-table-column] +== Delete an input table column + +Deletes a single editable column from an input table. This removes the column from the ThoughtSpot metadata and drops the physical column from the CDW. This action is irreversible. + +=== Endpoint + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete +---- + +Only columns added directly to the input table (editable, non-referenced columns) can be deleted. The request is rejected if the column is a referenced (model-projected) column or is still referenced by an existing Answer or Liveboard. + +Use the `id` field returned by `createInputTableColumn` or `createInputTable` as the `column_identifier`. + +=== Response + +Returns `204 No Content` on success. + +[#update-input-table] +== Write rows to an input table + +Writes rows into an existing input table using a keyed upsert (MERGE) operation. Rows are matched on the input table's key columns (the columns mapped to the linked model). Matched rows are updated in place. Unmatched rows are inserted. + +=== Endpoint + +---- +POST /api/rest/2.0/input-tables/{input_table_identifier}/update +---- + +=== Request body parameters + +[width="100%" cols="2,1,1,4"] +[options='header'] +|=== +|Parameter |Type |Required |Description + +|`columns` +|Array of Strings +|Yes +|Ordered list of column names to write. Must include every key column and at least one non-key column. + +|`rows` +|Array of Arrays +|Yes +|List of rows. Each row is an array of string values in the same order as `columns`. An empty value writes `NULL`. +|=== + +=== Date value handling + +* `DATE` columns accept ISO calendar dates (`yyyy-MM-dd`, for example `2025-01-01`). Epoch numbers are also accepted but resolved in the cluster's local time zone. +* `DATE_TIME` and `TIME` columns accept epoch numbers only. +* All values in a column must use the same format. + +=== Write semantics + +* **Matched rows**: only the non-key columns present in `columns` are overwritten. Columns not included keep their existing values. +* **New rows**: a new row is inserted. Non-key columns not included are set to `NULL`. +* This is not a full-table replace. Existing rows whose keys are not in the payload are untouched. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/{input_table_identifier}/update' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access_token}' \ + --data-raw '{ + "columns": ["Region", "Quarter", "forecast_revenue"], + "rows": [ + ["West", "Q1 2026", "500000"], + ["East", "Q1 2026", "750000"] + ] +}' +---- + +=== Response + +Returns `rows_loaded`, the number of rows written (updated + inserted). + +== Error codes + +[width="80%" cols="1,3"] +[options='header'] +|=== +|HTTP status |Description + +|`400` +|Invalid request. For example, a mismatched column name, missing key column, or incompatible data type. + +|`401` +|Unauthorized. The caller is not authenticated. + +|`403` +|Forbidden. The caller does not have the required privilege or permission. + +|`500` +|Unexpected server error. +|=== + +== Related information + +* xref:rest-api-v2-reference.adoc[REST API v2.0 Reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] From b277aca82dd858f5917b8440952147b19839460e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:36:06 +0530 Subject: [PATCH 022/169] docs: add November 2026 (26.11.0.cl) section to What's New SCAL-337999, SCAL-337682, SCAL-326037, SCAL-333822, SCAL-332820, SCAL-314932, SCAL-331936, SCAL-280403 --- modules/ROOT/pages/whats-new.adoc | 943 +----------------------------- 1 file changed, 1 insertion(+), 942 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 9628f34b3..ec6077f68 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -1,942 +1 @@ -= What's new -:toc: true -:toclevels: 1 -:page-title: What's new -:page-pageid: whats-new -:page-description: New features and enhancements - -This page lists new features, enhancements, and deprecated functionality introduced for ThoughtSpot Embedded instances in 2026. For information about the features introduced in the previous release versions, see xref:whats-new-prev-history.adoc[release history]. - -// ============================================================ -// VERSION TEMPLATE — copy this block for each new release -// ============================================================ -// -// -// [.version-badge.breaking]#Breaking# / -// [.version-badge.new]#New# / -// [.version-badge.deprecated]#Deprecated# / -// [.version-badge.fixed]#Fixed# -// -// *API version string:* `?api-version=YYYY-MM-DD` -// *Status:* Current / Supported / Deprecated -// *Affects:* Developers, Administrators, End Users -// ============================================================ - - -== October 2026 - -**Release version**: ThoughtSpot Cloud 26.10.0.cl + -*Upgrade notes*: ⚠️ Includes a deprecation and an upcoming change to API rate limits. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.53.0 or later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.10.0.cl* - -a| - -[discrete] -==== Spotter Analyst - -Embed Spotter Analyst:: -You can now embed a single, pinned Spotter Analyst in your application using the Visual Embed SDK. The `spotterAnalystConfig.analystId` property in `SpotterEmbed` locks the embed to one governed Analyst experience. For more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst]. - -Spotter Analyst APIs:: -Spotter Analysts are governed AI agents you can create, configure, and manage via the REST API. Four new endpoints are available under `/api/rest/2.0/ai/agent/analysts/` to create, search, update, and delete Analysts programmatically. Each Analyst is configured with a name, description, one or more data sources, and optional instructions, MCP connectors, and starter prompts. For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. - ---- - -[discrete] -==== Pinning Spotter conversations -Users can now pin Spotter conversations in the embedded view and through the REST API, so that pinned conversations appear at the top of the conversation list for quick access. For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations] and xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Spotter conversation APIs]. - ---- - -[discrete] -==== Feature management through APIs -ThoughtSpot now supports programmatic feature management with new REST API v2 endpoints available under `/api/rest/2.0/configurations/features/`. Cluster and Org admins can search feature configurations, assign features to Orgs, and set feature values without using the link:https://docs.thoughtspot.com/cloud/latest/admin-portal-2#_feature_management[new Admin portal, window=_blank]. For more information, see xref:feature-management-api.adoc[Feature Management]. - ---- - -[discrete] -==== Liveboard enhancements -* *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# -+ -Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]. - -* *Host Events* -+ -** The xref:HostEvent.adoc#_getgroups[`HostEvent.GetGroups`] event returns group details for the Liveboard, and the `applicability` attribute on `HostEvent.UpdateFilters` and `HostEvent.UpdateParameters` scopes filter updates to a specific tab or group. For more information, see xref:embed-events.adoc[Events and app interactions]. -** The xref:HostEvent.adoc#_openparameter[`HostEvent.OpenParameter`] event opens the parameter panel for a specific parameter on the Liveboard. It accepts an optional `applicability` object to scope the action to a tab or group. - -* *Centralized filter modal* in Liveboards is now generally available and enabled by default on ThoughtSpot embedded instances. - -* *Column security rules on Liveboards* -+ -Liveboards that were previously blocked by column security rules (CSR) now open and work normally, with column security fully enforced, including in embedded Liveboards. Filter values from inaccessible columns are masked instead of blocking the Liveboard, and scheduled Liveboard deliveries apply CSR separately for each recipient. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards]. - ---- - -[discrete] -==== HostEvent v1 framework deprecated [.version-badge.deprecated]#Deprecated# -Starting from ThoughtSpot Cloud 26.10.0.cl, the HostEvent v1 framework is deprecated and replaced by the HostEvent v2 framework, which provides context-aware event routing and stricter payload validation. If your embedded application uses HostEvent objects to trigger actions, evaluate the event behavior and its impact on your custom workflows in a development environment. For more information, see xref:deprecated-features.adoc#hostEventv1[HostEvent v1 framework deprecation] and the xref:hosteventsv2-migration.adoc[HostEvent v2 migration guide]. - ---- - -[discrete] -==== Upcoming changes to API rate limits -Starting from 26.11.0.cl, ThoughtSpot will enforce an API rate limit of 50 requests per second (RPS) per Org for all public REST API endpoints on instances with Orgs. This Org-level limit operates independently of the existing cluster-level limit of 100 RPS per client IP. - -ThoughtSpot recommends reviewing your existing API integrations to identify any workflows that may exceed 50 RPS within a single Org. Where possible, implement request throttling, and retry with exponential backoff when you receive an `HTTP 429: Too Many Requests` response. If your workflows require a higher rate limit, contact ThoughtSpot Support to discuss your requirements. - -For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. - ---- - -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.53.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. - ---- - -[discrete] -==== REST API -For information about REST API v2.0 enhancements in this release, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|=== - - -== September 2026 - -**Release version**: ThoughtSpot Cloud 26.9.0.cl + -*Upgrade notes*: No breaking changes in this release. + -*Recommended SDK versions*: Visual Embed SDK v1.52.0 or later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.9.0.cl* - -a| - -[discrete] -==== Full application embed - -Default page settings:: -You can now embed Collections list page and set it as the default landing page using `Page.Collections` enumeration value. For more information, see xref:set-default-page.adoc#_set_the_default_page_using_pageid[Customizing default page]. - -Navigation panel customization:: -Embed developers can include *Collections* as a navigation option in the left navigation panel in full application embeds. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. - -UI experience:: -The classic V1 and V2 navigation and home page experience modes are no longer supported. All embedded sessions use V3 navigation and homepage by default and the V4 homepage experience if enabled in the embed. - ---- - -[discrete] -==== Spotter embed - -Spotter visual experience enhancements:: -The Spotter interface is redesigned and enhanced to provide a more streamlined and conversational experience to embedding application users. The classic Spotter interface remains the default for existing deployments, and you can choose to enable the new experience using the `updatedSpotterExperience` parameter in the SDK. For more information, see xref:customize-spotter-embed.adoc#_spotter_interface_in_the_embedded_view[Spotter experience]. - -Spotter conversation sharing in embedded views:: -Users can now share saved Spotter conversations with other users and groups directly from the embedded Spotter interface or via REST APIs. For more information, see xref:customize-spotter-sharing.adoc[Customize Spotter conversation sharing] and xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. - ---- - - -[discrete] -==== Browser history management in embedded application -When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. - ---- - - -[discrete] -==== Lazy loading enabled by default for full-height embeds -To improve the initial load performance of large Liveboards, lazy loading is now enabled by default when `fullHeight` is set to `true`. For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of Liveboard visualizations]. - ---- - -[discrete] -==== Custom app scheme allowlisting for mobile embeds -ThoughtSpot now supports adding custom app schemes such as `capacitor://localhost` and `ionic://localhost` to the CSP and CORS allowlist. This allows mobile applications built with hybrid frameworks such as Capacitor and Ionic to embed ThoughtSpot content. For more information, see xref:security-settings.adoc#custom-app-schemes[Security settings]. - ---- - -[discrete] -==== Upcoming changes to `EmbedEvent.Error` framework -In the upcoming ThoughtSpot Cloud 26.10.0.cl and Visual Embed SDK 1.53.0 versions, `EmbedEvent.Error` will include a `severity` field that categorizes errors into three levels, `SEV1`, `SEV2`, and `SEV3`. ThoughtSpot recommends reviewing your error handling logic to prepare for this change. For more information, see xref:embed-event-error-best-practices.adoc[Handling embed errors]. - ---- - - -[discrete] -==== Personalized Views TML portability - -The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances. For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability]. - ---- - - -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.52.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. - ---- - - -[discrete] -==== REST API v2 -This release introduces new API endpoints for sharing Spotter conversations, managing Snowflake Semantic integrations, and other enhancements. -For more information, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - ---- - -|=== - -== 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:customize-spotter-analysts.adoc#_spotter_analysts[Customize Spotter Analysts]. - -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:customize-spotter-chat-experience.adoc#_spotter_starter_prompts[Enable starter prompts in Spotter]. - ---- - -[discrete] -==== Liveboard embedding enhancements -The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: - -* Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + -xref:customize-liveboard-filters.adoc#filter-visibility[Hides filters] that are not relevant to the displayed visualization in a tab. -* Compact header (`isLiveboardCompactHeaderEnabled`) + -Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:customize-liveboard-layout.adoc#compact-header[compact Liveboard header]. -* Cover page filtering options (`coverAndFilterOptionInPDF`) + -Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. -* Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + -Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. -* Filter interactivity (`isEnhancedFilterInteractivityEnabled`) + -Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. - ---- - -[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:deprecated-features.adoc#v1-v2-exp-fullApp-embed[V1 and V2 deprecation]. - ---- - -[discrete] -==== Wide logo dimension [.version-badge.breaking]#Breaking change# -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#logo-change[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-import.adoc#personalized-views-portability[Personalized Views portability]. - ---- - -[discrete] -==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking change# -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#liveboardDiscoverable[Deprecation announcements]. - ---- - -[discrete] -==== SpotterCode widget for documentation assistance -This developer documentation site now includes a SpotterCode AI assistant panel that replaces the earlier *AskDocs* feature. When you open the assistant panel, it displays prebuilt starter prompts relevant to the page you are currently viewing and allows you to explore topics instantly. You can also type your own questions about embedding, REST APIs, SDK configuration, and developer guides. For more information, see xref:spottercode.adoc[SpotterCode documentation]. - ---- - -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, 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 + -*Upgrade notes*: Includes breaking changes to SpotterCode + -*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.7.0.cl* - -a| -[discrete] -==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# -You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. - -For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. - ---- - -[discrete] -==== Spotter embedding - -Spotter file upload in embedded apps:: -Applications embedding the Spotter interface can now allow their users to xref:customize-spotter-chat-experience.adoc#fileUpload[upload files directly in the Spotter chat panel]. - -Spotter conversation history:: -You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. - -Spotter Agent instructions:: -You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. - ---- - -[discrete] -==== Focused home page experience [earlyAccess eaBackground]#Early Access# - -In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - ---- - -[discrete] -==== SpotterCode authentication and workflow execution [.version-badge.breaking]#Breaking# -SpotterCode now supports authenticated sessions with your ThoughtSpot instance. When connecting your MCP client to the SpotterCode endpoint, you are now prompted to log in using your organization's identity provider. After authentication, SpotterCode can make ThoughtSpot API calls on your behalf. - -For more information, see the documentation on xref:spottercode.adoc#_mcp_server_endpoints[SpotterCode MCP Server] and xref:spottercode-integration.adoc#_authenticate_spottercode[Authenticating SpotterCode]. - ---- - -[discrete] -==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# - -The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, provides a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically and accelerates building code and iterating embed configurations. - -For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. - ---- - -[discrete] -==== Webhooks enhancements - -ThoughtSpot introduces the following features and enhancements for webhook configuration and management: - -* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + -The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. -* Storage configuration retrieval + -The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. -* GCS storage configuration for webhook delivery + -Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. -* Webhook activation and deactivation + -You can enable or disable a webhook connection in the UI or through REST API. -* Selective configuration reset + -The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. - ---- - - -[discrete] -==== 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. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. - ---- - -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API v2 -For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - ---- - -|=== - -== June 2026 - -**Release version**: ThoughtSpot Cloud 26.6.0.cl + -*Upgrade notes*: No breaking changes. + -*Recommended SDK versions*: Visual Embed SDK v1.49.0 and later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.6.0.cl* - -a| -[discrete] -==== Chart and table overrides [.version-badge.new]#New# -You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: - -* Chart overrides + -Control legend visibility and position, data label display and per-column filter -thresholds, regression lines, grid lines, axis range and label settings, series -colors, and conditional formatting rules including font and background styling. -* Table overrides + -Control column visibility, text wrapping, row height and padding density, table -theme, and column summary visibility with per-column exceptions. - -For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. - ---- - -[discrete] -==== Spotter AI and embedding enhancements [.version-badge.new]#New# - -This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. - -* Spotter embedding: + -Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. -* Spotter AI APIs: + -//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. - New API endpoint xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. - ---- - -[discrete] -==== Developer page enhancements -The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: - -* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. -* Removal of REST API v1 + -The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. -* Removal of GraphQL playgrounds + -The menu link to the GraphQL playground has been removed from the UI. - -[discrete] -==== 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]. - ---- - -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API v2 -This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|=== - - -== May 2026 - -**Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + -*Recommended SDK versions*: Visual Embed SDK v1.48.0 and later - - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.5.0.cl* - -a| - - -[discrete] -==== Liveboard downloads - -Continuous Liveboard PDF export [beta betaBackground]^Beta^:: -In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. - -Liveboard download in XLSX and CSV formats:: -Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. - -Excel exports for pivot tables:: -Pivot table visualizations can now be exported to Excel format. - -For more information, see xref:liveboard-data-downloads.adoc#liveboard-download-options[Liveboard download options]. - ---- - -[discrete] -==== Visualization edit interface within the Liveboard view - -Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. - ---- - -[discrete] -==== KPI charts in embedded Liveboards - -Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. - ---- - -[discrete] -==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ - -You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. - -For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. - ---- - -[discrete] -==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ -ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. - -For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. - -[NOTE] -==== -The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. -==== - - ---- - -[discrete] -==== Visual Embed SDK -The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API v2 -This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|=== - - -== April 2026 - -**Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#_version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.47.0 and later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== - -a| -[.cl-label] -*Version 26.4.0.cl* - -a| - -[discrete] -==== Theme builder in AI mode - -The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. - -For more information, see xref:theme-builder.adoc[Theme builder]. - ---- - - -[discrete] -==== Webhook integration -In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: - -Channel validation:: -Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. - -Monitor webhook delivery:: -Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. - -Support for custom HTTP headers in webhook requests:: -When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks.adoc#_webhook_delivery_behavior[webhook documentation]. - ---- - - -[discrete] -==== Spotter embed enhancements -You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. - -You can also customize the branding and logo in the Spotter chat interface. - -For more information, see xref:customize-spotter-chat-experience.adoc[Customizing chat history sidebar] and xref:customize-spotter-chat-experience.adoc#_spotter_logo_and_thoughtspot_branding_label[Hiding logo and brand label in Spotter chat interface]. - ---- - -[discrete] -==== Liveboard enhancements -The following enhancements are introduced in Liveboard export and filtering workflows. - -Embedding a personalized Liveboard view:: -You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. - -Centralized filter modal:: -Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. - -Current period inclusion in rolling date filters:: -The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. - -Liveboard PNG export:: -The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard report API documentation]. - ---- - - -[discrete] -==== Full app embedding -In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. - -The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: - -* The **Views** column to show the number of views for each object. -* Sorting options for **Name**, **Author**, and **Views** columns. -* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. - -For more information, see xref:full-app-customize.adoc#_list_page_experience[List page customization]. - ---- - - -[discrete] -==== Variable API -The variable REST API provides new API endpoints for the following bulk operations: - -* Bulk deletion: -You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. -* Batch update of variable values: -You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. - -[NOTE] -==== -The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. -==== - -For more information, see xref:variables.adoc[Variables documentation]. - ---- - - -[discrete] -==== Metadata parameterization -You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. - ---- - - -[discrete] -==== Collections [beta betaBackground]^Beta^ -ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. - -For more information, see xref:collections.adoc[Collections]. - -[NOTE] -==== -These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. -==== ---- - -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. - - -[discrete] -==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - ---- -|=== - -== March 2026 - -**Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.46.0 and later - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== - -a| -[.cl-label] -*Version 26.3.0.cl* - -a| -[discrete] -==== Amazon S3 storage destination for webhook delivery -You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. - -For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. - ---- - -[discrete] -==== Host event enhancements for context-aware routing - -HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. - -Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. - -For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. - ---- - -[discrete] -==== JWT-based ABAC implementation -The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. - -As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: - -* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. - -* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. - -Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. - -For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. - ---- - -[discrete] -==== Spotter coaching access across published Orgs -Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. - -Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. - -Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. - -For more information, see xref:spotter-nl-instructions.adoc#_allowing_access_to_spotter_data_model_instructions[Allowing access to Spotter data model instructions]. - ---- - -[discrete] -==== Full application embedding -The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. - -If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. - -For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. - ---- - -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - ---- - -|=== - -== February 2026 -**Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + -*Recommended SDK versions*: Visual Embed SDK v1.45.0 and later - - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 26.2.0.cl* - -a| -[discrete] -==== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# - -ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. - -SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. - ---- - -[discrete] -==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# -You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. - -For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. - ---- - -[discrete] -==== Rate limits for REST APIs -To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. -//Administrators can adjust these limits for their ThoughtSpot deployments as needed. - -For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. - ---- - -[discrete] -==== Security settings via REST APIs -Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: - -* Content Security Policy (CSP) -* Cross-origin Resource Sharing (CORS) -* Authentication attributes -* Access control settings - -For more information, see xref:security-settings.adoc[Security Settings]. - ---- - -[discrete] -==== WebSocket support for external tools -ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. - -To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. - -For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. - ---- - - -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API v2 -For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - ---- -|=== - - -== January 2026 - -**Release version**: ThoughtSpot Cloud 10.15.0.cl + -*Upgrade notes*: No breaking changes. + -*Recommended SDK versions*: Visual Embed SDK v1.44.0 and later - - -[.cl-table, cols="2,4", frame=none, grid=none] -|=== -a| -[.cl-label] -*Version 10.15.0.cl* - -a| -[discrete] -==== Theme Builder -Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. - -When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. - -For more information, see xref:theme-builder.adoc[Theme Builder]. - ---- - -[discrete] -==== V3 navigation and home page experience - -The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. - -The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. - -For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. - ---- - -[discrete] -==== Formula variables in RLS rules - -You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. - -For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - ---- - -[discrete] -==== Spotter APIs - -ThoughtSpot introduces new REST APIs for the following Spotter workflows: - -* To send queries to a conversation session with the Spotter agent -* To set data model instructions on a model to coach the Spotter system -* To fetch data model instructions configured on a model - -For more information, see xref:spotter-apis.adoc[Spotter APIs]. - ---- - -[discrete] -==== Embed events and parameters to intercept API calls -You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. - ---- - -[discrete] -==== Icon customization enhancements - -You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. - ---- - -[discrete] -==== Mobile Embed SDK -The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. - ---- - -[discrete] -==== Visual Embed SDK -For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. - ---- - -[discrete] -==== REST API -For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. - -|=== \ No newline at end of file +Unknown tool: github_get_file \ No newline at end of file From 57abfdb73a6a02c460d1d1458177d1fe3776a25a Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:36:07 +0530 Subject: [PATCH 023/169] docs: add November 2026 (26.11.0.cl) section to What's New SCAL-337999, SCAL-337682, SCAL-326037, SCAL-333822, SCAL-332820, SCAL-314932, SCAL-331936, SCAL-280403 From a6e87d0ee87eaadacf6aadc89ab1fa5c4d1cedb3 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:37:10 +0530 Subject: [PATCH 024/169] docs: add November 2026 entry to REST API v2.0 changelog SCAL-337999, SCAL-337682, SCAL-332820 --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1530 +----------------- 1 file changed, 39 insertions(+), 1491 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 235280ad0..efb7e8443 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -1,1508 +1,56 @@ -= REST API v2.0 changelog -:toc: true -:toclevels: 1 +--- CITABLE SOURCE --- +File: modules/ROOT/pages/rest-apiv2-changelog.adoc +Branch: docs/scal-26-11-0-cl-doc-updates +URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc +To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc#L{line_number} +--- -:page-title: REST API v2.0 changelog -:page-pageid: rest-v2-changelog -:page-description: Changelog of REST APIs +{ + "path": "modules/ROOT/pages/rest-apiv2-changelog.adoc", + "name": "rest-apiv2-changelog.adoc", + "size": 77050, + "content": "= REST API v2.0 changelog\n:toc: true\n:toclevels: 1\n\n:page-title: REST API v2.0 changelog\n:page-pageid: rest-v2-changelog\n:page-description: Changelog of REST APIs\n\nThis 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].\n\n== Version 26.11.0.cl, November 2026 -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]. + === Org-level API rate limiting enforced + The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response. -== Version 26.10.0.cl, October 2026 + For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. -=== Spotter AI APIs + === Link Customization APIs + ThoughtSpot introduces two REST API v2.0 endpoints for managing the URL templates used when ThoughtSpot generates shareable links. -Spotter Analyst APIs:: -ThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically. + * `POST /api/rest/2.0/customization/links/search` + + Retrieves the URL templates at the cluster level or for the Org the caller is signed in to. + * `POST /api/rest/2.0/customization/links/update` + + Updates the URL templates at the cluster level or for the caller's Org, using `REPLACE` to set templates or `RESET` to clear overrides. -* `POST /api/rest/2.0/ai/agent/analysts/create` + -Creates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts. -* `POST /api/rest/2.0/ai/agent/analysts/search` + -Returns the Spotter Analysts visible to the caller. -* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` + -Updates a Spotter Analyst. -* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` + -Deletes a Spotter Analyst. -+ -For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. + Supported link types include `LIVEBOARD_SHARE_URL`, `VISUALIZATION_SHARE_URL`, `ANSWER_SHARE_URL`, `SPOTIQ_ANALYSIS_URL`, `UNSUBSCRIBE_URL`, `GENERIC_URL`, and `CONVERSATION_SHARE_URL`. -Pin conversations in the update conversation API:: -The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation]. + Requires `ADMINISTRATION` or `DEVELOPER` privilege. -Spotter conversation enhancements:: + For more information, see xref:link-customization-api.adoc[Link Customization APIs]. -* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation. -* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification. + === Input Table APIs + ThoughtSpot introduces REST API v2.0 endpoints for creating and managing input tables programmatically. -=== TML and metadata type additions + * `POST /api/rest/2.0/input-tables/create` -- Creates an input table and links it to a model (worksheet). + * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` -- Adds editable columns to an existing input table. + * `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` -- Deletes an input table and drops the physical CDW table. + * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` -- Deletes a single column from an input table. + * `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` -- Writes rows into an input table using a keyed upsert (MERGE) operation. -* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`. -* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response. + Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. If RBAC is enabled, the `CAN_MANAGE_INPUT_TABLES` privilege is required. -=== Databricks semantic integrations + For more information, see xref:input-table-api.adoc[Input Table APIs]. -The `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it. + === Share Analyst API -=== Feature Management API -This release introduces the following new REST API v2.0 endpoints for programmatic feature management. + `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share`:: + Updates share permissions on a Spotter Analyst for one or more principals (users or groups). Supports `READ_ONLY`, `MODIFY`, and `NO_ACCESS` share modes. Granting access also shares the Analyst's data sources with the recipient. Requires ownership of the Analyst, or `ADMINISTRATION` or `CAN_MANAGE_SPOTTER` privilege. + + + For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. -* `POST /api/rest/2.0/configurations/features/search` + -Returns feature configurations grouped by feature group. -* `POST /api/rest/2.0/configurations/features/assignments/update` + -Updates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations. -* `POST /api/rest/2.0/configurations/features/values/update` + -Sets feature value at `CLUSTER` or `ORG` scope. -For more information, see xref:feature-management-api.adoc[Feature Management API]. + == Version 26.10.0.cl, October 2026\n\n=== Spotter AI APIs\n\nSpotter Analyst APIs::\nThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically.\n\n* `POST /api/rest/2.0/ai/agent/analysts/create` +\nCreates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts.\n* `POST /api/rest/2.0/ai/agent/analysts/search` +\nReturns the Spotter Analysts visible to the caller.\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` +\nUpdates a Spotter Analyst.\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` +\nDeletes a Spotter Analyst.\n+\nFor more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\n\nPin conversations in the update conversation API::\nThe `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation].\n\nSpotter conversation enhancements::\n\n* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation.\n* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification.\n\n=== TML and metadata type additions\n\n* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`.\n* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response.\n\n=== Databricks semantic integrations\n\nThe `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it.\n\n=== Feature Management API\nThis release introduces the following new REST API v2.0 endpoints for programmatic feature management.\n\n* `POST /api/rest/2.0/configurations/features/search` +\nReturns feature configurations grouped by feature group.\n* `POST /api/rest/2.0/configurations/features/assignments/update` +\nUpdates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations.\n* `POST /api/rest/2.0/configurations/features/values/update` +\nSets feature value at `CLUSTER` or `ORG` scope.\n\nFor more information, see xref:feature-management-api.adoc[Feature Management API].\n\n=== Multi-Org tokens [beta betaBackground]^Beta^\n\nAuthentication token endpoints now support Org scope at issuance and inspection:\n\n* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens.\n* Token responses, including `POST /api/rest/2.0/auth/token/validate`, retrun `scope/org_scope` and `scope/org_ids`, indicating the Orgs the token is authorized for.\n* API requests made with a multi-Org token select the target Org using the `X-Org-Selector` header. The header selects from the Orgs already authorized on the token; it does not grant new access.\n\nFor more information, see xref:authentication.adoc#multi-org-tokens[Multi-Org tokens].\n\n== Version 26.9.0.cl, September 2026\n\n=== Answer Export API\n\nThe following enhancements for the `POST /api/rest/2.0/report/answer` endpoint are now GA:\n\n`type` parameter::\nThe request body accepts a new `type` parameter that specifies the kind of Answer to export:\n+\n* `SAVED` (default): exports a saved Answer.\n* `PINNED`: exports a pinned Answer from a Liveboard.\n\nPinned Answer export::\nSet `type` to `PINNED` to export a pinned Answer (a visualization on a Liveboard) directly. The Answer downloads with Liveboard context: Liveboard-level filters, Runtime Filters, and Column Security Rules are applied automatically.\n\nPersonalized View support::\nPass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard.\n\nSpotter Answer export::\nXLSX and PDF export formats are now supported for Spotter-generated Answers, in addition to CSV and PNG.\n\nCustom PNG dimensions::\nUse `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports.\n\nDisplay scaling::\nUse `scaling` to adjust the relative size of chart elements in a PNG export without cropping the image.\n\nDynamic file naming::\nExported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended.\n\nFor more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API].\n\n=== Snowflake Semantic View integration APIs\nThis release introduces the following new REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically.\n\n* `POST /api/rest/2.0/semantic-integrations/create` +\nCreates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model.\n* `POST /api/rest/2.0/semantic-integrations/search` +\nReturns a list of semantic integrations matching the specified filter criteria.\n* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +\nRe-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model.\n* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` +\nDeletes a semantic integration and its generated ThoughtSpot data model.\n\nFor more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs].\n\n=== Conversation sharing APIs\nThoughtSpot introduces the following REST API v2.0 endpoints to share Spotter agent conversations with other users or groups.\n\n* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` +\nShare a conversation with users or groups with `READ_ONLY` access.\n* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` +\nRetrieve the shared messages and answers in a conversation.\n* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` +\nRetrieve the list of principals a conversation is shared with and their access levels.\n\nFor more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations].\n\n=== KPI Sparkline setting in metadata search response\nThe `POST /api/res -=== Multi-Org tokens [beta betaBackground]^Beta^ - -Authentication token endpoints now support Org scope at issuance and inspection: - -* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens. -* Token responses, including `POST /api/rest/2.0/auth/token/validate`, retrun `scope/org_scope` and `scope/org_ids`, indicating the Orgs the token is authorized for. -* API requests made with a multi-Org token select the target Org using the `X-Org-Selector` header. The header selects from the Orgs already authorized on the token; it does not grant new access. - -For more information, see xref:authentication.adoc#multi-org-tokens[Multi-Org tokens]. - -== Version 26.9.0.cl, September 2026 - -=== Answer Export API - -The following enhancements for the `POST /api/rest/2.0/report/answer` endpoint are now GA: - -`type` parameter:: -The request body accepts a new `type` parameter that specifies the kind of Answer to export: -+ -* `SAVED` (default): exports a saved Answer. -* `PINNED`: exports a pinned Answer from a Liveboard. - -Pinned Answer export:: -Set `type` to `PINNED` to export a pinned Answer (a visualization on a Liveboard) directly. The Answer downloads with Liveboard context: Liveboard-level filters, Runtime Filters, and Column Security Rules are applied automatically. - -Personalized View support:: -Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. - -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter-generated Answers, in addition to CSV and PNG. - -Custom PNG dimensions:: -Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. - -Display scaling:: -Use `scaling` to adjust the relative size of chart elements in a PNG export without cropping the image. - -Dynamic file naming:: -Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. - -For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API]. - -=== Snowflake Semantic View integration APIs -This release introduces the following new REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. - -* `POST /api/rest/2.0/semantic-integrations/create` + -Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. -* `POST /api/rest/2.0/semantic-integrations/search` + -Returns a list of semantic integrations matching the specified filter criteria. -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + -Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. -* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + -Deletes a semantic integration and its generated ThoughtSpot data model. - -For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. - -=== Conversation sharing APIs -ThoughtSpot introduces the following REST API v2.0 endpoints to share Spotter agent conversations with other users or groups. - -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` + -Share a conversation with users or groups with `READ_ONLY` access. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` + -Retrieve the shared messages and answers in a conversation. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` + -Retrieve the list of principals a conversation is shared with and their access levels. - -For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. - -=== KPI Sparkline setting in metadata search response -The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` parameter in the `AnswerSpecHeader` object for KPI chart type answers. This boolean parameter indicates whether the sparkline trend line is enabled for the KPI visualization. - -//// -=== Outline Encoding for Muze charts -Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. - -The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. -//// - -=== Personalized Views TML portability -The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances: - -* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained while delegating ownership to another user during import. -* The `obj_id` field provides a stable cross-environment identifier for inter-Org deployments. -* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. - -For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability in TML]. - -=== Support for Scheduled Liveboards process type in Connection configuration -The connection configuration API endpoints now support `SCHEDULED_LIVEBOARDS` as a process type: - -* `POST /api/rest/2.0/connection/configuration/create` -* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` - -Administrators can add `SCHEDULED_LIVEBOARDS` as a valid process type for connection configurations, allowing scheduled Liveboard delivery jobs to use an alternative connection configuration, with separate warehouse, credentials, or non-OAuth authentication instead of the parent connection's defaults. - -== Version 26.8.0.cl, August 2026 - -=== Spotter AI APIs - -Spotter memory APIs::: -ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter memory programmatically: - -* `POST /api/rest/2.0/ai/memory/import` + -Imports Spotter 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 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 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-import.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. - - -=== 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 C# SDK -ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. - -For information about how to install and use the SDK, see xref:rest-api-csharp-sdk.adoc[C# SDK for REST APIs]. - -== Version 26.7.0.cl, July 2026 - -=== Spotter AI APIs - -Save chat AI APIs:: -ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. - -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates attributes of an existing agent conversation. -* `GET /api/rest/2.0/ai/agent/conversations` + -Retrieves the list of saved agent conversations for the currently authenticated user. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + -Retrieves the full content of a saved conversation with Spotter agent. -* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates the display title of a saved conversation. -* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + -Deletes a saved conversation and all its associated messages. -* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + -Loads the full answer payload for a specific answer item in an agent conversation. - -+ -For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. - -Save chat settings in conversation create API:: - -The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. - -Agent instructions APIs:: -The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. - -* `PUT /api/rest/2.0/ai/agent/instructions/set` + -Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. - -* `GET /api/rest/2.0/ai/agent/instructions/get` + -Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. -+ -For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. - -=== Webhooks - -New API endpoint:: -The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. - -Enhancements:: - -* 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 - -The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. - -=== Style customization APIs - -ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. - -Style configuration:: - -* `POST /api/rest/2.0/customization/styles/search` + -Returns the current style configuration at the `CLUSTER` or active `ORG` scope. - -* `POST /api/rest/2.0/customization/styles/update` + -Updates style settings at the `CLUSTER` or `ORG` scope. - -Custom fonts:: - -* `POST /api/rest/2.0/customization/styles/fonts/upload` + -Uploads a custom font file to ThoughtSpot. - -* `POST /api/rest/2.0/customization/styles/fonts/search` + -Returns custom fonts uploaded to the instance. - -* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates the display name, weight, style, or color of an existing custom font. - -* `POST /api/rest/2.0/customization/styles/fonts/delete` + -Deletes one or more custom fonts from the font library. - -Logo export:: - -* `POST /api/rest/2.0/customization/styles/logos/export` + -Exports the current logo files as a ZIP archive containing the default logo and the wide logo. - -For more information, see xref:customize-style-api.adoc[Style customization APIs]. - -=== Manual translation APIs -The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. - -* `POST /api/rest/2.0/localizations/manual-translation/import` + -Allows importing a CSV file containing translated terms and labels. -* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + -Retrieves all translations for a specific locale as a JSON map. -* `POST /api/rest/2.0/localizations/manual-translation/export` + -Downloads all manually translated terms and labels in the Org context as a CSV file. -* `POST /api/rest/2.0/localizations/manual-translation/delete` + -Deletes all manual translations from the Org. - -For more information, see xref:manual-translation.adoc[Manual translations]. - -=== 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 how to install and use the SDK, see xref:rest-api-python-sdk.adoc[Python SDK]. - -== Version 26.6.0.cl, June 2026 - -=== Spotter AI APIs - -Stop in-progress agent response:: - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + -Stops a Spotter agent response that is currently in progress for a given conversation session. - -For more information, see xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. - -=== Authentication -The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. - -* `POST /api/rest/2.0/auth/configure` + -Enables or disables authentication at cluster or Org level for the specified auth type. -* `POST /api/rest/2.0/auth/search` + -Returns the authentication configuration for the specified auth type at cluster and Org level. - -=== Connection deactivate and activate API [beta betaBackground]^Beta^ - -// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 - -ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: - -* `POST /api/rest/2.0/connections/{connection_identifier}/status` + -Deactivates or activates a connection. - -=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# - -The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: - -Pinned Answer export:: -// SOURCE: SCAL-236681, SCAL-306548 -You can now export a pinned Answer directly from a Liveboard using the Answer report API. -To export a pinned Answer, specify the `viz_guid` parameter in your API request. -Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. -+ -To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. - -Spotter Answer export:: -XLSX and PDF export formats are now supported for Spotter (conversational) Answers. - -Custom PNG dimensions:: -PNG exports now support custom dimensions via the following new parameters: -+ -* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. -* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. - -Display scaling:: -A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. -Valid range: 80–500%. - -Automatic file naming:: -The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). - -Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. -For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer report API documentation]. - -=== Share metadata API: Collections support [beta betaBackground]^Beta^ - -The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. - -To share a Collection, set `metadata_type` to `COLLECTION` in the request body. -For more information, see xref:collections.adoc#share-collection[Share a Collection]. - -== Version 26.5.0.cl, May 2026 - -=== Sync connection metadata attributes -You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. - -=== Spotter APIs - -==== New API endpoints - -The following new endpoints allow sending messages to an active conversation -session with a Spotter agent. - -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + -Allows sending a message to an active Spotter AI conversation and returns a synchronous response. -* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + -Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. - -These new endpoints replace the legacy agent conversation and SSE streaming APIs. - -==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# - -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. - -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` - -These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. - -==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# - -The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: - -metadata_context:: -To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: - -* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. -* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. -** To set a single data source object metadata context, specify a `data_source_identifier`. -** For multi-data source context, specify the `data_source_identifiers`. -+ -[IMPORTANT] -==== -The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. -==== - -Other context options:: -The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. - -Enable save chat:: -The `enable_save_chat` parameter, when set to `true`, saves the conversation. - -API response:: -The API response now returns the `conversation_identifier`, which is used in all -subsequent send message or SSE streaming calls. - -=== Liveboard report API enhancements [beta betaBackground]^Beta^ -The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: - -* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. -* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. - -For more information, see xref:report-apis-v2.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 -The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-import.adoc[TML import documentation]. - -== Version 26.4.0.cl, April 2026 - -=== Variable API endpoints -The following endpoints are introduced for bulk delete and update operations for variables: - -* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + -Assigns multiple values to a variable and sets the scope for variable values in a single API request. -* `POST /api/rest/2.0/template/variables/delete` + -Deletes one or more variables in a single API request. - -These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. - -* `POST /api/rest/2.0/template/variables/{identifier}/delete` -* `POST /api/rest/2.0/template/variables/update-values` - -Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. - -For more information, see xref:variables.adoc[Variable API documentation]. - -=== Metadata parameterization -You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. -This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. - -For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. - -=== Webhook integration -This release introduces the following features and enhancements to the webhook integration workflows: - -Custom HTTP headers in webhook requests:: -Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. - -Webhook connection validation:: -You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. - -Webhook monitoring:: -To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. - -For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. - -=== Collections API endpoints - -The following APIs are introduced for Collections: - -* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + -Creates a new Collection. -* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + -Searches for a Collection in ThoughtSpot -* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + -Updates an existing Collection -* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + -Deletes a Collection - -For more information, see xref:collections.adoc[Collections]. - -=== Email customization API enhancements - -The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. - -=== Spotter API enhancements -Spotter AI APIs now support the following error responses: - -* 401 Unauthorized: authentication token is missing, expired, or invalid. -* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. - -=== Pivot table .xlsx exports -The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: - -* `POST /api/rest/2.0/report/answer` -* `POST /api/rest/2.0/schedules/create` - -To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. - -== Version 26.3.0.cl, March 2026 - -=== Webhook APIs - -The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. - -* `POST /api/rest/2.0/webhooks/create` + -Configures storage destination for webhook delivery. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + -Allows modifying storage configuration for a webhook. -* `POST /api/rest/2.0/webhooks/search` + -Retrieves storage configuration details. - -=== Object privilege APIs -Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. - -To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. - -For more information, see xref:spotter-nl-instructions.adoc#_allowing_access_to_spotter_data_model_instructions[Allowing access to Spotter data model instructions]. - - -=== User API enhancements - -The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: - -* When creating a new user via `POST /api/rest/2.0/users/create` + -* When importing users via `POST /api/rest/2.0/users/import` + -* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + - -When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. - -The status of the browser language setting for a given user can also be retrieved using the following API endpoints: - -* `POST /api/rest/2.0/users/search` + -* `POST /api/rest/2.0/users/activate` + -* `GET /api/rest/2.0/auth/session/user` + - -=== Custom token generation API -Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: - -* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. - -* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. - -For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. - -== Version 26.2.0.cl, February 2026 - -=== Security settings APIs -This release introduces the following Security settings APIs: - -* `POST /api/rest/2.0/system/security-settings/configure` + -Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. -* `POST /api/rest/2.0/system/security-settings/search` + -Gets a list of security settings configured on a specific Org or for all Orgs on a ThoughtSpot instance. - -For more information, see xref:security-settings.adoc[Security Settings]. - -=== Connection API -ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. - -=== Connection configuration API enhancements -You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. - -The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. - -=== Liveboard Report API enhancements -You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. - -For more information, see xref:report-apis-v2.adoc[Report APIs]. - -=== Email customization API enhancements - -The `template_properties` parameter now has two additional elements for email template customization: - -* `contact_support_url` to add a customized link for contacting customer support. -* `hide_contact_support_url` to hide the option of adding a link for customer support. - -=== System configuration API enhancements -The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. - -=== User API enhancements - -* `POST /api/rest/2.0/users/import` + -The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. -* `POST /api/rest/2.0/users/search` + -The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. - -== Version 10.15.0.cl, December 2025 - -=== Spotter APIs - -This release introduces the following Spotter APIs: - -* `POST /api/rest/2.0/ai/instructions/set` + -Allows configuring data model instructions to define how Spotter interprets queries, handles data nuances, and improves responses. -* `POST /api/rest/2.0/ai/instructions/get` + -Gets data model instructions that are currently assigned to a model. -* `POST /api/rest/2.0/ai/data-source-suggestions` + -Retrieves a list of recommended data sources based on the specified query string. - -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -=== Variable APIs - -You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. - -For more information, see xref:variables.adoc[Configure variables]. - -=== ABAC tokens with formula variable attributes -The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. - -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -== Version 10.14.0.cl, November 2025 - -=== New API endpoints - - - -System:: -This release introduces the following endpoints for configuring communication channel preferences. - -* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + -Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. -* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + -Gets details of the communication channel preferences configured on ThoughtSpot. -+ -For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. - -Webhook:: -The following APIs are introduced for webhook CRUD operations: -* `POST /api/rest/2.0/webhooks/create` -Creates a webhook. -* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` -Updates the properties of a webhook. -* `POST /api/rest/2.0/webhooks/search` -Gets a list of webhooks configured in ThoughtSpot or in a specific Org. -* `POST /api/rest/2.0/webhooks/delete` -Deletes the webhook. -+ -For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. - -Column security rules:: - -* `POST /api/rest/2.0/security/column/rules/update` + -Updates column security rules for a given Table. - -* `POST /api/rest/2.0/security/column/rules/fetch` + -Gets details of column security rules for the tables specified in the API request. - -//// - -Spotter:: -POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse -//// -=== Variable API enhancements - -The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. - -==== Variable creation API - -* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. -* The `sensitive` parameter is renamed as `is_sensitive`. - -==== Variables update APIs [tag redBackground]#BREAKING CHANGE# - -The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + -To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. - -==== Variables search API - -* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. -* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. - - -=== User API enhancements -The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. - -* `POST /api/rest/2.0/users/create` -* `POST /api/rest/2.0/users/search` -* `POST /api/rest/2.0/users/activate` - -=== DBT API enhancements -The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. - -//// - -=== Authentication API -Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. - -//// - -== Version 10.13.0.cl, October 2025 - -=== New API endpoints - -Spotter:: - -* `POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + - - -* `POST /api/rest/2.0/ai/relevant-questions/` + -Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. - -* `POST /api/rest/2.0/ai/agent/converse/sse` + -Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + - -For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. - -Email customization:: -`POST /api/rest/2.0/customization/email/update` + -Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== API enhancements -The following APIs were modified to include new parameters: - -TML export:: -The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. - -Email customization:: -The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. - -For more information, see xref:customize-email-apis.adoc[Customize email template]. - -=== Deprecated endpoints - -Spotter:: -The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. - -Email customization:: -The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. - - -//// -=== Deprecated endpoints -The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. - -* `POST /api/rest/2.0/ai/conversation/create` -* `POST /api/rest/2.0/ai/analytical-questions` -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` -//// - -== Version 10.12.0.cl, September 2025 - -=== New API endpoints - -The following API endpoints are now available: - -Custom calendar:: -* `POST /api/rest/2.0/calendars/create` + -Creates a custom calendar. -* `POST /api/rest/2.0/calendars/generate-csv` + -Exports a custom calendar in the CSV format. -* `POST /api/rest/2.0/calendars/search` + -Gets custom calendars for the connection ID specified in the API request. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + -Deletes a custom calendar. -* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + -Updates a custom calendar. - -Connection configuration:: -* `POST /api/rest/2.0/connection-configurations/create` + -Creates an additional configuration to an existing connection to a data warehouse. -* `POST /api/rest/2.0/connection-configurations/search` + -Gets the required connection configuration objects. -* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + -Updates an existing connection configuration object. -* `POST /api/rest/2.0/connection-configurations/delete` + -Deletes the connection configuration object. - -=== Enhancements to APIs - -Export API endpoint:: - -* Answer TML: + -The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. - -* Table TML: + -The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. - -== Version 10.11.0.cl, July 2025 - -=== Search metadata API enhancements -The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: - -* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. -* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. -* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. - - -=== System API -The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. - -=== TML API -The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. - -=== REST API Java SDK - -The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. - -For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. - -== Version 10.10.0.cl, July 2025 - -=== Email template customization APIs -This release introduces the following new endpoints for email template customization: - -* `POST /api/rest/2.0/customization/email` + -Allows you to personalize the ThoughtSpot notification emails content. -* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + -Removes the customizations done for the ThoughtSpot notification emails. -* `POST /api/rest/2.0/customization/email/search` + -Allows searching the email customization configuration if configured for ThoughtSpot. -* `POST /api/rest/2.0/customization/email/validate` + -Validates the email customization configuration if configured for ThoughtSpot. - -=== Group API - -The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: - -* `include_users` + -When set to `true`, it includes user details in the group search API response. -* `include_sub_groups` + -When set to `true`, it includes sub-groups in the group search response. - -=== Schedule API -You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: - -* `POST /api/rest/2.0/schedules/create` -To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. - -== Version 10.9.0.cl, June 2025 - -=== Metadata parameterization and content publishing across Orgs - -This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. - -* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + -Allows you to parameterize fields in metadata objects. -* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + -Allows removing parameterization from fields in metadata objects -* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + -Publish metadata objects to one or several Orgs on an instance. -* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + -Removes published metadata objects from the Orgs specified in the API request. -* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + -Allows creating a template variable which can be used to parameterize fields in a metadata object. -* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + -Allows searching template variables -* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + -Allows updating properties of a template variable. -* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + -Allows you to add, remove, or replace properties of one or several template variables. -* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + -Deletes a template variable. - -If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. - -=== Liveboard Report API -The Liveboard Report API now allows you to define the following properties: - -* `tab_identifiers` + -Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. -* `personalised_view_identifier` + -Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. - -In addition to these parameters, you can also define the following properties for PNG downloads: - -* `image_resolution` -* `image_scale` -* `include_header` - -For more information, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API]. - -=== REST API Java SDK - -The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. - -For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. - - -== Version 10.8.0.cl, April 2025 - -=== New API endpoints - -This version introduces the following endpoints: - -* `POST /api/rest/2.0/metadata/update-obj-id` + -Update object IDs for given metadata objects. + - -[NOTE] -==== -An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. -Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. -==== - -=== Metadata API - -* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: - -** `include_discoverable_objects` + -Allows including Answers and Liveboards that are marked as discoverable by the object owner. -** `metadata_obj_id` + -Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. - -=== TML APIs - -* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. - -* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. - -=== Report APIs -The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. - -For more information, see xref:report-apis-v2.adoc#_override_filters[Override filters]. - -== Version 10.6.0.cl, March 2025 - -=== New metadata API endpoints - -* `POST /api/rest/2.0/metadata/headers/update` + -Updates metadata header for a given list of objects. -* `POST /api/rest/2.0/metadata/worksheets/convert` + -Converts a Worksheet object to a Model. - -=== Report APIs -[tag redBackground]#BREAKING CHANGE# - -Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. - -==== Parameters for regional settings - -The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: - -* `currency_format` -* `user_locale` -* `number_format_locale` -* `date_format_locale` - -=== Custom object ID in TML and Metadata APIs - -The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: - -* `POST /api/rest/2.0/metadata/search` -* `POST /api/rest/2.0/metadata/headers/update` -* `POST /api/rest/2.0/metadata/tml/export` + - -=== TML import API - -The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. - -=== API response changes - -The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. - - -== Version 10.5.0.cl, December 2024 - -=== Custom access token API -The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: - -* `auto_create` + -Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. -* `REPLACE` enum for `persist_option` + -Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -=== TML import APIs - -TML async import:: - -The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: -+ -* `import_policy` + -Allows you to specify if all objects should be imported during the TML import operation. Valid values are: - -** `PARTIAL_OBJECT` (default) -** `PARTIAL` -** `VALIDATE_ONLY` -** `ALL_OR_NONE` - -* `enable_large_metadata_validation` + -Indicates if the TMLs with large and complex metadata should be validated before the import. -+ -For more information about these attributes, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -TML import API:: - -The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. - -TML export API:: - -The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: - -* `include_obj_id_ref` + -Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_guid` + -Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. -* `include_obj_id` + -Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. - - -Share metadata:: - -The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. - -Role API:: - -The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. - -== Version 10.4.0.cl, November 2024 - -=== New API endpoints - -Spotter AI APIs [beta betaBackground]^Beta^ :: - -* `POST /api/rest/2.0/ai/conversation/create` + -Creates a conversation session. -* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + -Generates responses for user queries and follow-up questions. -* `POST /api/rest/2.0/ai/answer/create` + -Generates an Answer from a Natural Language Search query. - -Authentication:: -The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. - -+ -ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. - -Connections:: -The following new API endpoints are available for updating and deleting a connection object: - -* `POST /api/rest/2.0/connections/{connection_identifier}/update` -* `POST /api/rest/2.0/connections/{connection_identifier}/delete` - -+ -ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. - -TML:: -The following API endpoints are available for asynchronous TML import: - -* `POST /api/rest/2.0/metadata/tml/async/import` + -Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. -* `POST /api/rest/2.0/metadata/tml/async/status` + -Fetches task status for the async TML import operations. - -For more information, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. - -=== API enhancements - -User session:: - -* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. - -* You can now manage account activation status for IAMv2 users using the following API endpoints: - -** `POST /api/rest/2.0/users/create` + -** `POST /api/rest/2.0/users/{user_identifier}/update` - -Report API:: - -The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: - -* `session_identifier` + -Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. -* `generation_number` + -Number assigned to the Answer session with Spotter. -+ -If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. - -=== Deprecated features - -Connection APIs:: - -The following connection API endpoints are deprecated: - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` - -+ -Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. - -Authentication:: - -The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. -+ -ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. - -== Version 10.3.0.cl, October 2024 - -=== New API endpoint - -You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. - -== Version 10.1.0.cl, August 2024 - -=== New API endpoints - -* `POST /api/rest/2.0/metadata/tml/export/batch` + -Exports a batch of TML for user, user group, or Role objects. - -=== Security APIs -The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: - -* `record_offset` + -Specifies the starting record number from which the records for each metadata type will be included in the API response. -* `record_size` + -Specifies the number of records that should be included for each metadata type in the API response. -* `permission_type` + -Specifies the type of permission. Valid values are: -** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. -** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. - -== Version 10.0.0.cl, July 2024 - -=== Roles - -You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: - -* `POST /api/rest/2.0/roles/create` -* `POST /api/rest/2.0/roles/{role_identifier}/update` - -The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. - -== Version 9.12.0.cl, May 2024 - -=== New features - -Authentication API:: - -* `/api/rest/2.0/auth/token/validate` + -Validates the authentication token of the logged-in user. - -TML API:: -The export TML API requests now support the following parameters: -+ -* `export_schema_version` + -Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + -* `export_dependent` + -Allows exporting dependent Tables while exporting a Connection. -* `export_connection_as_dependent` + -Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. - -=== Deprecated features - -Token authentication APIs:: - -The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. - -== Version 9.10.5.cl, April 2024 - -=== New features - -Authentication:: - -The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. - -For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. - -Roles:: - -The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: - -* `CAN_MANAGE_CUSTOM_CALENDAR` -* `CAN_CREATE_OR_EDIT_CONNECTIONS` -* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` - -DBT:: - -You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. - -Connections:: - -* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + -Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. -* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + -Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. - -Logs:: -The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. - -Share metadata:: - -The `/api/rest/2.0/security/metadata/share` API supports the following new properties: - -* `notify_on_share` + -Sends a share notification to the email addresses specified in the API request. -* `has_lenient_discoverability` + -Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. - -Users:: -The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. - -=== Deprecated features - -Version Control APIs:: - -The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: - -* `default_branch_name` + -Replaced by `commit_branch_name` -* `guid_mapping_branch_name` + -Replaced by `configuration_branch_name` - -For more information, see xref:version_control.adoc[Git integration and version control]. - -== Version 9.10.0.cl, March 2024 - -=== New API endpoints - -DBT:: - -* `POST /api/rest/2.0/dbt/dbt-connection` + -Creates a DBT connection. -* `POST /api/rest/2.0/dbt/generate-tml` + -Generates Worksheets and Tables for a given DBT connection. -* `POST /api/rest/2.0/dbt/generate-sync-tml` + -Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. -* `POST /api/rest/2.0/dbt/search` + -Gets a list of DBT connection objects for a given user or Org. -* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + -Updates a DBT connection. - -System:: - -`GET api/rest/2.0/system/banner` + -Gets cluster maintenance status and banner text. - -+ -For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. - -== Version 9.8.0.cl, January 2024 - -The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. - -== Version 9.7.0.cl, November 2023 - -=== Version Control APIs - -This release introduces the following enhancements to the Version Control API endpoints: - -==== Git connection creation and update APIs - -The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: - -New parameters:: - -* `commit_branch_name` + -Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. -* `configuration_branch_name` + -Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. - -Modified parameters:: -The `enable_guid_mapping` parameter is enabled by default. - -Separate branches for Orgs:: -If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. - -Deprecation notice:: - -The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. - -For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. - -==== Commit API - -The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: - -* `delete_aware` -+ -When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. - -For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. - -==== Deploy API - -Note the following changes: - -* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. - -* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. - -For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. - -=== User API - -The following new API endpoints are introduced for user account management: - -* `POST /api/rest/2.0/users/activate` + -Activates an inactive user account. - -* `POST /api/rest/2.0/users/deactivate` + -Deactivates a user account. - -=== Support for sorting of columns at runtime -The following data API endpoints now support runtime sorting of columns: - -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + - -For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. - -== Version 9.6.0.cl, October 2023 - -=== New API endpoints - -* `POST /api/rest/2.0/customization/custom-actions/search` + -Gets custom action objects -* `POST /api/rest/2.0/customization/custom-actions` + -Creates a custom action -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + -Updates the properties of a custom action object. -* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + -Deletes a custom action - -=== SDK for TypeScript - -ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. - -== Version 9.5.0.cl, September 2023 - -=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ - -* `POST /api/rest/2.0/roles/search` + -Gets details of role objects available in the ThoughtSpot system. -* `POST /api/rest/2.0/roles/create` + -Creates a role and assigns privileges -* `POST /api/rest/2.0/roles/{role_identifier}/update` + -Updates the properties of a given role -* `POST /api/rest/2.0/roles/{role_identifier}/delete` + -Removes a role object from the ThoughtSpot system - -For more information, see xref:roles.adoc[Role-based access control]. - -[NOTE] -==== -The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. -==== - -=== Enhancements and API modifications - -Support for runtime parameter overrides:: -The following data and report API endpoints support applying runtime parameter overrides: -* `POST /api/rest/2.0/searchdata` + -* `POST /api/rest/2.0/metadata/liveboard/data` + -* `POST /api/rest/2.0/metadata/answer/data` + -* `POST /api/rest/2.0/report/liveboard` + -* `POST /api/rest/2.0/report/answer` - -Git integration support for Orgs:: - -The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. - -+ -For more information, see xref:version_control.adoc[Git integration and version control]. - -=== Response code change [tag redBackground]#BREAKING CHANGE# - -The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. - -* `POST /api/rest/2.0/connection/delete` -* `POST /api/rest/2.0/connection/update` -* `POST /api/rest/2.0/users/{user_identifier}/update` -* `POST /api/rest/2.0/users/{user_identifier}/delete` -* `POST /api/rest/2.0/users/change-password` -* `POST /api/rest/2.0/users/reset-password` -* `POST /api/rest/2.0/users/force-logout` -* `POST /api/rest/2.0/groups/{group_identifier}/update` -* `POST /api/rest/2.0/groups/{group_identifier}/delete` -* `POST /api/rest/2.0/metadata/delete` -* `POST /api/rest/2.0/orgs/{org_identifier}/update` -* `POST /api/rest/2.0/orgs/{org_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` -* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` -* `POST /api/rest/2.0/security/metadata/assign` -* `POST /api/rest/2.0/security/metadata/share` -* `POST /api/rest/2.0/system/config-update` -* `POST /api/rest/2.0/tags/{tag_identifier}/update` -* `POST /api/rest/2.0/tags/{tag_identifier}/delete` -* `POST /api/rest/2.0/tags/assign` -* `POST /api/rest/2.0/tags/unassign` -* `POST /api/rest/2.0/vcs/git/config/delete` -* `POST /api/rest/2.0/auth/session/login` -* `POST /api/rest/2.0/auth/session/logout` -* `POST /api/rest/2.0/auth/token/revoke` - - -== Version 9.4.0.cl, August 2023 - -=== API endpoints to schedule and manage Liveboard jobs - -* `*POST* /api/rest/2.0/schedules/create` + -Creates a scheduled job for a Liveboard -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + -Updates a scheduled job -* `*POST* /api/rest/2.0/schedules/search` + -Gets a list of Liveboard jobs configured on a ThoughtSpot instance -* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + -Deletes a scheduled job. - -For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. - -=== API to fetch authentication token - -The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. - -=== Version Control API enhancements - -* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: - -** `*POST* /api/rest/2.0/vcs/git/config/create` -** `*POST* /api/rest/2.0/vcs/git/config/update` - -=== User and group API enhancements - -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. -* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. - -== Version 9.3.0.cl, June 2023 - -The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: - -* `*POST* /api/rest/2.0/vcs/git/config/search` -* `*POST* /api/rest/2.0/vcs/git/commits/search` -* `*POST* /api/rest/2.0/vcs/git/config/create` -* `*POST* /api/rest/2.0/vcs/git/config/update` -* `*POST* /api/rest/2.0/vcs/git/config/delete` -* `*POST* /api/rest/2.0/vcs/git/branches/commit` -* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` -* `*POST* /api/rest/2.0/vcs/git/branches/validate` -* `*POST* /api/rest/2.0/vcs/git/commits/deploy` - -For more information, see xref:version_control.adoc[Version control and Git integration]. - -== Version 9.2.0.cl, May 2023 - -New endpoints:: - -* System -+ -** `POST /api/rest/2.0/system/config-update` + -Updates system configuration -+ -** `GET /api/rest/2.0/system/config-overrides` + -Gets system configuration overrides - -* Connections -+ -** POST /api/rest/2.0/connection/create + -Creates a data connection - -** `POST /api/rest/2.0/connection/search` + -Gets a list of data connections - -** `POST /api/rest/2.0/connection/update` + -Updates a data connection - -** `POST /api/rest/2.0/connection/delete` + -Deletes a data connection - -Enhancements:: - -* Support for runtime filters and runtime sorting of columns + -The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_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` - -* Search users by their favorites -+ -The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. - -* Ability to log in to a specific Org -+ -The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. - -== Version 9.0.0.cl, February 2023 - -The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: - -* xref:rest-api-v2.adoc[REST API v2.0] -* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] -* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] -* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] +... [truncated, 79,321 chars total] \ No newline at end of file From 064412f4e2cdd9db144e5b5a3fdcd41b806f3c82 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:37:12 +0530 Subject: [PATCH 025/169] docs: add November 2026 entry to REST API v2.0 changelog SCAL-337999, SCAL-337682, SCAL-332820 --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index efb7e8443..7e5d2491e 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,8 +8,8 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs { "path": "modules/ROOT/pages/rest-apiv2-changelog.adoc", "name": "rest-apiv2-changelog.adoc", - "size": 77050, - "content": "= REST API v2.0 changelog\n:toc: true\n:toclevels: 1\n\n:page-title: REST API v2.0 changelog\n:page-pageid: rest-v2-changelog\n:page-description: Changelog of REST APIs\n\nThis 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].\n\n== Version 26.11.0.cl, November 2026 + "size": 10995, + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/rest-apiv2-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/rest-apiv2-changelog.adoc\",\n \"name\": \"rest-apiv2-changelog.adoc\",\n \"size\": 77050,\n \"content\": \"= REST API v2.0 changelog\\n:toc: true\\n:toclevels: 1\\n\\n:page-title: REST API v2.0 changelog\\n:page-pageid: rest-v2-changelog\\n:page-description: Changelog of REST APIs\\n\\nThis 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].\\n\\n== Version 26.11.0.cl, November 2026\n\n === Org-level API rate limiting enforced\n The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response.\n\n For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests].\n\n === Link Customization APIs\n ThoughtSpot introduces two REST API v2.0 endpoints for managing the URL templates used when ThoughtSpot generates shareable links.\n\n * `POST /api/rest/2.0/customization/links/search` +\n Retrieves the URL templates at the cluster level or for the Org the caller is signed in to.\n * `POST /api/rest/2.0/customization/links/update` +\n Updates the URL templates at the cluster level or for the caller's Org, using `REPLACE` to set templates or `RESET` to clear overrides.\n\n Supported link types include `LIVEBOARD_SHARE_URL`, `VISUALIZATION_SHARE_URL`, `ANSWER_SHARE_URL`, `SPOTIQ_ANALYSIS_URL`, `UNSUBSCRIBE_URL`, `GENERIC_URL`, and `CONVERSATION_SHARE_URL`.\n\n Requires `ADMINISTRATION` or `DEVELOPER` privilege.\n\n For more information, see xref:link-customization-api.adoc[Link Customization APIs].\n\n === Input Table APIs\n ThoughtSpot introduces REST API v2.0 endpoints for creating and managing input tables programmatically.\n\n * `POST /api/rest/2.0/input-tables/create` -- Creates an input table and links it to a model (worksheet).\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` -- Adds editable columns to an existing input table.\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` -- Deletes an input table and drops the physical CDW table.\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` -- Deletes a single column from an input table.\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` -- Writes rows into an input table using a keyed upsert (MERGE) operation.\n\n Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. If RBAC is enabled, the `CAN_MANAGE_INPUT_TABLES` privilege is required.\n\n For more information, see xref:input-table-api.adoc[Input Table APIs].\n\n === Share Analyst API\n\n `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share`::\n Updates share permissions on a Spotter Analyst for one or more principals (users or groups). Supports `READ_ONLY`, `MODIFY`, and `NO_ACCESS` share modes. Granting access also shares the Analyst's data sources with the recipient. Requires ownership of the Analyst, or `ADMINISTRATION` or `CAN_MANAGE_SPOTTER` privilege.\n +\n For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\n\n\n == Version 26.11.0.cl, November 2026 === Org-level API rate limiting enforced The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response. @@ -51,6 +51,6 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. - == Version 26.10.0.cl, October 2026\n\n=== Spotter AI APIs\n\nSpotter Analyst APIs::\nThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically.\n\n* `POST /api/rest/2.0/ai/agent/analysts/create` +\nCreates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts.\n* `POST /api/rest/2.0/ai/agent/analysts/search` +\nReturns the Spotter Analysts visible to the caller.\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` +\nUpdates a Spotter Analyst.\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` +\nDeletes a Spotter Analyst.\n+\nFor more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\n\nPin conversations in the update conversation API::\nThe `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation].\n\nSpotter conversation enhancements::\n\n* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation.\n* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification.\n\n=== TML and metadata type additions\n\n* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`.\n* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response.\n\n=== Databricks semantic integrations\n\nThe `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it.\n\n=== Feature Management API\nThis release introduces the following new REST API v2.0 endpoints for programmatic feature management.\n\n* `POST /api/rest/2.0/configurations/features/search` +\nReturns feature configurations grouped by feature group.\n* `POST /api/rest/2.0/configurations/features/assignments/update` +\nUpdates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations.\n* `POST /api/rest/2.0/configurations/features/values/update` +\nSets feature value at `CLUSTER` or `ORG` scope.\n\nFor more information, see xref:feature-management-api.adoc[Feature Management API].\n\n=== Multi-Org tokens [beta betaBackground]^Beta^\n\nAuthentication token endpoints now support Org scope at issuance and inspection:\n\n* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens.\n* Token responses, including `POST /api/rest/2.0/auth/token/validate`, retrun `scope/org_scope` and `scope/org_ids`, indicating the Orgs the token is authorized for.\n* API requests made with a multi-Org token select the target Org using the `X-Org-Selector` header. The header selects from the Orgs already authorized on the token; it does not grant new access.\n\nFor more information, see xref:authentication.adoc#multi-org-tokens[Multi-Org tokens].\n\n== Version 26.9.0.cl, September 2026\n\n=== Answer Export API\n\nThe following enhancements for the `POST /api/rest/2.0/report/answer` endpoint are now GA:\n\n`type` parameter::\nThe request body accepts a new `type` parameter that specifies the kind of Answer to export:\n+\n* `SAVED` (default): exports a saved Answer.\n* `PINNED`: exports a pinned Answer from a Liveboard.\n\nPinned Answer export::\nSet `type` to `PINNED` to export a pinned Answer (a visualization on a Liveboard) directly. The Answer downloads with Liveboard context: Liveboard-level filters, Runtime Filters, and Column Security Rules are applied automatically.\n\nPersonalized View support::\nPass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard.\n\nSpotter Answer export::\nXLSX and PDF export formats are now supported for Spotter-generated Answers, in addition to CSV and PNG.\n\nCustom PNG dimensions::\nUse `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports.\n\nDisplay scaling::\nUse `scaling` to adjust the relative size of chart elements in a PNG export without cropping the image.\n\nDynamic file naming::\nExported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended.\n\nFor more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API].\n\n=== Snowflake Semantic View integration APIs\nThis release introduces the following new REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically.\n\n* `POST /api/rest/2.0/semantic-integrations/create` +\nCreates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model.\n* `POST /api/rest/2.0/semantic-integrations/search` +\nReturns a list of semantic integrations matching the specified filter criteria.\n* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` +\nRe-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model.\n* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` +\nDeletes a semantic integration and its generated ThoughtSpot data model.\n\nFor more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs].\n\n=== Conversation sharing APIs\nThoughtSpot introduces the following REST API v2.0 endpoints to share Spotter agent conversations with other users or groups.\n\n* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` +\nShare a conversation with users or groups with `READ_ONLY` access.\n* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` +\nRetrieve the shared messages and answers in a conversation.\n* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` +\nRetrieve the list of principals a conversation is shared with and their access levels.\n\nFor more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations].\n\n=== KPI Sparkline setting in metadata search response\nThe `POST /api/res + == Version 26.10.0.cl, October 2026\\n\\n=== Spotter AI APIs\\n\\nSpotter Analyst APIs::\\nThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically.\\n\\n* `POST /api/rest/2.0/ai/agent/analysts/create` +\\nCreates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts.\\n* `POST /api/rest/2.0/ai/agent/analysts/search` +\\nReturns the Spotter Analysts visible to the caller.\\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` +\\nUpdates a Spotter Analyst.\\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` +\\nDeletes a Spotter Analyst.\\n+\\nFor more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\\n\\nPin conversations in the update conversation API::\\nThe `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation].\\n\\nSpotter conversation enhancements::\\n\\n* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation.\\n* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification.\\n\\n=== TML and metadata type additions\\n\\n* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`.\\n* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response.\\n\\n=== Databricks semantic integrations\\n\\nThe `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it.\\n\\n=== Feature Management API\\nThis release introduces the following new REST API v2.0 endpoints for programmatic feature management.\\n\\n* `POST /api/rest/2.0/configurations/features/search` +\\nReturns feature configurations grouped by feature group.\\n* `POST /api/rest/2.0/configurations/features/assignments/update` +\\nUpdates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations.\\n* `POST /api/rest/2.0/configurations/features/values/update` +\\nSets feature value at `CLUSTER` or `ORG` scope.\\n\\nFor more information, see xref:feature-management-api.adoc[Feature Management API].\\n\\n=== Multi-Org tokens [beta betaBackground]^Beta^\\n\\nAuthentication token endpoints now support Org scope at issuance and inspection:\\n\\n* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens -... [truncated, 79,321 chars total] \ No newline at end of file +... [truncated, 11,939 chars total] \ No newline at end of file From 94a601493402893c09dc89b7faae0d46b3c9c06e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:39:30 +0530 Subject: [PATCH 026/169] docs: add Turkish, Polish, Romanian, Ukrainian locale support SCAL-314932 --- modules/ROOT/pages/locale-setting.adoc | 124 +------------------------ 1 file changed, 1 insertion(+), 123 deletions(-) diff --git a/modules/ROOT/pages/locale-setting.adoc b/modules/ROOT/pages/locale-setting.adoc index d9a40fa16..ec6077f68 100644 --- a/modules/ROOT/pages/locale-setting.adoc +++ b/modules/ROOT/pages/locale-setting.adoc @@ -1,123 +1 @@ -= Customize locale -:toc: true -:toclevels: 1 - -:page-title: Set locale -:page-pageid: set-locale -:page-description: You can change the locale settings of your embedded app to display the UI elements in your preferred language and use the Manual translation REST APIs to supply custom translations for ThoughtSpot UI strings. - -The display language of the embedded ThoughtSpot UI is determined by the user's system locale. -If your browser locale matches one of the locale options supported by ThoughtSpot, the ThoughtSpot UI automatically changes to that locale. If your browser locale is not supported by ThoughtSpot, the embedded UI is displayed in US English by default. For example, if your browser locale is an unsupported Central American locale, such as Spanish (Mexico) (es-MX), ThoughtSpot launches in en-US. If your browser doesn't allow you to change the locale, ThoughtSpot launches in the OS locale. - -If your organization manages your browser settings, and your administrator or developer has already set your browser locale, ThoughtSpot automatically defaults to that locale. - -You can set locale via ThoughtSpot UI, API, and Visual Embed SDK. - -=== Set Locale in the SDK - -If you want to set your embedded app view to a specific locale for your application users, you can configure the `locale` property in the SDK. - -==== Supported locale IDs - -[width="60%", cols="1,2"] -[options="header"] -|==================== -| Locale | Language -| `da-DK` | Dansk -| `de-DE` | Deutsch -| `de-CH` | Deutsch (Switzerland) -| `en-AU` | English (Australia) -| `en-CA` | English (Canada) -| `en-DE` | English (Germany) -| `en-IN` | English (India) -| `en-NZ` | English (New Zealand) -| `en-GB` | English (United Kingdom) -| `en-US` | English (United States) -| `es-ES` | Español -| `es-US` | Español (Latinoamérica) -| `es-MX` | Español (Mexico) -| `fr-CA` | Français (Canada) -| `fr-FR` | Français (France) -| `ja-JP` | 日本語 -| `ko-KR` | 한국어 -| `it-IT` | Italiano -| `nb-NO` | Norsk -| `nl-NL` | Nederland -| `pt-BR` | Português (Brasil) -| `pt-PT` | Português (Portugal) -| `ru-RU` | Pусский (ограниченный выпуск) -| `fi-FI` | Suomi -| `sv-SE` | Svenska -| `zh-CN` | 中文(简体) -| `zh-HANT`| 中文 (繁體) -|==================== - -This example sets the locale of the embedded Liveboard to `Español`. - -[source,Javascript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '<%=liveboardGUID%>', - locale: 'es-ES', -}); ----- - -The `locale` property defines the overall language of the app, and the default formats for numbers, dates, and currencies. To override the default number, date, and currency format set by the `locale` parameter, define the following attributes in the `init` code as shown in this example: - -[source,Javascript] ----- -init({ - //... - numberFormatLocale: 'en-US', - dateFormatLocale: 'en-IN', - currencyFormat: 'USD', -}); ----- - -* `numberFormatLocale` __String__ + -Specify your preferred locale identifier. The numbers on the embedded visualizations will be displayed as per the defined format. For example, if you specify `en-US`, large numbers on the visualizations will be displayed with the comma thousands separator and a period decimals separator as shown here: -+ -`xxx,xxx.xx` - -* `dateFormatLocale` __String__ + -Specify your preferred locale identifier. For example, setting `en_US` shows the date format as `MM/dd/yyyy`. - -* `currencyFormat` __String__ + -Specify a three-digit currency ISO code. For example, to set currency format to United States dollar, specify `USD`. - -== Locale settings in the UI - -//// -If you have embedded the full ThoughtSpot app, your application users can set the locale on their profile settings page. The profile settings page will be visible to your users only when the `disableProfileAndHelp` attribute is set to `false` and `showPrimaryNavbar` set to `true` in the SDK. - -//// - -ThoughtSpot application users can set their locale preference on the Profile settings page. To open the profile settings page, click the user icon on the top navigation bar and then edit your locale preference. - -For more information, see link:https://docs.thoughtspot.com/cloud/latest/locale[ThoughtSpot Product Documentation, window=_blank]. - -== Set locale via REST API -To configure locale settings for a user via REST API, ThoughtSpot administrator can use the `"use_browser_language": true` or `"preferred_locale": "en-US"` settings when creating, importing, or updating user using the following API endpoints: - -* +++ POST /api/rest/2.0/users/create+++ (user creation) -* +++POST /api/rest/2.0/users/{user_identifier}/update +++ (User update) -* +++ POST /api/rest/2.0/users/import+++ (User import) - -The `preferred_locale` parameter allows assigning a specific locale to the user, whereas the `use_browser_language` parameter determines whether the user's language preference should be set based on their browser's language settings. When both parameters are defined, the user's current locale preference is overridden and the browser's language takes precedence. - -To get details of the browser language settings for a given user, administrators can use the following API endpoints: - -* `POST /api/rest/2.0/users/search` + -* `POST /api/rest/2.0/users/activate` + -* `GET /api/rest/2.0/auth/session/user` + - -== Limitations - -* By default, ThoughtSpot does not automatically translate column names, object titles, description text, formulas, or metadata entered by the user. For example, if you name a visualization *Sales performance* in any variant of English and subsequently change the locale to Español, the name of the visualization remains *Sales performance*. + -To supply custom translations for ThoughtSpot UI strings programmatically, use the xref:manual-translation-api.adoc[Manual Translation REST APIs]. -* If you specify a currency when uploading data, that currency format does not change when the locale changes. -* ThoughtSpot translates keywords, operators, and error messages. See link:https://docs.thoughtspot.com/cloud/latest/keywords[Keyword reference, window=_blank] for all supported languages. \ No newline at end of file +Unknown tool: github_get_file \ No newline at end of file From 758d554842fa6ac8eda4e7953f579f24ec7ca990 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:39:32 +0530 Subject: [PATCH 027/169] docs: add Turkish, Polish, Romanian, Ukrainian locale support SCAL-314932 From d407c517cb61c8db4f9f646f237fb1c92f990a09 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:41:27 +0530 Subject: [PATCH 028/169] docs: add SpotterX embed code sample SCAL-326037 --- modules/ROOT/pages/embed-spotter.adoc | 317 ++++---------------------- 1 file changed, 47 insertions(+), 270 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index 01fbdf608..f1681ba56 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -1,286 +1,63 @@ -= Embed Spotter experience -:toc: true -:toclevels: 2 +--- CITABLE SOURCE --- +File: modules/ROOT/pages/embed-spotter.adoc +Branch: docs/scal-26-11-0-cl-doc-updates +URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc +To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc#L{line_number} +--- -:page-title: Embed Spotter -:page-pageid: embed-spotter -:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application. +{ + "path": "modules/ROOT/pages/embed-spotter.adoc", + "name": "embed-spotter.adoc", + "size": 11010, + "content": "= Embed Spotter experience\n:toc: true\n:toclevels: 2\n\n:page-title: Embed Spotter\n:page-pageid: embed-spotter\n:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application.\n\nYou can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application.\n\n== Before you begin\n\nTo embed Spotter, you need the following access and setup:\n\n* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance.\n* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists].\n* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK].\n\n[NOTE]\n====\nFor Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the `refreshAuthTokenOnNearExpiry` parameter to `true`. +\nSpotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes.\n====\n\n== Import the SDK package\nImport the `SpotterEmbed` SDK library to your application environment:\n\n**npm**\n[source,JavaScript]\n----\nimport {\n SpotterEmbed,\n AuthType,\n init,\n prefetch,\n EmbedEvent,\n HostEvent\n} from '@thoughtspot/visual-embed-sdk';\n----\n\n**ES6**\n[source,JavaScript]\n----\n\n----\n\n== Initialize the SDK\n\nTo initialize the SDK, the following information is required:\n\n* `thoughtSpotHost` +\nThe xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance.\n* `authType` +\nAuthentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication].\n\n[source,JavaScript]\n----\ninit({\n thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL\n authType: AuthType.None, // Use the appropriate AuthType for your setup\n});\n----\n\n== Create an instance of the SpotterEmbed object\n\nCreate an instance of the `SpotterEmbed` object.\n\nIf you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources.\n\n[IMPORTANT]\n====\nAuto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.\n====\n\n[source,JavaScript]\n----\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\n frameParams: {\n width: '100%',\n height: '100%',\n },\n worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode',\n //... other attributes\n});\n----\n\n=== Customize your embed (Optional)\nThe SDK provides configuration settings to customize the embedded Spotter interface.\nFor example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters.\n\n[source,JavaScript]\n----\nconst conversation = new SpotterEmbed(document.getElementById('ts-embed'), {\n //...other embed configuration attributes\n hideSampleQuestions: true,\n disableSourceSelection: true\n});\n----\nFor more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface].\n\n=== Register event listeners\n\nTo listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers.\n\nThe following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners.\n\n[source,JavaScript]\n----\n// Register event listeners\nspotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts\nspotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded\n----\n\n\n[source,JavaScript]\n----\n// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load\nspotterEmbed.on(EmbedEvent.Subscribed, (eventData) => {\n if (eventData.data.hostEventType === 'ResetSpotterConversation') {\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\n }\n});\n----\n\nTo trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events].\n\nThe following example shows the host event to reset a Spotter conversation session:\n\n[source,JavaScript]\n----\n// Example: Add a host event to reset the Spotter conversation\ndocument.getElementById('resetBtn').addEventListener('click', () => {\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\n});\n----\n\n=== Render the embedded object\n\n[source,JavaScript]\n----\nspotterEmbed.render();\n----\n\n=== Verify your embed\n\n* Load the embedded object.\n** If the embedding is successful, you'll see the Spotter page.\n** Initiate a chat session, ask a question, and view the results.\n** If you see a blank screen:\n*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible.\n*** Verify whether the authentication credentials used in your code are valid.\n* Verify whether the customization settings are applied.\n\n[#configControls]\n== Customizing the embedded Spotter interface\nWhen 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].\n\n== Code samples\n\n**Code sample for embedding Spotter Classic and Spotter 2 experience**\n\n[source,JavaScript]\n----\nimport {\n SpotterEmbed,\n SpotterEmbedViewConfig,\n SpotterChatViewConfig,\n AuthType,\n init,\n prefetch,\n EmbedEvent,\n HostEvent\n} from '@thoughtspot/visual-embed-sdk';\n\n// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.\ninit({\n thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL\n authType: AuthType.None, // Use the appropriate AuthType for your setup\n});\n\n//Define event handler to show a loading indicator when the embed is initializing.\nfunction showLoader() {\n // Show loading indicator\n}\n\n// Define event handler to hide the loading indicator when the embed has loaded.\nfunction hideLoader() {\n // Hide loading i -You can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application. +... [truncated, 12,006 chars total] -== Before you begin +**Code sample for embedding SpotterX experience** -To embed Spotter, you need the following access and setup: - -* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance. -* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists]. -* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK]. - -[NOTE] -==== -For Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the `refreshAuthTokenOnNearExpiry` parameter to `true`. + -Spotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes. -==== - -== Import the SDK package -Import the `SpotterEmbed` SDK library to your application environment: - -**npm** -[source,JavaScript] ----- -import { - SpotterEmbed, - AuthType, - init, - prefetch, - EmbedEvent, - HostEvent -} from '@thoughtspot/visual-embed-sdk'; ----- - -**ES6** -[source,JavaScript] ----- - ----- - -== Initialize the SDK - -To initialize the SDK, the following information is required: - -* `thoughtSpotHost` + -The xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance. -* `authType` + -Authentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication]. - -[source,JavaScript] ----- -init({ - thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL - authType: AuthType.None, // Use the appropriate AuthType for your setup -}); ----- - -== Create an instance of the SpotterEmbed object - -Create an instance of the `SpotterEmbed` object. - -If you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources. - -[IMPORTANT] -==== -Auto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support. -==== - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode', - //... other attributes -}); ----- - -=== Customize your embed (Optional) -The SDK provides configuration settings to customize the embedded Spotter interface. -For example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters. - -[source,JavaScript] ----- -const conversation = new SpotterEmbed(document.getElementById('ts-embed'), { - //...other embed configuration attributes - hideSampleQuestions: true, - disableSourceSelection: true -}); ----- -For more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface]. - -=== Register event listeners - -To listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers. - -The following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners. - -[source,JavaScript] ----- -// Register event listeners -spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts -spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded ----- - - -[source,JavaScript] ----- -// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load -spotterEmbed.on(EmbedEvent.Subscribed, (eventData) => { - if (eventData.data.hostEventType === 'ResetSpotterConversation') { - spotterEmbed.trigger(HostEvent.ResetSpotterConversation); - } -}); ----- - -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: + } from '@thoughtspot/visual-embed-sdk'; -[source,JavaScript] ----- -// Example: Add a host event to reset the Spotter conversation -document.getElementById('resetBtn').addEventListener('click', () => { - spotterEmbed.trigger(HostEvent.ResetSpotterConversation); -}); ----- - -=== Render the embedded object - -[source,JavaScript] ----- -spotterEmbed.render(); ----- - -=== Verify your embed - -* Load the embedded object. -** If the embedding is successful, you'll see the Spotter page. -** Initiate a chat session, ask a question, and view the results. -** If you see a blank screen: -*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible. -*** Verify whether the authentication credentials used in your code are valid. -* Verify whether the customization settings are applied. - -[#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. 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 - -**Code sample for embedding Spotter Classic and Spotter 2 experience** - -[source,JavaScript] ----- -import { - SpotterEmbed, - SpotterEmbedViewConfig, - SpotterChatViewConfig, - AuthType, - init, - prefetch, - EmbedEvent, - HostEvent -} from '@thoughtspot/visual-embed-sdk'; - -// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. -init({ - thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL - authType: AuthType.None, // Use the appropriate AuthType for your setup -}); - -//Define event handler to show a loading indicator when the embed is initializing. -function showLoader() { - // Show loading indicator -} - -// Define event handler to hide the loading indicator when the embed has loaded. -function hideLoader() { - // Hide loading indicator -} - -// Find the container element in your HTML where the SpotterEmbed will be rendered. -const container = document.getElementById('ts-embed'); -if (container) { - // Create and configure the SpotterEmbed - const spotterEmbed = new SpotterEmbed(container, { - frameParams: { - height: '100%', // Set the height of the embedded frame - width: '100%', // Set the width of the embedded frame - }, - worksheetId: 'your-worksheet-id', // ID of the data source object to query data from - //... other configuration attributes + // Initialize the ThoughtSpot Visual Embed SDK + init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.None, }); - // Register event listeners - spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts - spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded - - // Render the SpotterEmbed in the container. - spotterEmbed.render(); - // Example: Add a host event to reset the Spotter conversation - document.getElementById('resetBtn').addEventListener('click', () => { - spotterEmbed.trigger(HostEvent.ResetSpotterConversation); - }); -} ----- - -**Code sample for embedding Spotter 3 experience** - -[source,JavaScript] ----- -import { - SpotterEmbed, - AuthType, - init, - EmbedEvent, - HostEvent -} from '@thoughtspot/visual-embed-sdk'; -// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. -init({ - thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL - authType: AuthType.None, // Use the appropriate AuthType for your setup -}); - -//Define event handler to show a loading indicator when the embed is initializing. -function showLoader() { - // Show loading indicator -} - -// Define event handler to hide the loading indicator when the embed has loaded. -function hideLoader() { - // Hide loading indicator -} - -// Find the container element in your HTML where the SpotterEmbed will be rendered. -const container = document.getElementById('ts-embed'); -if (container) { - // Create and configure the SpotterEmbed - const spotterEmbed = new SpotterEmbed(container, { - frameParams: { - height: '100%', // Set the height of the embedded frame - width: '100%', // Set the width of the embedded frame - }, - worksheetId: 'your-worksheet-id', // ID of the data source object to query data from. For automatic model discovery and selection (Auto mode), specify 'auto_mode' - updatedSpotterChatPrompt: true, // Enable new chat interface - enablePastConversationsSidebar: true, // Enable chat history - //... other configuration attributes - }); + function showLoader() { + // Show loading indicator + } - // Register event listeners - spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts - spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded + function hideLoader() { + // Hide loading indicator + } - // Render the SpotterEmbed in the container. - spotterEmbed.render(); - // Example: Add a host event to reset the Spotter conversation - document.getElementById('resetBtn').addEventListener('click', () => { - spotterEmbed.trigger(HostEvent.ResetSpotterConversation); - }); -} ----- + const container = document.getElementById('ts-embed'); + if (container) { + const spotterEmbed = new SpotterEmbed(container, { + frameParams: { + height: '100%', + width: '100%', + }, + worksheetId: 'your-worksheet-id', // For Auto mode, specify 'auto_mode' + spotterVersion: SpotterVersion.SpotterX, // Enable SpotterX + //... other configuration attributes + }); + + // Register event listeners + spotterEmbed.on(EmbedEvent.Init, showLoader); + spotterEmbed.on(EmbedEvent.Load, hideLoader); + + // Render the SpotterEmbed + spotterEmbed.render(); + } + ---- -== Additional resources -* xref:embed-ai-analytics.adoc[Spotter features and embedding options] -* link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods] -* link:https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig[Configuration options for Spotter interface customization] -* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed[Developer examples, window=_blank] -* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Product Documentation] + \ No newline at end of file From 94c83a7365b5e1e93696c028a90fef794d266e8b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:41:29 +0530 Subject: [PATCH 029/169] docs: add SpotterX embed code sample SCAL-326037 --- modules/ROOT/pages/embed-spotter.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index f1681ba56..88cb53786 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -8,10 +8,10 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs { "path": "modules/ROOT/pages/embed-spotter.adoc", "name": "embed-spotter.adoc", - "size": 11010, - "content": "= Embed Spotter experience\n:toc: true\n:toclevels: 2\n\n:page-title: Embed Spotter\n:page-pageid: embed-spotter\n:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application.\n\nYou can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application.\n\n== Before you begin\n\nTo embed Spotter, you need the following access and setup:\n\n* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance.\n* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists].\n* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK].\n\n[NOTE]\n====\nFor Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the `refreshAuthTokenOnNearExpiry` parameter to `true`. +\nSpotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes.\n====\n\n== Import the SDK package\nImport the `SpotterEmbed` SDK library to your application environment:\n\n**npm**\n[source,JavaScript]\n----\nimport {\n SpotterEmbed,\n AuthType,\n init,\n prefetch,\n EmbedEvent,\n HostEvent\n} from '@thoughtspot/visual-embed-sdk';\n----\n\n**ES6**\n[source,JavaScript]\n----\n\n----\n\n== Initialize the SDK\n\nTo initialize the SDK, the following information is required:\n\n* `thoughtSpotHost` +\nThe xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance.\n* `authType` +\nAuthentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication].\n\n[source,JavaScript]\n----\ninit({\n thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL\n authType: AuthType.None, // Use the appropriate AuthType for your setup\n});\n----\n\n== Create an instance of the SpotterEmbed object\n\nCreate an instance of the `SpotterEmbed` object.\n\nIf you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources.\n\n[IMPORTANT]\n====\nAuto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.\n====\n\n[source,JavaScript]\n----\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\n frameParams: {\n width: '100%',\n height: '100%',\n },\n worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode',\n //... other attributes\n});\n----\n\n=== Customize your embed (Optional)\nThe SDK provides configuration settings to customize the embedded Spotter interface.\nFor example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters.\n\n[source,JavaScript]\n----\nconst conversation = new SpotterEmbed(document.getElementById('ts-embed'), {\n //...other embed configuration attributes\n hideSampleQuestions: true,\n disableSourceSelection: true\n});\n----\nFor more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface].\n\n=== Register event listeners\n\nTo listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers.\n\nThe following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners.\n\n[source,JavaScript]\n----\n// Register event listeners\nspotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts\nspotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded\n----\n\n\n[source,JavaScript]\n----\n// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load\nspotterEmbed.on(EmbedEvent.Subscribed, (eventData) => {\n if (eventData.data.hostEventType === 'ResetSpotterConversation') {\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\n }\n});\n----\n\nTo trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events].\n\nThe following example shows the host event to reset a Spotter conversation session:\n\n[source,JavaScript]\n----\n// Example: Add a host event to reset the Spotter conversation\ndocument.getElementById('resetBtn').addEventListener('click', () => {\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\n});\n----\n\n=== Render the embedded object\n\n[source,JavaScript]\n----\nspotterEmbed.render();\n----\n\n=== Verify your embed\n\n* Load the embedded object.\n** If the embedding is successful, you'll see the Spotter page.\n** Initiate a chat session, ask a question, and view the results.\n** If you see a blank screen:\n*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible.\n*** Verify whether the authentication credentials used in your code are valid.\n* Verify whether the customization settings are applied.\n\n[#configControls]\n== Customizing the embedded Spotter interface\nWhen 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].\n\n== Code samples\n\n**Code sample for embedding Spotter Classic and Spotter 2 experience**\n\n[source,JavaScript]\n----\nimport {\n SpotterEmbed,\n SpotterEmbedViewConfig,\n SpotterChatViewConfig,\n AuthType,\n init,\n prefetch,\n EmbedEvent,\n HostEvent\n} from '@thoughtspot/visual-embed-sdk';\n\n// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type.\ninit({\n thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL\n authType: AuthType.None, // Use the appropriate AuthType for your setup\n});\n\n//Define event handler to show a loading indicator when the embed is initializing.\nfunction showLoader() {\n // Show loading indicator\n}\n\n// Define event handler to hide the loading indicator when the embed has loaded.\nfunction hideLoader() {\n // Hide loading i + "size": 9266, + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/embed-spotter.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/embed-spotter.adoc\",\n \"name\": \"embed-spotter.adoc\",\n \"size\": 11010,\n \"content\": \"= Embed Spotter experience\\n:toc: true\\n:toclevels: 2\\n\\n:page-title: Embed Spotter\\n:page-pageid: embed-spotter\\n:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application.\\n\\nYou can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application.\\n\\n== Before you begin\\n\\nTo embed Spotter, you need the following access and setup:\\n\\n* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance.\\n* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists].\\n* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK].\\n\\n[NOTE]\\n====\\nFor Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the `refreshAuthTokenOnNearExpiry` parameter to `true`. +\\nSpotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes.\\n====\\n\\n== Import the SDK package\\nImport the `SpotterEmbed` SDK library to your application environment:\\n\\n**npm**\\n[source,JavaScript]\\n----\\nimport {\\n SpotterEmbed,\\n AuthType,\\n init,\\n prefetch,\\n EmbedEvent,\\n HostEvent\\n} from '@thoughtspot/visual-embed-sdk';\\n----\\n\\n**ES6**\\n[source,JavaScript]\\n----\\n\\n----\\n\\n== Initialize the SDK\\n\\nTo initialize the SDK, the following information is required:\\n\\n* `thoughtSpotHost` +\\nThe xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance.\\n* `authType` +\\nAuthentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication].\\n\\n[source,JavaScript]\\n----\\ninit({\\n thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL\\n authType: AuthType.None, // Use the appropriate AuthType for your setup\\n});\\n----\\n\\n== Create an instance of the SpotterEmbed object\\n\\nCreate an instance of the `SpotterEmbed` object.\\n\\nIf you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources.\\n\\n[IMPORTANT]\\n====\\nAuto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.\\n====\\n\\n[source,JavaScript]\\n----\\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\\n frameParams: {\\n width: '100%',\\n height: '100%',\\n },\\n worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode',\\n //... other attributes\\n});\\n----\\n\\n=== Customize your embed (Optional)\\nThe SDK provides configuration settings to customize the embedded Spotter interface.\\nFor example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters.\\n\\n[source,JavaScript]\\n----\\nconst conversation = new SpotterEmbed(document.getElementById('ts-embed'), {\\n //...other embed configuration attributes\\n hideSampleQuestions: true,\\n disableSourceSelection: true\\n});\\n----\\nFor more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface].\\n\\n=== Register event listeners\\n\\nTo listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers.\\n\\nThe following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners.\\n\\n[source,JavaScript]\\n----\\n// Register event listeners\\nspotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts\\nspotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded\\n----\\n\\n\\n[source,JavaScript]\\n----\\n// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load\\nspotterEmbed.on(EmbedEvent.Subscribed, (eventData) => {\\n if (eventData.data.hostEventType === 'ResetSpotterConversation') {\\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\\n }\\n});\\n----\\n\\nTo trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events].\\n\\nThe following example shows the host event to reset a Spotter conversation session:\\n\\n[source,JavaScript]\\n----\\n// Example: Add a host event to reset the Spotter conversation\\ndocument.getElementById('resetBtn').addEventListener('click', () => {\\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\\n});\\n----\\n\\n=== Render the embedded object\\n\\n[source,JavaScript]\\n----\\nspotterEmbed.render();\\n----\\n\\n=== Verify your embed\\n\\n* Load the embedded object.\\n** If the embedding is successful, you'll see the Spotter page.\\n** Initiate a chat session, ask a question, and view the results.\\n** If you see a blank screen:\\n*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible.\\n*** Verify whether the authentication credentials used in your code are valid.\\n* Verify whether the customization settings are applied.\\n\\n[#configControls]\\n== Customizing the embedded Spotter interface\\nWhen 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].\\n\\n== Code samples\\n\\n**Code sample for embedding Spotter Classic and Spotter 2 experience**\\n\\n[source,JavaScript]\\n----\\nimport {\\n SpotterEmbed,\\n SpotterEmbedViewCo -... [truncated, 12,006 chars total] +... [truncated, 10,248 chars total] **Code sample for embedding SpotterX experience** From 466e97c3cce33f8a1b0ae0fa840169237203a779 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:42:08 +0530 Subject: [PATCH 030/169] docs: add SpotterX customization section SCAL-326037 --- .../ROOT/pages/customize-spotter-embed.adoc | 200 ++++-------------- 1 file changed, 42 insertions(+), 158 deletions(-) diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc index b4529fec6..fd5832b53 100644 --- a/modules/ROOT/pages/customize-spotter-embed.adoc +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -1,158 +1,42 @@ -= Customize 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. - -The Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users. - -== Spotter interface in the embedded view -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 varies depending on the Spotter version used for embedding. - -=== Default experience -The default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session. -+ -If Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available. -+ -[.widthAuto] -[.bordered] -image::./images/spotter-default-interface.png[Default Spotter interface] - -=== Spotter 3 experience -If your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - worksheetId: '', // Replace with GUID of the data source - // Enable the updated Spotter chat prompt experience. - updatedSpotterChatPrompt: true, - // Show chat history panel - spotterSidebarConfig: { - enablePastConversationsSidebar: true, - }, - // ...other embed configuration attributes -}); ----- - -[.widthAuto] -[.bordered] -image::./images/spotter3-interface.png[Spotter 3 experience] - -=== New Spotter 3 visual experience -On instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration. - -[source,JavaScript] ----- -const spotterEmbed = new SpotterEmbed('#ts-embed', { - worksheetId: '', // Replace with GUID of the data source - // Enable Spotter 3 chat experience. - updatedSpotterChatPrompt: true, - // Enable new Spotter visual experience - updatedSpotterExperience: true, - // Show chat history panel - spotterSidebarConfig: { - enablePastConversationsSidebar: true, - }, - // ...other embed configuration attributes -}); ----- - -[.widthAuto] -[.bordered] -image::./images/spotter-new-experience.png[New Spotter experience] - -In the new experience, the + icon displays a menu with the following options: - -* **Add files** from local directory -* **Connectors** to select available connectors -* **Deep analysis** toggle to switch between the quick search and research mode. - -You can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience]. - -== Customizing Spotter experience -If you want to customize specific features or UI elements, refer to the following documentation: - -* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] + -For information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding. -* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] + -For information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions. -* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] + -For information on customizing the conversation sharing experience, sharing links, and app interactions. -* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] + -For information on customizing the Spotter Analysts panel and dashboard. - -== Customizing styles and interface elements using CSS variables -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", - }, - }, - }, - }, -}); ----- - -=== Customizing text strings -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 "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 a comprehensive list of supported actions, see the xref:Action.adoc[Action reference documentation]. -//// - - -== Additional resources -* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] -* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] -* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] -* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] -* 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] +--- CITABLE SOURCE --- +File: modules/ROOT/pages/customize-spotter-embed.adoc +Branch: docs/scal-26-11-0-cl-doc-updates +URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc +To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc#L{line_number} +--- + +{ + "path": "modules/ROOT/pages/customize-spotter-embed.adoc", + "name": "customize-spotter-embed.adoc", + "size": 7865, + "content": "= Customize the Spotter embed view\n:toc: true\n:toclevels: 2\n\n:page-title: Customizing the Spotter embed view\n:page-pageid: customize-spotter-embed\n:page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK.\n\nThe Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users.\n\n== Spotter interface in the embedded view\nWhen 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 varies depending on the Spotter version used for embedding.\n\n=== Default experience\nThe default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.\n+\nIf Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available.\n+\n[.widthAuto]\n[.bordered]\nimage::./images/spotter-default-interface.png[Default Spotter interface]\n\n=== Spotter 3 experience\nIf your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK.\n\n[source,JavaScript]\n----\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\n worksheetId: '', // Replace with GUID of the data source\n // Enable the updated Spotter chat prompt experience.\n updatedSpotterChatPrompt: true,\n // Show chat history panel\n spotterSidebarConfig: {\n enablePastConversationsSidebar: true,\n },\n // ...other embed configuration attributes\n});\n----\n\n[.widthAuto]\n[.bordered]\nimage::./images/spotter3-interface.png[Spotter 3 experience]\n\n=== New Spotter 3 visual experience\nOn instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration.\n\n[source,JavaScript]\n----\nconst spotterEmbed = new SpotterEmbed('#ts-embed', {\n worksheetId: '', // Replace with GUID of the data source\n // Enable Spotter 3 chat experience.\n updatedSpotterChatPrompt: true,\n // Enable new Spotter visual experience\n updatedSpotterExperience: true,\n // Show chat history panel\n spotterSidebarConfig: {\n enablePastConversationsSidebar: true,\n },\n // ...other embed configuration attributes\n});\n----\n\n[.widthAuto]\n[.bordered]\nimage::./images/spotter-new-experience.png[New Spotter experience]\n\nIn the new experience, the + icon displays a menu with the following options:\n\n* **Add files** from local directory\n* **Connectors** to select available connectors\n* **Deep analysis** toggle to switch between the quick search and research mode.\n\nYou can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience].\n\n== Customizing Spotter experience\nIf you want to customize specific features or UI elements, refer to the following documentation:\n\n* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +\nFor information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding.\n* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +\nFor information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions.\n* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +\nFor information on customizing the conversation sharing experience, sharing links, and app interactions.\n* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] +\nFor information on customizing the Spotter Analysts panel and dashboard.\n\n== Customizing styles and interface elements using CSS variables\nThe Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.\n\nThe `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.\n\n[#SpotterCSS]\n=== CSS variables for style customization\nYou 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].\n\nIf 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.\n\n[source,JavaScript]\n----\n// Initialize the SDK with CSS variables with custom style definitions\ninit({\n // ...\n customizations: {\n style: {\n // Use CSS variables to customize styles\n customCSS: {\n variables: {\n \"--ts-var-button--primary-background\": \"#008000\",\n \"--ts-var-spotter-prompt-background\": \"#F0EBFF\",\n \"--ts-var-root-color\": \"#E3D9FC\",\n \"--ts-var-root-background\": \"#F7F5FF\",\n },\n },\n },\n },\n});\n----\n\n=== Customizing text strings\nTo replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object.\n\nThe following example shows how to replace \"Spotter\" and other text strings on the Spotter interface.\n\n[source,JavaScript]\n----\n// Initialize the SDK with custom text string replacements\ninit({\n // ...\n customizations: {\n content: {\n // Use the strings object to replace the visible UI text with custom labels.\n strings: {\n // Change all instances of \"Spotter\" to \"dataAnalyzer\"\n \"Spotter\": \"dataAnalyzer\",\n }\n }\n }\n});\n----\n\n////\n[#spotterMenuActions]\n=== Menu elements and action visibility\nThe SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays.\n\nFor a comprehensive list of supported actions, see the xref:Action.adoc[Action reference documentation].\n////\n\n\n== Additional resources\n* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience]\n* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel]\n* xref:customize-spotter + +... [truncated, 8,816 chars total] + === SpotterX experience + [.version-badge.new]#26.11.0.cl# + + SpotterX is the next-generation Spotter experience in embedded views. To enable SpotterX, set the `spotterVersion` property to `SpotterVersion.SpotterX` in your embed configuration. + + [source,JavaScript] + ---- + const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + spotterVersion: SpotterVersion.SpotterX, + worksheetId: 'your-worksheet-id', + //...other attributes + }); + ---- + + SpotterX provides a redesigned conversational interface with the following features: + + * Improved chat layout and user interaction flow + * Enhanced branding controls for text, labels, and icons + * Instance-level branding behavior controls + * Consistent configuration across Spotter, Liveboard, and full app embed contexts + * Full support for `EmbedEvent` and `HostEvent` lifecycle controls + + [NOTE] + ==== + SpotterX is opt-in. Existing Spotter embeds are unaffected unless you explicitly set `spotterVersion` to `SpotterVersion.SpotterX`. To roll back, set `spotterVersion` to `SpotterVersion.Spotter3` and re-render the component. + ==== + + \ No newline at end of file From e2ff24cd6584107e2770c6549c84753d75eaabb4 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:42:10 +0530 Subject: [PATCH 031/169] docs: add SpotterX customization section SCAL-326037 --- modules/ROOT/pages/customize-spotter-embed.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc index fd5832b53..375d07132 100644 --- a/modules/ROOT/pages/customize-spotter-embed.adoc +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -8,10 +8,10 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs { "path": "modules/ROOT/pages/customize-spotter-embed.adoc", "name": "customize-spotter-embed.adoc", - "size": 7865, - "content": "= Customize the Spotter embed view\n:toc: true\n:toclevels: 2\n\n:page-title: Customizing the Spotter embed view\n:page-pageid: customize-spotter-embed\n:page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK.\n\nThe Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users.\n\n== Spotter interface in the embedded view\nWhen 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 varies depending on the Spotter version used for embedding.\n\n=== Default experience\nThe default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.\n+\nIf Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available.\n+\n[.widthAuto]\n[.bordered]\nimage::./images/spotter-default-interface.png[Default Spotter interface]\n\n=== Spotter 3 experience\nIf your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK.\n\n[source,JavaScript]\n----\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\n worksheetId: '', // Replace with GUID of the data source\n // Enable the updated Spotter chat prompt experience.\n updatedSpotterChatPrompt: true,\n // Show chat history panel\n spotterSidebarConfig: {\n enablePastConversationsSidebar: true,\n },\n // ...other embed configuration attributes\n});\n----\n\n[.widthAuto]\n[.bordered]\nimage::./images/spotter3-interface.png[Spotter 3 experience]\n\n=== New Spotter 3 visual experience\nOn instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration.\n\n[source,JavaScript]\n----\nconst spotterEmbed = new SpotterEmbed('#ts-embed', {\n worksheetId: '', // Replace with GUID of the data source\n // Enable Spotter 3 chat experience.\n updatedSpotterChatPrompt: true,\n // Enable new Spotter visual experience\n updatedSpotterExperience: true,\n // Show chat history panel\n spotterSidebarConfig: {\n enablePastConversationsSidebar: true,\n },\n // ...other embed configuration attributes\n});\n----\n\n[.widthAuto]\n[.bordered]\nimage::./images/spotter-new-experience.png[New Spotter experience]\n\nIn the new experience, the + icon displays a menu with the following options:\n\n* **Add files** from local directory\n* **Connectors** to select available connectors\n* **Deep analysis** toggle to switch between the quick search and research mode.\n\nYou can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience].\n\n== Customizing Spotter experience\nIf you want to customize specific features or UI elements, refer to the following documentation:\n\n* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +\nFor information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding.\n* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +\nFor information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions.\n* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +\nFor information on customizing the conversation sharing experience, sharing links, and app interactions.\n* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] +\nFor information on customizing the Spotter Analysts panel and dashboard.\n\n== Customizing styles and interface elements using CSS variables\nThe Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.\n\nThe `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.\n\n[#SpotterCSS]\n=== CSS variables for style customization\nYou 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].\n\nIf 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.\n\n[source,JavaScript]\n----\n// Initialize the SDK with CSS variables with custom style definitions\ninit({\n // ...\n customizations: {\n style: {\n // Use CSS variables to customize styles\n customCSS: {\n variables: {\n \"--ts-var-button--primary-background\": \"#008000\",\n \"--ts-var-spotter-prompt-background\": \"#F0EBFF\",\n \"--ts-var-root-color\": \"#E3D9FC\",\n \"--ts-var-root-background\": \"#F7F5FF\",\n },\n },\n },\n },\n});\n----\n\n=== Customizing text strings\nTo replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object.\n\nThe following example shows how to replace \"Spotter\" and other text strings on the Spotter interface.\n\n[source,JavaScript]\n----\n// Initialize the SDK with custom text string replacements\ninit({\n // ...\n customizations: {\n content: {\n // Use the strings object to replace the visible UI text with custom labels.\n strings: {\n // Change all instances of \"Spotter\" to \"dataAnalyzer\"\n \"Spotter\": \"dataAnalyzer\",\n }\n }\n }\n});\n----\n\n////\n[#spotterMenuActions]\n=== Menu elements and action visibility\nThe SDK provides action IDs to disable, show, or hide the following elements and menu actions via `disabledActions`, `visibleActions`, or `hiddenActions` arrays.\n\nFor a comprehensive list of supported actions, see the xref:Action.adoc[Action reference documentation].\n////\n\n\n== Additional resources\n* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience]\n* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel]\n* xref:customize-spotter + "size": 9216, + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/customize-spotter-embed.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/customize-spotter-embed.adoc\",\n \"name\": \"customize-spotter-embed.adoc\",\n \"size\": 7865,\n \"content\": \"= Customize the Spotter embed view\\n:toc: true\\n:toclevels: 2\\n\\n:page-title: Customizing the Spotter embed view\\n:page-pageid: customize-spotter-embed\\n:page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK.\\n\\nThe Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users.\\n\\n== Spotter interface in the embedded view\\nWhen 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 varies depending on the Spotter version used for embedding.\\n\\n=== Default experience\\nThe default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.\\n+\\nIf Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available.\\n+\\n[.widthAuto]\\n[.bordered]\\nimage::./images/spotter-default-interface.png[Default Spotter interface]\\n\\n=== Spotter 3 experience\\nIf your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK.\\n\\n[source,JavaScript]\\n----\\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\\n worksheetId: '', // Replace with GUID of the data source\\n // Enable the updated Spotter chat prompt experience.\\n updatedSpotterChatPrompt: true,\\n // Show chat history panel\\n spotterSidebarConfig: {\\n enablePastConversationsSidebar: true,\\n },\\n // ...other embed configuration attributes\\n});\\n----\\n\\n[.widthAuto]\\n[.bordered]\\nimage::./images/spotter3-interface.png[Spotter 3 experience]\\n\\n=== New Spotter 3 visual experience\\nOn instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration.\\n\\n[source,JavaScript]\\n----\\nconst spotterEmbed = new SpotterEmbed('#ts-embed', {\\n worksheetId: '', // Replace with GUID of the data source\\n // Enable Spotter 3 chat experience.\\n updatedSpotterChatPrompt: true,\\n // Enable new Spotter visual experience\\n updatedSpotterExperience: true,\\n // Show chat history panel\\n spotterSidebarConfig: {\\n enablePastConversationsSidebar: true,\\n },\\n // ...other embed configuration attributes\\n});\\n----\\n\\n[.widthAuto]\\n[.bordered]\\nimage::./images/spotter-new-experience.png[New Spotter experience]\\n\\nIn the new experience, the + icon displays a menu with the following options:\\n\\n* **Add files** from local directory\\n* **Connectors** to select available connectors\\n* **Deep analysis** toggle to switch between the quick search and research mode.\\n\\nYou can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience].\\n\\n== Customizing Spotter experience\\nIf you want to customize specific features or UI elements, refer to the following documentation:\\n\\n* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +\\nFor information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding.\\n* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +\\nFor information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions.\\n* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +\\nFor information on customizing the conversation sharing experience, sharing links, and app interactions.\\n* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] +\\nFor information on customizing the Spotter Analysts panel and dashboard.\\n\\n== Customizing styles and interface elements using CSS variables\\nThe Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.\\n\\nThe `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.\\n\\n[#SpotterCSS]\\n=== CSS variables for style customization\\nYou 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].\\n\\nIf 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.\\n\\n[source,JavaScript]\\n----\\n// Initialize the SDK with CSS variables with custom style definitions\\ninit({\\n // ...\\n customizations: {\\n style: {\\n // Use CSS variables to customize styles\\n customCSS: {\\n variables: {\\n \\\"--ts-var-button--primary-background\\\": \\\"#008000\\\",\\n \\\"--ts-var-spotter-prompt-background\\\": \\\"#F0EBFF\\\",\\n \\\"--ts-var-root-color\\\": \\\"#E3D9FC\\\",\\n \\\"--ts-var-root-background\\\": \\\"#F7F5FF\\\",\\n },\\n },\\n },\\n },\\n});\\n----\\n\\n=== Customizing text strings\\nTo replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object.\\n\\nThe following example shows how to replace \\\"Spotter\\\" and other text strings on the Spotter interface.\\n\\n[source,JavaScript]\\n----\\n// Initialize the SDK with custom text string replacements\\ninit({\\n // ...\\n customizations: {\\n content: {\\n // Use the strings object to replace the visible UI text with custom labels.\\n -... [truncated, 8,816 chars total] +... [truncated, 10,241 chars total] === SpotterX experience [.version-badge.new]#26.11.0.cl# From 4eabc9a1af84511e6b3cd077c6f7ff772699bb40 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:43:13 +0530 Subject: [PATCH 032/169] docs: add SDK v1.54.0 November 2026 changelog entry SCAL-326037, SCAL-331936, SCAL-280403 --- modules/ROOT/pages/api-changelog.adoc | 2229 +------------------------ 1 file changed, 42 insertions(+), 2187 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 3435deff8..bbf2ed552 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1,2187 +1,42 @@ -= Visual Embed SDK changelog -:toc: true -:toclevels: 2 - -:page-title: Visual Embed SDK changelog -:page-pageid: embed-sdk-changelog -:page-description: Changelog for the Visual Embed SDK - -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]. - -== Version 1.53.0, October 2026 - -[width="100%", cols="1,4"] -|==== -|[tag greenBackground]#NEW# -a| -[discrete] -===== Spotter Analyst embed -You can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`. -For more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst]. - -|[tag greenBackground]#NEW# -a| -[discrete] -===== Spotter embedding - -`spotterChatPinConfig`:: -You can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations]. - -`starterPrompts`:: -You can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills]. - -|[tag greenBackground]#NEW# -a| -[discrete] -===== Liveboards in embedded view -The SDK includes the following enhancements for the Liveboards in your embedded app. - -* `isScopedLiveboardFilteringEnabled` + -Enables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`. -* `openSpotterOnLiveboardByDefault` + -Opens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`. -* `starterPrompts.liveboard` + -Starter prompts for the Spotter chat panel on a Liveboard. - -|[tag greenBackground]#NEW# -a| -[discrete] -===== Action IDs for embedded Spotter and Liveboard interfaces - -The following `Action` enum members are added in this release: - -* `Action.SpotterChatPin` + -Controls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu. -* `Action.SpotterAnalystList` + -Controls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface. -* `Action.SpotterDefaultAnalyst` + -Controls the visibility and enabled state of the default Spotter entry in the Analyst interface. -* `Action.SpotterOnLiveboard` + -Controls the visibility and enabled state of the *Spotter* button in the Liveboard header. -* `Action.AllLiveboardFilters` + -Shows, hides, or greys out all filter surfaces on a Liveboard: filter chips, parameter chips, and cross-filter chips at the Liveboard, tab, and group levels. Parameter and cross-filter chips can only be hidden. -* `Action.EditInputTable` + -Controls the *Edit input table* action, which lets users edit an input table used by an Answer directly from the Liveboard. -* `Action.QuickSearchPill` + -Controls the *Basic Search* starter prompt pill in the Spotter interface. -* `Action.DeepAnalysisPill` + -Controls the *Deep Analysis* starter prompt pill in the Spotter interface. -* `Action.DataLiteracyPill` + -Controls the *Data Literacy* starter prompt pill in the Spotter interface. - -|[tag greenBackground]#NEW# -a| -[discrete] -===== Events - -Embed events:: -* `EmbedEvent.SpotterConversationPinned` + -Emitted when a user pins a Spotter conversation. The event payload includes the `conversationId` and `pinnedAt` values. -* `EmbedEvent.SpotterConversationUnpinned` + -Emitted when a user unpins a Spotter conversation. The event payload includes the `conversationId` and `unpinnedAt` values. - -Host events:: -* `HostEvent.PinSpotterConversation` + -Pins a saved Spotter conversation. Accepts `{ conversationId }`. -* `HostEvent.UnpinSpotterConversation` + -Unpins a previously pinned Spotter conversation. Accepts `{ conversationId }`. -* `HostEvent.GetGroups` + -Returns filter and parameter group details for the current Liveboard. The response includes `orderedGroupIds`, `numberOfGroups`, and `Groups`. -* `HostEvent.OpenParameter` + -Opens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group. - -The pin and unpin events require `spotterChatPinConfig.enabled: true` and `enablePastConversationsSidebar: true` in the embed configuration. The host events also require chat history to be enabled on your ThoughtSpot instance. - -Updated events:: -The following existing events now include or accept an optional `applicability` attribute, which scopes filters and parameters to a Liveboard tab or group: - -* `EmbedEvent.FilterChanged` -* `EmbedEvent.ParameterChanged` -* `HostEvent.OpenFilter` -* `HostEvent.GetFilters` -* `HostEvent.UpdateFilters` -* `HostEvent.GetParameters` -* `HostEvent.UpdateParameters` - -Deprecated events:: -* `HostEvent.UpdatePersonalizedView` is deprecated. Use `HostEvent.SelectPersonalizedView` instead. `HostEvent.SelectPersonalizedView` additionally accepts an optional `viewName` to select a view by name, resets to the original view when the payload is empty, and reports an error when the named view isn't found. -|==== - -== Version 1.52.x, September 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# -a| -[discrete] -===== Spotter conversation sharing in embedded views -Embedding application users can now share a saved Spotter conversation with other users and groups directly from the embedded interface. Recipients can view the shared conversation in a read-only view. -Conversation sharing is turned off by default in embedded views. To enable it, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object. - -Interface customization settings:: -The SDK also provides the following controls for conversation sharing: - -* `SpotterShareConversationConfig` + -Includes object properties for enabling conversation sharing, label and text overrides for the share button, share modal, recipient picker, and the read-only shared view. For more information, see xref:customize-spotter-sharing.adoc[Customize conversation sharing experience]. -* `sharedConversationId` + -Allows passing conversation ID to the SpotterEmbed when the sharing link is generated for the recipient users in the embedded app. For more information, see xref:customize-spotter-sharing.adoc#_customizing_conversation_sharing_link[Conversation sharing link] - -New action IDs:: -* `Action.SpotterShareConversationButtonHeader` for **Share** button in the Spotter conversation header. -* `Action.SpotterShareConversationMenuItemSidebar` for **Share** menu action in the chat history panel in the sidebar. -* `Action.SpotterShareIncludeNewMessagesCheckbox` for the `include new messages since last shared version` checkbox in the share modal. -* `SpotterSharedConversationBannerDismissButton` for the dismiss button of the data access banner displayed in the shared conversation view. -* `Action.SpotterShareUpToCurrentInfo` for the share modal footer note. -* `Action.SpotterSharedConversationBanner` for the data access banner shown when a recipient opens a shared conversation. -* `Action.SpotterShareStaleInfoBannerDismissButton` for the banner that shows the message, "This data may have changed since the last time you had a chat." -* `Action.SpotterSharedConversationExitButton` for *Exit* button in the read-only view of the shared conversation. - -New host events:: -* `HostEvent.ShareSpotterConversation` + -Opens the Spotter share conversation modal for the given conversation ID. -* `HostEvent.ExitSpotterSharedConversation` + -Exits the read-only view of the shared conversation. -* `HostEvent.CloseSpotterShareConversation` + -Closes the Spotter share conversation modal. - -New embed events:: -* `EmbedEvent.SpotterConversationShared` + -Emitted when a Spotter conversation is shared with the intended recipients. -* `EmbedEvent.SpotterConversationShareRevoked` + -Emitted when access to a shared Spotter conversation is revoked. -* `EmbedEvent.SpotterSharedConversationViewed` + -Emitted when a recipient opens a shared Spotter conversation. -* `EmbedEvent.SpotterShareConversationButtonHeaderClicked` + -Emitted when the Share button in the conversation header is clicked. -* `EmbedEvent.SpotterShareConversationMenuItemSidebarClicked` + -Emitted when the Share action in the menu displayed for a chat in the chat history sidebar. -* `SpotterShareIncludeNewMessagesCheckboxToggled` + -Emitted when the user toggles the "include new messages since last shared version" checkbox in the share modal. -* `EmbedEvent.SpotterShareModalCancelButtonClicked` + -Emitted when the Cancel button in the share conversation modal is clicked. -* `EmbedEvent.SpotterShareStaleInfoBannerDismissed`+ -Emitted when the user dismisses the banner that shows the text, "This data may have changed since the last time you had a chat." -* `EmbedEvent.SpotterSharedConversationExitButtonClicked` + -Emitted when a user exits the shared conversation read-only view. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Browser history management in embedded application -To override the browser history behavior for embedding application users, you can now set `overrideHistoryState` in the Visual Embed SDK. Use this setting in your embed when the in-app navigation between objects pushes multiple entries onto the host application's browser history stack. When set to `true`, this feature prevents users from getting trapped in back-button loops inside the embedded iframe. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Customization controls for Collections in full application embedding -The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. - -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. - -|[tag greenBackground]#MODIFIED# a| - -[discrete] -===== Lazy loading defaults for Liveboards -When `fullHeight` is enabled on `LiveboardEmbed` or `AppEmbed`, the following lazy-loading parameters now default to `true`: - -* `lazyLoadingForFullHeight` + -Enables lazy loading of visualizations when fullHeight is enabled. -* `enableScrollableContainerLazyLoading` + -Enables lazy loading for scrollable container elements. -* `lazyLoadingMargin` + -Sets the margin for lazy loading to `'500px 0px'`. - -These defaults apply automatically. Any value you set explicitly, including `false`, overrides the default. If `fullHeight` is disabled or not specified, the behavior is not affected. - -For more information, see xref:lazy-loading-fullheight.adoc[Full height and lazy loading options for Liveboards]. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Pre-render configuration object -The SDK introduces the `PreRenderConfig` interface, which bundles the existing prerender settings such as `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` into a single object. - -The existing individual `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` properties at the top-level are deprecated in this version. Update your integration to use the new `preRenderConfig` property on `BaseViewConfig` instead of the individual top-level properties. - -For more information, see xref:prerender.adoc[Pre-rendering ThoughtSpot embed components]. - -|[tag greenBackground]#NEW# -a| - -[discrete] -===== CSS customization - -CSS variable for unsaved filter indicator:: -A new CSS variable `--ts-var-unsaved-filter-indicator-color` is available to customize the color of the "unsaved changes" indicator dot shown on filter and parameter chips. - -Insight tile CSS variables:: -New CSS variables are available to customize the Liveboard insight tile appearance: - -* `--ts-var-liveboard-insight-tile-background` + -Background color of the insight tile. -* `--ts-var-liveboard-insight-tile-icon-color` + -Color of the insight tile icon. -* `--ts-var-liveboard-insight-tile-success-color` + -Color used for positive/success indicators. -* `--ts-var-liveboard-insight-tile-failure-color` + -Color used for negative/failure indicators. - -For more information, see xref:css-customization.adoc[CSS customization framework]. - -|| -|==== - -//// -|[tag greenBackground]#NEW# a| - - -[discrete] -===== Exported host-event contract types -The SDK now publicly exports host-event contract types that were previously internal-only. This allows TypeScript consumers to strongly type `embed.trigger(HostEvent.X, payload)` calls without importing internal modules. - -Newly exported types include: - -* `UIPassthroughContractBase`, `UIPassthroughRequest`, `UIPassthroughResponse`, `UIPassthroughArrayResponse` -* `HostEventRequest`, `HostEventResponse` -* `TriggerPayload`, `TriggerResponse` -* `LiveboardTab`, `LiveboardGroup` -* `Applicability`, `ApplicabilityLevel` -* `FilterUpdate`, `LiveboardFilter`, `LiveboardParameter` -* `SpotterAnalystConfig` -* `StarterPromptsConfig`, `StarterPromptCategory`, `StarterPreviewDataCategory`, `StarterPromptQuestion` -//// - -== Version 1.51.x, August 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| - -[discrete] -===== Liveboard embedding -The SDK includes the following new features and enhancements in Liveboard embedding. - -`liveboardGutter` embed config property:: -A new `liveboardGutter` property is available on `LiveboardViewConfig`. Use this property to set the gutter spacing between tiles on an embedded Liveboard. -For more information, see xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter] - -12-column layout for Liveboard tile positioning:: -A new embed config property is available on `LiveboardViewConfig` to always use a 12-column grid layout for Liveboard tile positioning. When enabled, tile placement and sizing follow a fixed 12-column grid regardless of the Liveboard's default layout settings. -For more information, see xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards] - -New host events for the Liveboard edit page:: -* `HostEvent.OpenAddFilterModal` + -Opens the Add Filter modal in the Liveboard edit view. Trigger this event to let users add a filter without navigating the UI manually. -* `HostEvent.OpenAddParameterModal` + -Opens the Add Parameter modal in the Liveboard edit view. Trigger this event to let users add a parameter from a host application control. - -For more information, see xref:events-hostEvents.adoc#open-add-filter-parameter-modal[Host events]. - -CSS customization variables for Liveboard:: -These new CSS variables are available for Liveboard layout and header customization: - -* `--ts-var-liveboard-header-horizontal-margin` + -Sets the left and right margins of the Liveboard header. Set this to the same pixel value as `liveboardGutter` in `LiveboardViewConfig` to align the header with the tile grid. - -* `--ts-var-liveboard-dual-column-breakpoint` + -Sets the container width threshold at which the Liveboard layout collapses from 12 columns to 2 columns. + - -* `--ts-var-liveboard-single-column-breakpoint` + -Sets the container width threshold at which the Liveboard layout collapses from 2 columns to a single column. + - -For more information, see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables] and xref:customize-css-styles.adoc#_liveboard[Liveboard CSS variables]. - - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Spotter embedding - -Spotter Analysts:: -The Visual Embed SDK 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. For more information, see xref:customize-spotter-analysts.adoc#_spotter_analysts[Spotter Analysts in embed view]. - -Starter prompts:: -If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-chat-experience.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. - -|[tag greenBackground]#MODIFIED# a| - -[discrete] -===== Liveboard embedding -The following Liveboard embedding settings are set to `true` by default on all ThoughtSpot embedded instances: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filters that are not relevant to the displayed visualization. -* `isLiveboardCompactHeaderEnabled` + -Enables compact header layout in embedded Liveboards. -* `coverAndFilterOptionInPDF` + -Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. -* `isLiveboardMasterpiecesEnabled` + -Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. -* `isEnhancedFilterInteractivityEnabled` + -Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. - -For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Object format support in HostEvent.Navigate -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. - -|==== - -== Version 1.50.x, July 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| - -[discrete] -===== SpotterViz embed customization -The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. - -A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Home page customization in full application embedding -For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. - -For more information, see xref:full-app-customize.adoc[Customize full application embedding]. -|==== - -== Version 1.49.x, June 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| -[discrete] -===== Visual overrides for charts and tables -The SDK introduces the `visualOverrides` object in `SearchViewConfig` and -`AppViewConfig`, enabling embed developers to apply chart and table display -customizations to the new answers from an embedded Search data interface at initialization time. - -The `visualOverrides` object provides the following customization controls to modify the chart and table display: - -* `legend` to control legend visibility, position, and color palette of charts. -* `dataLabel` attribute for data labels and per-column label filters. -* `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 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# a| - -[discrete] -===== Liveboard browser cache refresh -For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. - -The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. - -* `EmbedEvent.RefreshLiveboardBrowserCache` + -Emitted when the Liveboard browser cache is refreshed. -* `HostEvent.RefreshLiveboardBrowserCache` + -Trigger a manual cache refresh from the host application. -* `Action.RefreshLiveboardBrowserCache` + -Action ID to show or hide the cache refresh button. - -For more information, see xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh]. - -|[tag greenBackground]#NEW# a| -[discrete] -===== Spotter file upload -The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. - -* `spotterFileUploadEnabled` + -When set to `true`, enables the file upload feature in the Spotter chat panel. - -* `spotterFileUploadFileTypes` + -Restricts the file types allowed for upload in the Spotter chat panel. - -For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. - -|==== - -== Version 1.48.x, May 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| -[discrete] -===== Liveboard embedding -The SDK includes the following new features and enhancements in Liveboard embedding. - -Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: - -When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. - -New events and action IDs;; - -* `EmbedEvent.DownloadLiveboardAsContinuousPDF` + -Emits when the download action is triggered. -* `HostEvent.DownloadLiveboardAsContinuousPDF` + -Programmatically triggers the download action to export the PDF with a continuous Liveboard layout. -* `Action.DownloadLiveboardAsContinuousPDF` + -Action ID to control the visibility of download action that exports continuous PDFs. - -Liveboard download actions:: - -The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: - -* `Action.DownloadLiveboard` + -* `Action.DownloadLiveboardAsXlsx` + -* `Action.DownloadLiveboardAsCsv` - -Test email for Liveboard scheduled jobs:: - -The SDK introduces the `isSendNowLiveboardSchedulingEnabled` to enable the **Send now** option for the Liveboard scheduled jobs. This option allows Liveboard users to send a test email notification to either themselves or the intended recipients of the Liveboard scheduled alerts. - -New events and action IDs;; - -* `EmbedEvent.SendTestScheduleEmail` + -Emits when *Send now* button is clicked. -* `HostEvent.SendTestScheduleEmail` + -Programmatically triggers the Send now action to send a test email notification for a Liveboard scheduled job. -* `Action.SendTestScheduleEmail` + -Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Spotter embedding - -The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface: - -* `Action.SpotterChatConnectorResources` + -For the connector resources section in the Spotter chat interface. -* `Action.SpotterChatConnectors` + -For the connectors panel section in the Spotter chat interface. -* `Action.SpotterChatModeSwitcher` + -For the mode switcher in the Spotter chat interface. - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Event handling -Note the following changes: - -EmbedEvent:: - -* `EmbedEvent.Subscribed` + -The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. -* `EmbedEvent.Error` + -The `EmbedEvent.Error` now fires on HostEvent payload validation failures. - -HostEvent:: -* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + -The response payload of the `GetExportRequestForCurrentPinboard` passthrough -host event has been updated to include a `type` discriminator field, making it -consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. - - -|[tag greenBackground]#NEW# a| - -[discrete] -===== Personalized View selection via host event - -* `EmbedEvent.ChangePersonalizedView` + -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]. - -* `HostEvent.SelectPersonalizedView` + -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]. - -⚠️Deprecated events and action IDs️:: -The following events are deprecated and replaced with new event IDs. - -* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. -* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. -* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. -* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. -* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. -* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. - -|==== - - -== Version 1.47.x, April 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| **Spotter chat history sidebar customization** - -The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: - -* `enablePastConversationsSidebar` + -Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. - -* `spotterSidebarTitle` + -Allows adding custom title text for the sidebar header. - -* `spotterSidebarDefaultExpanded` + -Sets the default state of the sidebar to expanded or collapsed view. - -* `spotterChatRenameLabel` + -Allows setting a custom label for the **Rename** action in the conversation edit menu. - -* `spotterChatDeleteLabel` + -Allows setting a custom label for the **Delete** action in the conversation edit menu. - -* `spotterDeleteConversationModalTitle` + -Allows editing the title text of the chat delete confirmation modal. - -* `spotterPastConversationAlertMessage` + -Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. - -* `spotterBestPracticesLabel` + -Allows customizing the label for the best practices button in the sidebar footer. - -* `spotterDocumentationUrl` + -The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. - -* `spotterConversationsBatchSize` + -Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. - -* `spotterNewChatButtonTitle` + -Allows customizing the title text for the **New chat** button in the sidebar. - -|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** - -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. - -Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. - -[source,javascript] ----- -// Deprecated -enablePastConversationsSidebar: false, - -// Recommended -spotterSidebarConfig: { - enablePastConversationsSidebar: true, - //... other config properties -} ----- - -|[tag greenBackground]#NEW# a| **Spotter chat UI branding** - -The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. - -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. - -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. - -[NOTE] -==== -These settings do not affect the external MCP tool branding. -==== - -|[tag greenBackground]#NEW# a|**Liveboard embed enhancements** - -Personalized Liveboard view:: - -The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. - -Centralized Liveboard filter setting:: - -When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. - -|[tag greenBackground]#NEW# a|**Option to include current period in rolling date filters** - -If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. -To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. -|==== - - -== Version 1.46.x, March 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| **Host events with page context framework** - -The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. - -* To enable this feature, set `useHostEventsV2` to `true`. -* To retrieve the current context, use `getCurrentContext()`. -* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. - -For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. - -|[tag redBackground]#DEPRECATED# a| **dataPanelV2** - -The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. - -|[tag greenBackground]#NEW# a| **Spotter experience** -The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. - -Chat history sidebar customization:: - -//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. -//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. -* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: -** `Action.DataModelInstructions` for the data model instructions icon. -** `Action.SpotterSidebarHeader` for the chat history sidebar header -** `Action.SpotterSidebarFooter` for the chat history sidebar footer -** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. -** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. -** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. -** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. -** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. -** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. -//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. - -Events:: -* `HostEvent.DataModelInstructions` + -Opens the Data Model instructions modal. -* `EmbedEvent.DataModelInstructions` + -Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. -* `EmbedEvent.SpotterConversationRenamed` + -Is emitted when a user renames a saved chat. -* `EmbedEvent.SpotterConversationDeleted` + -Is emitted when a saved chat is deleted. -* `EmbedEvent.SpotterConversationSelected` + -Is emitted when a saved chat is selected in the chat history sidebar. - -|[tag greenBackground]#NEW# | `enableLinkOverridesV2` + - -Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. - -|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** - -* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. -* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. -|==== - -== Version 1.45.0, February 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| **Spotter enhancements** - -You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. - -* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. -* To use Auto mode, set the `worksheetId` to `auto_mode`. -* To enable Chat history, set `enablePastConversationsSidebar` to `true`. - -For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. - -Events:: - -* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session -* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. -* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. - -[NOTE] -==== -On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. -==== - -|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** + - -Styling and grouping:: - -* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. -* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: -** `Action.MoveToGroup` for the **Move to Group** menu action. -** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. -** `Action.CreateGroup` for the *Create Group* menu action. -** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. - -Filter chip masking:: -The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. -+ -For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. -+ -The `showMaskedFilterChip` setting is also available in full application embedding. - -|[tag greenBackground]#NEW# a| **Publishing objects** - -The following action IDs are available for the data publishing menu actions in the *Data workspace* page: - -* `Action.Publish` for *Publish* -* `Action.ManagePublishing` for *Manage publishing* -* `Action.Unpublish` for *Unpublish* -* `Action.Parameterize` for *Parameterize* -|[tag greenBackground]#NEW# a| **Error handling improvements** - -To handle errors in the embedding workflows, the SDK includes the following features: - -* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. -* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. -* `EmbedErrorDetailsEvent` interface for structured error event handling. - -For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. -|==== - -== Version 1.44.x, January 2026 - -[width="100%" cols="1,4"] -|==== - -|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + - -The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. -To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. - -|[tag greenBackground]#NEW# a| *Intercepting API calls* + -The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: - -//* `enableApiIntercept` + -//When set to true, enables the feature on your ThoughtSpot embed. -* `interceptUrls` + -Allows configuring which API calls to intercept. -* `interceptTimeout` + -Sets the timeout duration for handling interception. -* `isOnBeforeGetVizDataInterceptEnabled` + -When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. -* `EmbedEvent.ApiIntercept` + -Emits when an API call matching the conditions defined in `interceptUrls` is detected. - -For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. -|==== - - -== Version 1.43.0, November 2025 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| *Code-based custom actions* - -The following enumerations are available for code-based custom actions: - -* `CustomActionTarget` + -To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. -* `CustomActionsPosition` + -To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW# | *Attribute to set Parameter chip visibility during overrides* + -The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. -|==== - -== Version 1.42.0, October 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|*Runtime overrides in Spotter embed* - -The Visual Embed SDK now supports runtime overrides in Spotter embed. - -* To apply runtime filters, use the `runtimeFilters` object -* To apply runtime Parameters, use the `runtimeParameters` object. - -|[tag greenBackground]#NEW# a|*PNG images in Liveboard schedule notifications* + -To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. - -The SDK also provides the following action IDs: - -* `Action.PngScreenshotInEmail` + -Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. -* `Action.RemoveAttachment` + -Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW# a|*Spotter embed* - -Action IDs:: -The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: - -* `Action.SpotterWarningsBanner` + -Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. -* `Action.SpotterWarningsOnTokens` + -Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. -* `Action.SpotterTokenQuickEdit` + -Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. -|==== - -== Version 1.41.0, September 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|*React component for Spotter Agent embed* - -The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. - -For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. - -|[tag greenBackground]#NEW# a|*Event handlers for Spotter embed* - -The following event handlers are now available for Spotter embed: - -* `EmbedEvent.SpotterInit` + -Fires when Spotter embed component rendering is initialized. -* `EmbedEvent.QueryChanged` + -Fires when the Spotter query is updated by the user. -* `HostEvent.AskSpotter` + -Triggers *Ask Spotter* action for visualizations. -* `HostEvent.GetParameters` + -Triggers the action to fetch runtime Parameters applied on a visualization. -* `HostEvent.UpdateParameters` + -Triggers the action to update runtime Parameters for a Spotter-generated Answer. -* `HostEvent.GetTML` + -Triggers the action to get TML representation of a Spotter-generated Answer. - -For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW# a|*Event handlers for Spotter Agent embed* - -You can now use the following host events in Spotter Agent embedding: - -- `HostEvent.DownloadAsCsv` + -Triggers the action to download a Spotter-generated Answer in CSV format. -- `HostEvent.DownloadAsPng` + -Triggers the action to download a Spotter-generated Answer in PNG format. -- `HostEvent.DownloadAsXlsx` + -Triggers the action to download a Spotter-generated Answer in XLSX format. -- `HostEvent.DownloadAsPdf` + -Triggers the action to download the PDF version of a Spotter-generated Answer. -- `HostEvent.Pin` + -Triggers the action to add a Spotter-generated Answer to a Liveboard. -- `HostEvent.Save` + -Triggers the *Save* action for a Spotter-generated Answer. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW# a| *Lazy loading of visualizations on an embedded Liveboard* - -You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -You can also set the margin property for lazy loading to define when the visualization should load. - -For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. - -|[tag greenBackground]#NEW# a| *Full application embed* + - -You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. - -When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. -|==== - -== Version 1.40.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + -Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW# a| *PDF download settings* + -Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. - -|[tag greenBackground]#NEW# a| *Parameter for overriding a default primary action* + - -If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. - -For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. - -|[tag greenBackground]#NEW# a| *Full application embed experience enhancements* + - -The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. - -|[tag greenBackground]#NEW# a| *Host events* + - -In this version, the SDK introduces the following host event handlers: - -- `HostEvent.ExitPresentMode` + -Triggers the exit action that allows users to exit the Liveboard or visualization present mode. -- `HostEvent.SpotterSearch` + -Triggers a search operation for the specified query string in Spotter embed. -- `HostEvent.PreviewSpotterData` + -Triggers the *Preview data* action that shows the data used for Spotter conversations. -- `HostEvent.ResetSpotterConversation` + -Triggers the *Reset* action to reset a Spotter conversation. -- `HostEvent.EditLastPrompt` + -Triggers the edit prompt action. -- `HostEvent.DeleteLastPrompt` + -Triggers the delete prompt action. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW# a|*Events support for Spotter embed* - -You can now use the following host events in Spotter embed: - -- `HostEvent.DownloadAsCsv` -- `HostEvent.DownloadAsPng` -- `HostEvent.DownloadAsXlsx` -- `HostEvent.Edit` -//- `HostEvent.GetParameters` -//- `HostEvent.GetTML` -- `HostEvent.MakeACopy` -- `HostEvent.Pin` -- `HostEvent.Save` - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW# a| *Lazy loading with full height* - -The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. -This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -[NOTE] -==== -To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. -==== -|==== - - -== Version 1.39.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| *Spotter embed components with new names* + -The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: - -* `ConversationEmbed` + -Replaced with `SpotterEmbed` -* `ConversationViewConfig` + -Replaced with `SpotterEmbedViewConfig` -* `BodylessConversation` + -Replaced with `SpotterAgentEmbed` -* `BodylessConversationViewConfig` + -Replaced with `SpotterAgentEmbedViewConfig` - -The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. - -|[tag greenBackground]#NEW# a| *Action ID for Spotter in-conversation training* + -For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. - -[NOTE] -The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. - -|[tag greenBackground]#NEW# a|*Events support for Spotter embed* - -New embed events:: - -- `EmbedEvent.ExitPresentMode` + -Emits when a user exits the Liveboard or visualization presentation mode. -- `EmbedEvent.LastPromptDeleted` + -Emits when a query prompt in Spotter embed is deleted. -- `EmbedEvent.LastPromptEdited` + -Emits when a query prompt in Spotter embed is edited. -- `EmbedEvent.ResetSpotterConversation` + -Emits when a Spotter query is reset. -- `EmbedEvent.PreviewSpotterData` + -Emits when a user clicks the Preview data button in the Spotter conversation panel. -- `EmbedEvent.SpotterQueryTriggered` -Emits when a Spotter query is triggered. - -The following embed events are also supported in Spotter embed: - -- `EmbedEvent.AddRemoveColumns` -- `EmbedEvent.AnswerChartSwitcher` -- `EmbedEvent.AuthExpire` -- `EmbedEvent.AuthInit` -- `EmbedEvent.CopyToClipboard` -- `EmbedEvent.CustomAction` -- `EmbedEvent.Data` -- `EmbedEvent.DataSourceSelected` -- `EmbedEvent.DialogClose` -- `EmbedEvent.DialogOpen` -- `EmbedEvent.Download` -- `EmbedEvent.DownloadAsCsv` -- `EmbedEvent.DownloadAsPng` -- `EmbedEvent.DownloadAsXlsx` -- `EmbedEvent.DrillDown` -- `EmbedEvent.DrillExclude` -- `EmbedEvent.DrillInclude` -- `EmbedEvent.Edit` -- `EmbedEvent.Error` -- `EmbedEvent.Load` -- `EmbedEvent.Pin` -- `EmbedEvent.Save` -- `EmbedEvent.TableVizRendered` -- `EmbedEvent.VizPointClick` -- `EmbedEvent.VizPointDoubleClick` -- `EmbedEvent.VizPointRightClick` - -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -|==== - -== Version 1.38.0, June 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| *String IDs for text customization* + -Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. - -To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. - -Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. - -For more information, see xref:customize-text-strings.adoc[Customize text strings]. - -|[tag greenBackground]#NEW# a| *Hide columns on list pages* + - -In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: - -* *Author* + -`hiddenListColumns: [ListPageColumns.Author]` -* *Favorite* + -`hiddenListColumns: [ListPageColumns.Favourite]` -* *Last modified* + -`hiddenListColumns: [ListPageColumns.DateSort]` -* *Tags* + -`hiddenListColumns: [ListPageColumns.Tags]` -* *Share* + -`hiddenListColumns: [ListPageColumns.Share]` + - -For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. -|==== - -== Version 1.37.0, April 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| -The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. -This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. - -For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. - -|[tag greenBackground]#NEW# a| -You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. - -|[tag greenBackground]#NEW# a| This version of the SDK supports the following embed and host events: - -Embed Events:: - -* `EmbedEvent.TableVizRendered` + -Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. - -* `EmbedEvent.CreateLiveboard` + -Emits when a Liveboard is created. - -Host Events:: - -* `HostEvent.TransformTableVizData` + -Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. - -* `HostEvent.Remove` + -Triggers the *Delete* action on a Liveboard. -|==== - -== Version 1.36.0, February 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| -The following HostEvents now allow custom parameters to set object properties programmatically: - -* `HostEvent.SaveAnswer` + -Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. -* `HostEvent.Pin` + -Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. - -For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. - -|[tag greenBackground]#NEW# a| - -New configuration attributes:: - -* `disableSourceSelection` + -Disables data source selection panel for embed users when set to `true`. -* `hideSourceSelection` + -Hides data source selection panel when set to `true` -* `locale` + -Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. -* `showSpotterLimitations` + -Shows functional limitations of Spotter when set to `true` -* `hideSampleQuestions` + -Hides sample questions that appear on the default Spotter page. - -Action IDs for menu customization:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: - -* `Action.PreviewDataSpotter` + -The *Preview data* button on the Spotter conversation panel. -* `Action.ResetSpotterChat` + -The *Reset* button on the Spotter conversation panel. -* `Action.SpotterFeedback` + -The feedback widget on Spotter-generated charts. -* `Action.EditPreviousPrompt` + -The edit icon on the prompt panel. -The Prompt panel appears after Spotter generates a response to a user query. -* `Action.DeletePreviousPrompt` + -The delete icon on the prompt panel. - -//// -* `Action.EditTokens` + -The option to edit tokens on a Spotter-generated chart or table. -//// -CSS variables:: - -The following new CSS variables are available for Spotter interface customization: - -* `--ts-var-spotter-input-background` -* `--ts-var-spotter-prompt-background` - -For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. -|[tag greenBackground]#NEW# a| - - -Configuration attributes:: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filter chips on a Liveboard when set to `true`. - -* `isLiveboardCompactHeaderEnabled` + -Enables the compact Liveboard header feature when set to `true`. - -Action IDs:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: - -* `Action.DisableChipReorder` + -ID for the action that disables filter chip reordering. -* `Action.ChangeFilterVisibilityInTab` - -|==== - -== Version 1.35.0, December 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| -The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: - -* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface -* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. - -For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. - -|[tag greenBackground]#NEW# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. -|==== - -== Version 1.34.0, November 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| You can now embed the following ThoughtSpot Spotter components in your app: - -* `SpotterEmbed` + -Embeds Spotter conversation interface in your app -* `SpotterAgentEmbed` + -Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. - -For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. - -|[tag greenBackground]#NEW# a|The following parameters and enumerations are available for customizing Liveboard experience: - -* `showLiveboardVerifiedBadge` + -Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. -* `showLiveboardReverifyBanner` + -Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. -* `Action.KPIAnalysisCTA` + -Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. - -|[tag greenBackground]#NEW# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. - -|[tag greenBackground]#NEW# a|The following parameters are available for customizing Search experience: - -* `collapseDataPanel` -Minimizes the data panel view. Users can click the data panel header any time to expand the panel. -* `collapseSearchBar` -Sets the initial state of the search bar when embedding a saved Answer. - -|[tag greenBackground]#NEW# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: - -* `HomeLeftNavItem.LiveboardSchedules` + -The Liveboard schedules menu on the left navigation panel. - -Action enumerations:: - -* `Action.EditScheduleHomepage` + -To show, disable, or hide the *Edit* action on the *Liveboard schedules* page -* `Action.PauseScheduleHomepage` + -To show, disable, or hide the *Pause* action on the *Liveboard schedules* page -* `Action.ViewScheduleRunHomepage` + -To show, disable, or hide the *View run history* action on the *Liveboard schedules* page -* `Action.DeleteScheduleHomepage` + -To show, disable, or hide the *Delete* action on the *Liveboard schedules* page -* `Action.UnsubscribeScheduleHomepage` + -To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page -|==== - -== Version 1.33.x, October 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. - -You can set the `homePageSearchBarMode` property to one of the following options: - -** `aiAnswer` + -Displays the search bar for Natural Language Search. -** `none` -Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. -** `objectSearch` (default) + -Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW# a| The SDK includes the following Event and Action enumeration members: - -Events:: - -* `EmbedEvent.OnBeforeGetVizDataIntercept` + -Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. - -* `EmbedEvent.ParameterChanged` + -Emitted when a Parameter is changed on a saved Answer or Liveboard. - -Actions:: - -* `Action.ManageTags` + -Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. -|==== - -== Version 1.32.x, August 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The following new action enumerations are available in this version: + - -* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + -* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. -* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. -* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. -* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. -* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. -* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) -For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. -|| -|==== - -== Version 1.31.x, July 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| Runtime filters + - -* `NOT_IN` operator for Runtime filters. -For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. -* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. -|==== - -== Version 1.30.0, June 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| **CSS variables for new homepage experience** - -* `--ts-var-home-watchlist-selected-text-color` + -* `--ts-var-home-card-color` + -* `--ts-var-home-favorite-suggestion-card-text-color` + -* `--ts-var-home-favorite-suggestion-card-background` + -* `--ts-var-home-favorite-suggestion-card-icon-color` - -For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. -|==== - -== Version 1.29.0, May 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| **Ask Sage** - -With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. - -Action enumeration:: -To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, -+ -[source,JavaScript] ----- -hiddenActions: [Action.AskAi] ----- - -Events:: -* `HostEvent.AskSage` + -Triggers the **Ask Sage** action on a Liveboard visualization. -* `EmbedEvent.AskSageInit` + -Emits when the **Ask Sage** action is initialized. -* `HostEvent.GetParameters` + -Triggers a fetch action to get runtime Parameters. -* `HostEvent.UpdateParameters` + -Updates runtime Parameters -* `HostEvent.ResetLiveboardPersonalisedView` + -Resets a personalized Liveboard view. -* `HostEvent.UpdateCrossFilter` + -Updates cross filters applied on a Liveboard. -|==== - -== Version 1.28.x, April 2024 - -[width="100%" cols="1,4"] -|===== -|[tag greenBackground]#NEW# a| The SDK includes the following new enumeration members in v1.28.0: - -** `Action.VerifiedLiveboard` + -Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: - -* `hiddenhomeleftnavitems` -* `hiddenhomepagemodules` -* `hideapplicationswitcher` -* `hidehomepageleftnav` -* `hideorgswitcher` -* `reorderedhomepagemodules` -* `HomeLeftNavItem` - -For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW# a| The following embed event is available from the v1.28.0 onwards: - -`EmbedEvent.Rename` + -Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW# a| TML actions - -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 -* Update TML - -To show, hide, or disable these actions in the embedded mode, use the following format: - -[source,JavaScript] ----- - // to show the TML menu and its sub-menu options -visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] ----- - -[source,JavaScript] ----- - // to hide all TML actions -hiddenActions: [Action.TML] ----- - -[source,JavaScript] ----- - // to disable all TML actions -disabledActions: [Action.TML] ----- -|[tag greenBackground]#NEW# | You can now reset authentication token and fetch a new token for new authentication requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. - -|[tag greenBackground]#NEW#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: - -* `numberFormatLocale` + -* `dateFormatLocale` + -* `currencyFormat` - -For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. - -|[tag greenBackground]#NEW# |Tokenized fetch + -The SDK now provides a fetch wrapper that adds the authentication token to the API requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. -|===== - -== Version 1.27.x, March 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The following action enumeration members are available from v1.27.9 and v1.27.10: - -* `Action.AIHighlights` -* `Action.AddToWatchlist` -* `Action.RemoveFromWatchlist` -* `Action.CopyKpiLink` - -For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. -|==== - -== Version 1.27.0, January 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. - -//For a complete list of methods, functions, interface objects, and properties, see the following pages: + -// -//* xref:SageEmbed.adoc[SageEmbed] -//* xref:SageViewConfig.adoc[SageViewConfig] - -|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. -For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following new enumeration members: - -* Host Events -** `HostEvent.UpdateSageQuery` + -Updates the search query string for Natural Language Search operations. -* Embed Events -** `EmbedEvent.CreateConnection` + -Emitted when a user creates a new data connection on the **Data** page. -** `EmbedEvent.CreateWorksheet` + -Emitted when a user creates a new Worksheet. -|==== - -== Version 1.26.0, November 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. -You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. - -|[tag greenBackground]#NEW# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: - -* `showLiveboardDescription` + -Shows the Liveboard description text when set to `true` -* `showLiveboardTitle` + -Shows the Liveboard title when set to `true` -* `isLiveboardHeaderSticky` + -Sets Liveboard header bar as a fixed element when set to `true` -* `hideLiveboardHeader` + -Hides the Liveboard header when set to `true` -* `hiddenTabs` + -Hides the specified tabs from the Liveboard page -* `visibleTabs` + -Displays the specified tabs on the Liveboard page - -|[tag greenBackground]#NEW# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. - -|[tag greenBackground]#NEW# a|The new version of the SDK supports the following events: - -Embed events:: -* `EmbedEvent.hiddenTabs` -* `EmbedEvent.visibleTabs` -* `EmbedEvent.UpdatePersonalisedView` -* `EmbedEvent.SavePersonalisedView` -* `EmbedEvent.ResetLiveboard` -* `EmbedEvent.DeletePersonalisedView` -* `EmbedEvent.SageWorksheetUpdated` -* `EmbedEvent.SageEmbedQuery` -+ -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -Host events:: - -* `HostEvent.GetTabs` -* `HostEvent.SetVisibleTabs` -* `HostEvent.SetHiddenTabs` -* `HostEvent.GetAnswerSession` -* `HostEvent.UpdateSageQuery` -+ -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: - -* `Action.AddTab` + -Show, disable, or hide the **Add Tab** action on a Liveboard. -* `Action.PersonalisedViewsDropdown` + -Show, disable, or hide the Liveboard views saved by a user. -* `Action.LiveboardUsers` + -Show, disable, or hide Liveboard users. -* `Action.SageAnswerFeedback` -Show, disable, or hide the feedback widget on AI-generated Answer page. -* `Action.EditSageAnswer` -Show, disable, or hide the **Edit** action on the AI-generated Answer page. - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.25.0, October 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. -For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. - -|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: - -* `Action.RenameModalTitleDescription` -* `Action.EnableContextualChangeAnalysis` -* `Action.RequestVerification` -* `Action.AddTab` - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.24.0, September 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. -|==== - -== Version 1.23.0, August 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -|==== - -//// -|[tag greenBackground]#NEW# a| New events for Liveboard filters + - -* `EmbedEvent.FilterChanged` + -* `HostEvent.GetFilters` + -* `HostEvent.UpdateFilters` -//// - -== Version 1.22.0, June 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. - -For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. - -|[tag greenBackground]#NEW# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. - -For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. - -|==== - -//// -|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -//// - -== Version 1.21.0, May 2023 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following action enumeration members: - -* `Action.AxisMenuAggregate` -* `Action.AxisMenuConditionalFormat` -* `Action.AxisMenuEdit` -* `Action.AxisMenuFilter` -* `Action.AxisMenuGroup` -* `Action.AxisMenuNumberFormat` -* `Action.AxisMenuPosition` -* `Action.AxisMenuRemove` -* `Action.AxisMenuRename` -* `Action.AxisMenuSort` -* `Action.AxisMenuTextWrapping` -* `Action.AxisMenuTimeBucket` -* `Action.CrossFilter` -* `Action.RemoveCrossFilter` - -For more information, see xref:embed-action-ref.adoc[Action reference]. - -|[tag greenBackground]#NEW# a| The SDK introduces the following events: - -* `HostEvent.AddColumns` -* `HostEvent.OpenFilter` -* `HostEvent.RemoveColumn` -* `HostEvent.ResetSearch` -* `EmbedEvent.CrossFilterChanged` -* `EmbedEvent.DownloadAsPng` -* `EmbedEvent.VizPointRightClick` - -For more information, see xref:embed-events.adoc[Events]. - -|[tag redBackground]#DEPRECATED# a| - -The following events are deprecated from version 1.21.0 onwards. - -* `HostEvent.Download` + -* `EmbedEvent.Download` - -You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. - -For more information, see xref:embed-events.adoc[Events reference]. -|[tag orangeBackground]#MODIFIED# a| - -Events:: -The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. -Actions:: -Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: -+ -* `Action.DownloadAsCsv` -* `Action.DownloadAsPdf` -* `Action.DownloadAsXlsx` -* `Action.DownloadAsPng` - -To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + - -** `Action.DownloadAsCsv` + -** `Action.DownloadAsPdf` + -** `Action.DownloadAsXlsx` + -** `Action.DownloadAsPng` - -|[tag greenBackground]#NEW# a| The SDK includes new attributes to customize the experience for embedded app users: - -* `linkOverride` -+ -Allows overriding the *Open in new tab* link on embedded pages. - -* `contextMenuTrigger` -+ -Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. - -* `hideSearchBar` -+ -Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW# | The SDK now allows setting the loading preference for embedded iFrames. -For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. -|==== - -== Version 1.20.0, April 2023 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. -|==== - -== Version 1.19.0, February 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: - -[source,JavaScript] ----- -liveboardEmbed.on(EmbedEvent.CustomAction, payload => { - if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { - console.log('Custom Action event:', payload.data); - } -}) ----- - -You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. - -|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following Host events: - -* `HostEvent.Delete` -* `HostEvent.Download` -* `HostEvent.DownloadAsCsv` -* `HostEvent.DownloadAsXlsx` -* `HostEvent.ManagePipelines` -* `HostEvent.Save` -* `HostEvent.Share` -* `HostEvent.ShowUnderlyingData` -* `HostEvent.SpotIQAnalyze` -* `HostEvent.SyncToOtherApps` -* `HostEvent.SyncToSheets` - -For more information, see xref:events-hostEvents.adoc[Host events]. - -|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. - -For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. -|==== - -== Version 1.18.0, January 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + - -For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. - -|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + - -For more information, see xref:HostEvent.adoc#_gettml[GetTML]. - -|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following enums in the `Action` object: - -* `Action.SyncToOtherApps` + -* `Action.SyncToSheets` + -* `Action.ManagePipelines` + - -You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. - -For more information, see xref:embed-action-ref.adoc[Actions]. -|==== - -== Version 1.17.1, December 2022 - -Bug fixes to the trusted authentication feature. - -== Version 1.17.0, November 2022 - -The new version of the SDK introduces several new features and enhancements. -[width="100%" cols="1,4"] -|==== -|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + - -* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + -* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + -* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + -This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + -For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW#| -The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|==== - -== Version 1.16.0, October 2022 - -The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. - -== Version 1.15.1, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| -The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|==== - -== Version 1.15.0, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| -For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. - -For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]. - -|[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: - -* CopyLink -* CreateMonitor -* DownloadAsPdf -* Edit -* EditTML -* Explore -* ExportTML -* LiveboardInfo -* MakeACopy -* ManageMonitor -* Pin -* Present -* Remove -* Schedule -* SchedulesList -* UpdateTML - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.14.0, August 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| -The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. -The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. -|==== - -== Version 1.13.0, July 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| -This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + -For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. -|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + -This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.12.0, June 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| -This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. -|==== - -== Version 1.11.2, June 2022 - -Bug fix for Typescript builds that affect Angular project configurations. - -== Version 1.11.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. -|==== - -== Version 1.11.0, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The new version of SDK includes the following new events: - -* `ALL` -* `AnswerChartSwitcher` -* `AnswerDelete` -* `CopyAEdit` -* `CopyToClipboard` -* `Download` -* `DownloadAsPdf` -* `DownloadAsCsv` -* `DownloadAsXlsx` -* `DrillExclude` -* `DrillInclude` -* `EditTML` -* `ExportTML` -* `Monitor` -* `Pin` -* `Save` -* `SaveAsView` -* `Share` -* `ShowUnderlyingData` -* `SpotIQAnalyze` -* `UpdateTML` -* `VizPointClick` - -For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. - -|[tag greenBackground]#NEW# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. -|==== - -== Version 1.10.4, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. -|==== -== Version 1.10.3, May 2022 - -Bug fix and improvements to the `logout` method. - -== Version 1.10.2, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. -|==== - -== Version 1.10.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#|You can now use the `logout` method to log out embed users. -|[tag orangeBackground]#MODIFIED# a| Note the following changes: + - -* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. -* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. -|==== - -== Version 1.10.0, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.8, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. - -For more information, see xref:full-embed.adoc[Embed full application]. -|==== - -== Version 1.9.6 and 1.9.7, April 2022 - -Bug fixes and improvements - -== Version 1.9.5, April 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. -For more information, see xref:locale-setting.adoc[Set locale and display language]. -|==== - -== Version 1.9.4, April 2022 - -Bug fixes and improvements to React components. - -== Version 1.9.3, March 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + -You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + -This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. - -For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. -|==== - -== Version 1.9.2, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| You can now trigger events on React components using the `useEmbedRef` hook. - -For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. -|==== - -== Version 1.9.1, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. - -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. - -|[tag greenBackground]#NEW# a| The following events are now available in the SDK: + - -* `LiveboardRendered` (EmbedEvent) - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.0, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a| The SDK now includes the following new enumerations for UI actions: - -* `Action.AnswerDelete` + -* `Action.AnswerChartSwitcher` + -* `Action.AddToFavorites` + -* `Action.EditDetails` + - -For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. - -|[tag greenBackground]#NEW# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.8.x, February 2022 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. -|==== - - -== Version 1.7.0, January 2022 - -[width="100%" cols="1,4"] -|==== -| -[tag greenBackground]#NEW# |+++
OIDC AuthType
+++ - -The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. - -For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW# a|+++
Embed events
+++ - -The SDK includes the following new event: - -* `RouteChange` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.6.x, November 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|+++
Visible actions
+++ - -You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. - -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. - -|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ - -The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. - -|[tag greenBackground]#NEW# a|+++
Embed events
+++ - -The SDK supports the following new events: - -* `DialogOpen` -* `DialogClose` - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.5.0, October 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW# | +++
Render embedded objects in queue
+++ - -The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. - -|[tag greenBackground]#NEW# a|+++
Liveboard embed
+++ - -The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. - -For more information, see xref:embed-search.adoc[Embed a pinboard]. - -|[tag greenBackground]#NEW# a|+++
Embed events
+++ - -The SDK EmbedEvent library includes the following new events: - -* `VizPointDoubleClick` -* `Drilldown` -* `SetVisibleVizs` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.4.0, September 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW# a|+++
+++Prefetch API+++
+++ - -The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. - -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. - -|[tag greenBackground]#NEW# a|+++
+++In-app page navigation+++
+++ - -The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. - -For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. - -|[tag greenBackground]#NEW# a|+++
+++Full application embedding+++
+++ - -The `appEmbed` SDK package includes the following new attributes: - -* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. - -* The `hideObjects` attribute to hide specific objects from a user's page view. - -For more information, see xref:full-embed.adoc[Embed full application]. - -|[tag greenBackground]#NEW# |+++
+++Search embed +++
+++ - -The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. - -For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. - -|[tag redBackground]#REMOVED# | - -The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW# a|+++
+++Embed events +++
+++ -The SDK EmbedEvent library includes the following events: - -* `QueryChanged` -* `AuthExpire` - -For more information, see xref:embed-events.adoc[Events and app integration]. -|==== - -== Version 1.3.0, August 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW# a| +++
searchOptions
+++ - -The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: - -* `searchTokenString` -+ -A TML query string to define search tokens. - -* `executeSearch` -+ -When set to `true`, it executes search and shows the search results. - -For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ - -The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. - -For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag greenBackground]#NEW# a| +++
autoLogin
+++ - -The SDK now supports logging in users automatically after a user session has expired. - -For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. - -|[tag greenBackground]#NEW# a| +++
shouldEncodeUrlQueryParams
+++ - -You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. -|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ - -* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. - -* The Answer payload for custom actions includes the following metadata: - -** `reportBookmetadata` -+ -Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. - -** user data -+ -Includes user information such as username, GUID of the user, and email address. - -To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. - -|[tag greenBackground]#NEW# a| +++
preventPinboardFilterRemoval
+++ - -The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. - -For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW# a| +++
suppressNoCookieAccessAlert
+++ - -You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. - -|[tag greenBackground]#NEW# a| +++
Support for fetching callback custom action payload in batches
+++ - -The Visual Embed SDK now supports processing data in batches for callback custom action responses. -The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. - -For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. -|==== - -== Version 1.2.0, June 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|+++
SAML authentication
+++ - -The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. - -For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. - -|[tag greenBackground]#NEW# a|+++
Pinboard actions
+++ -The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. - -Pinboard:: -* Save -* Make a copy -* Add filters -* Configure filters -* Present -* Download as PDF -* Pinboard info -* Manage schedules - - -[NOTE] -Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW# a|+++
Visualization actions
+++ - -Visualizations on a pinboard: - -* Pin -* Download -* Edit -* Present -* Download as CSV -* Download as XLSX -* Download as PDF - -[NOTE] -Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. - -|==== - -== Version 1.1.0, May 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW# a|+++
NoCookieAccess event
+++ - -When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. -To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== +--- CITABLE SOURCE --- +File: modules/ROOT/pages/api-changelog.adoc +Branch: docs/scal-26-11-0-cl-doc-updates +URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc +To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number} +--- + +{ + "path": "modules/ROOT/pages/api-changelog.adoc", + "name": "api-changelog.adoc", + "size": 106492, + "content": "= Visual Embed SDK changelog\n:toc: true\n:toclevels: 2\n\n:page-title: Visual Embed SDK changelog\n:page-pageid: embed-sdk-changelog\n:page-description: Changelog for the Visual Embed SDK\n\nThis 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].\n\n== Version 1.54.0, November 2026 + + [width="100%", cols="1,4"] + |==== + |[tag greenBackground]#NEW# + a| + [discrete] + ===== SpotterX embed support + You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts. + + For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. + + |[tag greenBackground]#NEW# + a| + [discrete] + ===== Host-controlled tooltip rendering + The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely. + + For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views]. + + |[tag greenBackground]#NEW# + a| + [discrete] + ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^ + You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction. + + |==== + + == Version 1.53.0, October 2026\n\n[width=\"100%\", cols=\"1,4\"]\n|====\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Spotter Analyst embed\nYou can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`.\nFor more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst].\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Spotter embedding\n\n`spotterChatPinConfig`::\nYou can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations].\n\n`starterPrompts`::\nYou can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills].\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Liveboards in embedded view\nThe SDK includes the following enhancements for the Liveboards in your embedded app.\n\n* `isScopedLiveboardFilteringEnabled` +\nEnables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`.\n* `openSpotterOnLiveboardByDefault` +\nOpens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`.\n* `starterPrompts.liveboard` +\nStarter prompts for the Spotter chat panel on a Liveboard.\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Action IDs for embedded Spotter and Liveboard interfaces\n\nThe following `Action` enum members are added in this release:\n\n* `Action.SpotterChatPin` +\nControls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu.\n* `Action.SpotterAnalystList` +\nControls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface.\n* `Action.SpotterDefaultAnalyst` +\nControls the visibility and enabled state of the default Spotter entry in the Analyst interface.\n* `Action.SpotterOnLiveboard` +\nControls the visibility and enabled state of the *Spotter* button in the Liveboard header.\n* `Action.AllLiveboardFilters` +\nShows, hides, or greys out all filter surfaces on a Liveboard: filter chips, parameter chips, and cross-filter chips at the Liveboard, tab, and group levels. Parameter and cross-filter chips can only be hidden.\n* `Action.EditInputTable` +\nControls the *Edit input table* action, which lets users edit an input table used by an Answer directly from the Liveboard.\n* `Action.QuickSearchPill` +\nControls the *Basic Search* starter prompt pill in the Spotter interface.\n* `Action.DeepAnalysisPill` +\nControls the *Deep Analysis* starter prompt pill in the Spotter interface.\n* `Action.DataLiteracyPill` +\nControls the *Data Literacy* starter prompt pill in the Spotter interface.\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Events\n\nEmbed events::\n* `EmbedEvent.SpotterConversationPinned` +\nEmitted when a user pins a Spotter conversation. The event payload includes the `conversationId` and `pinnedAt` values.\n* `EmbedEvent.SpotterConversationUnpinned` +\nEmitted when a user unpins a Spotter conversation. The event payload includes the `conversationId` and `unpinnedAt` values.\n\nHost events::\n* `HostEvent.PinSpotterConversation` +\nPins a saved Spotter conversation. Accepts `{ conversationId }`.\n* `HostEvent.UnpinSpotterConversation` +\nUnpins a previously pinned Spotter conversation. Accepts `{ conversationId }`.\n* `HostEvent.GetGroups` +\nReturns filter and parameter group details for the current Liveboard. The response includes `orderedGroupIds`, `numberOfGroups`, and `Groups`.\n* `HostEvent.OpenParameter` +\nOpens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group.\n\nThe pin and unpin events require `spotterChatPinConfig.enabled: true` and `enablePastConversationsSidebar: true` in the embed configuration. The host events also require chat history to be enabled on your ThoughtSpot instance.\n\nUpdated events::\nThe following existing events now include or accept an optional `applicability` attribute, which scopes filters and parameters to a Liveboard tab or group:\n\n* `EmbedEvent.FilterChanged`\n* `EmbedEvent.ParameterChanged`\n* `HostEvent.OpenFilter`\n* `HostEvent.GetFilters`\n* `HostEvent.UpdateFilters`\n* `HostEvent.GetParameters`\n* `HostEvent.UpdateParameters`\n\nDeprecated events::\n* `HostEvent.UpdatePersonalizedView` is deprecated. Use `HostEvent.SelectPersonalizedView` instead. `HostEvent.SelectPersonalizedView` additionally accepts an optional `viewName` to select a view by name, resets to the original view when the payload is empty, and reports an error when the named view isn't found.\n|====\n\n== Version 1.52.x, September 2026\n\n[width=\"100%\" cols=\"1,4\"]\n|====\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Spotter conversation sharing in embedded views\nEmbedding application users can now share a saved Spotter conversation with other users and groups directly from the embedded interface. Recipients can view the shared conversation in a read-only view.\nConversation sharing is turned off by default in embedded views. To enable it, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object.\n\nInterface customization settings::\nThe SDK also provides the following controls for conversation sharing:\n\n* `SpotterShareConversationConfig` +\nIncludes object properties for enabling conversation sharing, label and text overrides for the share button, share modal, recipient picker, and the read-only shared view. For more information, see xref:customize-spotter-sharing.adoc[Customize conversation sharing experience].\n* `sharedConversationId` +\nAllows passing conversation ID to the SpotterEmbed when the sharing link is generated for the recipient users in the embedded app. For more information, see xref:customize-spotter-sharing.adoc#_customizing_conversation_sharing_link[Conversation sharing link]\n\nNew action IDs::\n* `Action.SpotterShareConversationButtonHeader` for **Share** button in the Spotter conversation header.\n* `Action.SpotterShareConversationMenuItemSidebar` for **Share** menu action in the chat history panel in the sidebar.\n* `Action.SpotterShareIncludeNewMessagesCheckbox` for the `include new messages since last shared version` checkbox in the share modal.\n* `SpotterSharedCon + +... [truncated, 109,668 chars total] \ No newline at end of file From e5235265141c6d1e75709fb35cb6d3516fe7993e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:43:14 +0530 Subject: [PATCH 033/169] docs: add SDK v1.54.0 November 2026 changelog entry SCAL-326037, SCAL-331936, SCAL-280403 --- modules/ROOT/pages/api-changelog.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index bbf2ed552..08eef67cc 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,8 +8,8 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs { "path": "modules/ROOT/pages/api-changelog.adoc", "name": "api-changelog.adoc", - "size": 106492, - "content": "= Visual Embed SDK changelog\n:toc: true\n:toclevels: 2\n\n:page-title: Visual Embed SDK changelog\n:page-pageid: embed-sdk-changelog\n:page-description: Changelog for the Visual Embed SDK\n\nThis 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].\n\n== Version 1.54.0, November 2026 + "size": 9616, + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/api-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/api-changelog.adoc\",\n \"name\": \"api-changelog.adoc\",\n \"size\": 106492,\n \"content\": \"= Visual Embed SDK changelog\\n:toc: true\\n:toclevels: 2\\n\\n:page-title: Visual Embed SDK changelog\\n:page-pageid: embed-sdk-changelog\\n:page-description: Changelog for the Visual Embed SDK\\n\\nThis 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].\\n\\n== Version 1.54.0, November 2026\n\n [width=\"100%\", cols=\"1,4\"]\n |====\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== SpotterX embed support\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\n\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Host-controlled tooltip rendering\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\n\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\n\n |====\n\n == Version 1.54.0, November 2026 [width="100%", cols="1,4"] |==== @@ -37,6 +37,6 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs |==== - == Version 1.53.0, October 2026\n\n[width=\"100%\", cols=\"1,4\"]\n|====\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Spotter Analyst embed\nYou can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`.\nFor more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst].\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Spotter embedding\n\n`spotterChatPinConfig`::\nYou can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations].\n\n`starterPrompts`::\nYou can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills].\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Liveboards in embedded view\nThe SDK includes the following enhancements for the Liveboards in your embedded app.\n\n* `isScopedLiveboardFilteringEnabled` +\nEnables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`.\n* `openSpotterOnLiveboardByDefault` +\nOpens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`.\n* `starterPrompts.liveboard` +\nStarter prompts for the Spotter chat panel on a Liveboard.\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Action IDs for embedded Spotter and Liveboard interfaces\n\nThe following `Action` enum members are added in this release:\n\n* `Action.SpotterChatPin` +\nControls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu.\n* `Action.SpotterAnalystList` +\nControls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface.\n* `Action.SpotterDefaultAnalyst` +\nControls the visibility and enabled state of the default Spotter entry in the Analyst interface.\n* `Action.SpotterOnLiveboard` +\nControls the visibility and enabled state of the *Spotter* button in the Liveboard header.\n* `Action.AllLiveboardFilters` +\nShows, hides, or greys out all filter surfaces on a Liveboard: filter chips, parameter chips, and cross-filter chips at the Liveboard, tab, and group levels. Parameter and cross-filter chips can only be hidden.\n* `Action.EditInputTable` +\nControls the *Edit input table* action, which lets users edit an input table used by an Answer directly from the Liveboard.\n* `Action.QuickSearchPill` +\nControls the *Basic Search* starter prompt pill in the Spotter interface.\n* `Action.DeepAnalysisPill` +\nControls the *Deep Analysis* starter prompt pill in the Spotter interface.\n* `Action.DataLiteracyPill` +\nControls the *Data Literacy* starter prompt pill in the Spotter interface.\n\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Events\n\nEmbed events::\n* `EmbedEvent.SpotterConversationPinned` +\nEmitted when a user pins a Spotter conversation. The event payload includes the `conversationId` and `pinnedAt` values.\n* `EmbedEvent.SpotterConversationUnpinned` +\nEmitted when a user unpins a Spotter conversation. The event payload includes the `conversationId` and `unpinnedAt` values.\n\nHost events::\n* `HostEvent.PinSpotterConversation` +\nPins a saved Spotter conversation. Accepts `{ conversationId }`.\n* `HostEvent.UnpinSpotterConversation` +\nUnpins a previously pinned Spotter conversation. Accepts `{ conversationId }`.\n* `HostEvent.GetGroups` +\nReturns filter and parameter group details for the current Liveboard. The response includes `orderedGroupIds`, `numberOfGroups`, and `Groups`.\n* `HostEvent.OpenParameter` +\nOpens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group.\n\nThe pin and unpin events require `spotterChatPinConfig.enabled: true` and `enablePastConversationsSidebar: true` in the embed configuration. The host events also require chat history to be enabled on your ThoughtSpot instance.\n\nUpdated events::\nThe following existing events now include or accept an optional `applicability` attribute, which scopes filters and parameters to a Liveboard tab or group:\n\n* `EmbedEvent.FilterChanged`\n* `EmbedEvent.ParameterChanged`\n* `HostEvent.OpenFilter`\n* `HostEvent.GetFilters`\n* `HostEvent.UpdateFilters`\n* `HostEvent.GetParameters`\n* `HostEvent.UpdateParameters`\n\nDeprecated events::\n* `HostEvent.UpdatePersonalizedView` is deprecated. Use `HostEvent.SelectPersonalizedView` instead. `HostEvent.SelectPersonalizedView` additionally accepts an optional `viewName` to select a view by name, resets to the original view when the payload is empty, and reports an error when the named view isn't found.\n|====\n\n== Version 1.52.x, September 2026\n\n[width=\"100%\" cols=\"1,4\"]\n|====\n|[tag greenBackground]#NEW#\na|\n[discrete]\n===== Spotter conversation sharing in embedded views\nEmbedding application users can now share a saved Spotter conversation with other users and groups directly from the embedded interface. Recipients can view the shared conversation in a read-only view.\nConversation sharing is turned off by default in embedded views. To enable it, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object.\n\nInterface customization settings::\nThe SDK also provides the following controls for conversation sharing:\n\n* `SpotterShareConversationConfig` +\nIncludes object properties for enabling conversation sharing, label and text overrides for the share button, share modal, recipient picker, and the read-only shared view. For more information, see xref:customize-spotter-sharing.adoc[Customize conversation sharing experience].\n* `sharedConversationId` +\nAllows passing conversation ID to the SpotterEmbed when the sharing link is generated for the recipient users in the embedded app. For more information, see xref:customize-spotter-sharing.adoc#_customizing_conversation_sharing_link[Conversation sharing link]\n\nNew action IDs::\n* `Action.SpotterShareConversationButtonHeader` for **Share** button in the Spotter conversation header.\n* `Action.SpotterShareConversationMenuItemSidebar` for **Share** menu action in the chat history panel in the sidebar.\n* `Action.SpotterShareIncludeNewMessagesCheckbox` for the `include new messages since last shared version` checkbox in the share modal.\n* `SpotterSharedCon + == Version 1.53.0, October 2026\\n\\n[width=\\\"100%\\\", cols=\\\"1,4\\\"]\\n|====\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Spotter Analyst embed\\nYou can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`.\\nFor more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst].\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Spotter embedding\\n\\n`spotterChatPinConfig`::\\nYou can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations].\\n\\n`starterPrompts`::\\nYou can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills].\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Liveboards in embedded view\\nThe SDK includes the following enhancements for the Liveboards in your embedded app.\\n\\n* `isScopedLiveboardFilteringEnabled` +\\nEnables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`.\\n* `openSpotterOnLiveboardByDefault` +\\nOpens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`.\\n* `starterPrompts.liveboard` +\\nStarter prompts for the Spotter chat panel on a Liveboard.\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Action IDs for embedded Spotter and Liveboard interfaces\\n\\nThe following `Action` enum members are added in this release:\\n\\n* `Action.SpotterChatPin` +\\nControls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu.\\n* `Action.SpotterAnalystList` +\\nControls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface.\\n* `Action.SpotterDefaultAnalyst` +\\nControls the visibility and enabled state of the default Spotter entry in the Analyst interface.\\n* `Action.SpotterOnLiveboard` +\\nControls the visibility and enabled state of the *Spotter* button in the Liveboard header.\\n* `Action.AllLiveboardFilters` +\\nShows, hides, or greys out all filter surfaces on a Liveboard: filter chips, parameter chips, and cross-filter chips at the Liveboard, tab, and group levels. Parameter and cross-filter chips can only be hidden.\\n* `Action.EditInputTable` +\\nControls the *Edit input table* action, which lets users edit an input table used by an Answer directly from the Liveboard.\\n* `Action.QuickSearchPill` +\\nControls the *Basic Search* starter prompt pill in the Spotter interface.\\n* `Action.DeepAnalysisPill` +\\nControls the *Deep Analysis* starter prompt pill in the Spotter interface.\\n* `Action.DataLiteracyPill` +\\nControls the *Data Literacy* starter prompt pill in the Spotter interface.\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Events\\n\\nEmbed events::\\n* `EmbedEvent.SpotterConversationPinned` +\\nEmitted when a user pins a Spotter conversation. The event payload includes the `conversationId` and `pinnedAt` values.\\n* `EmbedEvent.SpotterConversationUnpinned` +\\nEmitted when a user unpins a Spotter conversation. The event payload includes the `conversationId` and `unpinnedAt` values.\\n\\nHost events::\\n* `HostEvent.PinSpotterConversation` +\\nPins a saved Spotter conversation. Accepts `{ conversationId }`.\\n* `HostEvent.UnpinSpotterConversation` +\\nUnpins a previously pinned Spotter conversation. Accepts `{ conversationId }`.\\n* `HostEvent.GetGroups` +\\nReturns filter and parameter group details for the current Liveboard. The response includes `orderedGroupIds`, `numberOfGroups`, and `Groups`.\\n* `HostEvent.OpenParameter` +\\nOpens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group.\\n\\nThe pin and unpin events require `spotterChatPinConfig.enabled: true` and `enablePastConversationsSidebar: true` in the embed configuration. The host events also require chat history to be enabled on your ThoughtSpot instance.\\n\\nUpdated events::\\nThe following existing events now include or accept an optional `applicability` attribute, which scopes filters and param -... [truncated, 109,668 chars total] \ No newline at end of file +... [truncated, 10,529 chars total] \ No newline at end of file From 3c8e6f063c44035c4cfef84d92e011e4a9806f60 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:43:16 +0530 Subject: [PATCH 034/169] docs: add SDK v1.54.0 November 2026 changelog entry SCAL-326037, SCAL-331936, SCAL-280403 --- modules/ROOT/pages/api-changelog.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 08eef67cc..97f7db8c4 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,8 +8,8 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs { "path": "modules/ROOT/pages/api-changelog.adoc", "name": "api-changelog.adoc", - "size": 9616, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/api-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/api-changelog.adoc\",\n \"name\": \"api-changelog.adoc\",\n \"size\": 106492,\n \"content\": \"= Visual Embed SDK changelog\\n:toc: true\\n:toclevels: 2\\n\\n:page-title: Visual Embed SDK changelog\\n:page-pageid: embed-sdk-changelog\\n:page-description: Changelog for the Visual Embed SDK\\n\\nThis 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].\\n\\n== Version 1.54.0, November 2026\n\n [width=\"100%\", cols=\"1,4\"]\n |====\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== SpotterX embed support\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\n\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Host-controlled tooltip rendering\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\n\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\n\n |====\n\n == Version 1.54.0, November 2026 + "size": 9615, + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/api-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/api-changelog.adoc\",\n \"name\": \"api-changelog.adoc\",\n \"size\": 9616,\n \"content\": \"--- CITABLE SOURCE ---\\nFile: modules/ROOT/pages/api-changelog.adoc\\nBranch: docs/scal-26-11-0-cl-doc-updates\\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\\n---\\n\\n{\\n \\\"path\\\": \\\"modules/ROOT/pages/api-changelog.adoc\\\",\\n \\\"name\\\": \\\"api-changelog.adoc\\\",\\n \\\"size\\\": 106492,\\n \\\"content\\\": \\\"= Visual Embed SDK changelog\\\\n:toc: true\\\\n:toclevels: 2\\\\n\\\\n:page-title: Visual Embed SDK changelog\\\\n:page-pageid: embed-sdk-changelog\\\\n:page-description: Changelog for the Visual Embed SDK\\\\n\\\\nThis 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].\\\\n\\\\n== Version 1.54.0, November 2026\\n\\n [width=\\\"100%\\\", cols=\\\"1,4\\\"]\\n |====\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== SpotterX embed support\\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\\n\\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Host-controlled tooltip rendering\\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\\n\\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\\n\\n |====\\n\\n == Version 1.54.0, November 2026\n\n [width=\"100%\", cols=\"1,4\"]\n |====\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== SpotterX embed support\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\n\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Host-controlled tooltip rendering\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\n\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\n\n |====\n\n == Version 1.54.0, November 2026 [width="100%", cols="1,4"] |==== @@ -37,6 +37,6 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs |==== - == Version 1.53.0, October 2026\\n\\n[width=\\\"100%\\\", cols=\\\"1,4\\\"]\\n|====\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Spotter Analyst embed\\nYou can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`.\\nFor more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst].\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Spotter embedding\\n\\n`spotterChatPinConfig`::\\nYou can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations].\\n\\n`starterPrompts`::\\nYou can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills].\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Liveboards in embedded view\\nThe SDK includes the following enhancements for the Liveboards in your embedded app.\\n\\n* `isScopedLiveboardFilteringEnabled` +\\nEnables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`.\\n* `openSpotterOnLiveboardByDefault` +\\nOpens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`.\\n* `starterPrompts.liveboard` +\\nStarter prompts for the Spotter chat panel on a Liveboard.\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Action IDs for embedded Spotter and Liveboard interfaces\\n\\nThe following `Action` enum members are added in this release:\\n\\n* `Action.SpotterChatPin` +\\nControls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu.\\n* `Action.SpotterAnalystList` +\\nControls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface.\\n* `Action.SpotterDefaultAnalyst` +\\nControls the visibility and enabled state of the default Spotter entry in the Analyst interface.\\n* `Action.SpotterOnLiveboard` +\\nControls the visibility and enabled state of the *Spotter* button in the Liveboard header.\\n* `Action.AllLiveboardFilters` +\\nShows, hides, or greys out all filter surfaces on a Liveboard: filter chips, parameter chips, and cross-filter chips at the Liveboard, tab, and group levels. Parameter and cross-filter chips can only be hidden.\\n* `Action.EditInputTable` +\\nControls the *Edit input table* action, which lets users edit an input table used by an Answer directly from the Liveboard.\\n* `Action.QuickSearchPill` +\\nControls the *Basic Search* starter prompt pill in the Spotter interface.\\n* `Action.DeepAnalysisPill` +\\nControls the *Deep Analysis* starter prompt pill in the Spotter interface.\\n* `Action.DataLiteracyPill` +\\nControls the *Data Literacy* starter prompt pill in the Spotter interface.\\n\\n|[tag greenBackground]#NEW#\\na|\\n[discrete]\\n===== Events\\n\\nEmbed events::\\n* `EmbedEvent.SpotterConversationPinned` +\\nEmitted when a user pins a Spotter conversation. The event payload includes the `conversationId` and `pinnedAt` values.\\n* `EmbedEvent.SpotterConversationUnpinned` +\\nEmitted when a user unpins a Spotter conversation. The event payload includes the `conversationId` and `unpinnedAt` values.\\n\\nHost events::\\n* `HostEvent.PinSpotterConversation` +\\nPins a saved Spotter conversation. Accepts `{ conversationId }`.\\n* `HostEvent.UnpinSpotterConversation` +\\nUnpins a previously pinned Spotter conversation. Accepts `{ conversationId }`.\\n* `HostEvent.GetGroups` +\\nReturns filter and parameter group details for the current Liveboard. The response includes `orderedGroupIds`, `numberOfGroups`, and `Groups`.\\n* `HostEvent.OpenParameter` +\\nOpens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group.\\n\\nThe pin and unpin events require `spotterChatPinConfig.enabled: true` and `enablePastConversationsSidebar: true` in the embed configuration. The host events also require chat history to be enabled on your ThoughtSpot instance.\\n\\nUpdated events::\\nThe following existing events now include or accept an optional `applicability` attribute, which scopes filters and param + == Version 1.53.0, October 2026\\\\n\\\\n[width=\\\\\\\"100%\\\\\\\", cols=\\\\\\\"1,4\\\\\\\"]\\\\n|====\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Spotter Analyst embed\\\\nYou can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`.\\\\nFor more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst].\\\\n\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Spotter embedding\\\\n\\\\n`spotterChatPinConfig`::\\\\nYou can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations].\\\\n\\\\n`starterPrompts`::\\\\nYou can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills].\\\\n\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Liveboards in embedded view\\\\nThe SDK includes the following enhancements for the Liveboards in your embedded app.\\\\n\\\\n* `isScopedLiveboardFilteringEnabled` +\\\\nEnables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`.\\\\n* `openSpotterOnLiveboardByDefault` +\\\\nOpens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`.\\\\n* `starterPrompts.liveboard` +\\\\nStarter prompts for the Spotter chat panel on a Liveboard.\\\\n\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Action IDs for embedded Spotter and Liveboard interfaces\\\\n\\\\nThe following `Action` enum members are added in this release:\\\\n\\\\n* `Action.SpotterChatPin` +\\\\nControls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu.\\\\n* `Action.SpotterAnalystList` +\\\\nControls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface.\\\\n* `Action.SpotterDefaultAnalyst` +\\\\nControls th -... [truncated, 10,529 chars total] \ No newline at end of file +... [truncated, 10,659 chars total] \ No newline at end of file From 0d8456e3e13ee0fb869b97463b048976f17a3cc3 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:43:17 +0530 Subject: [PATCH 035/169] docs: add SDK v1.54.0 November 2026 changelog entry SCAL-326037, SCAL-331936, SCAL-280403 --- modules/ROOT/pages/api-changelog.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 97f7db8c4..2d30d769c 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -9,7 +9,7 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs "path": "modules/ROOT/pages/api-changelog.adoc", "name": "api-changelog.adoc", "size": 9615, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/api-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/api-changelog.adoc\",\n \"name\": \"api-changelog.adoc\",\n \"size\": 9616,\n \"content\": \"--- CITABLE SOURCE ---\\nFile: modules/ROOT/pages/api-changelog.adoc\\nBranch: docs/scal-26-11-0-cl-doc-updates\\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\\n---\\n\\n{\\n \\\"path\\\": \\\"modules/ROOT/pages/api-changelog.adoc\\\",\\n \\\"name\\\": \\\"api-changelog.adoc\\\",\\n \\\"size\\\": 106492,\\n \\\"content\\\": \\\"= Visual Embed SDK changelog\\\\n:toc: true\\\\n:toclevels: 2\\\\n\\\\n:page-title: Visual Embed SDK changelog\\\\n:page-pageid: embed-sdk-changelog\\\\n:page-description: Changelog for the Visual Embed SDK\\\\n\\\\nThis 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].\\\\n\\\\n== Version 1.54.0, November 2026\\n\\n [width=\\\"100%\\\", cols=\\\"1,4\\\"]\\n |====\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== SpotterX embed support\\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\\n\\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Host-controlled tooltip rendering\\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\\n\\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\\n\\n |====\\n\\n == Version 1.54.0, November 2026\n\n [width=\"100%\", cols=\"1,4\"]\n |====\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== SpotterX embed support\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\n\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Host-controlled tooltip rendering\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\n\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\n\n |====\n\n == Version 1.54.0, November 2026 + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/api-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/api-changelog.adoc\",\n \"name\": \"api-changelog.adoc\",\n \"size\": 9615,\n \"content\": \"--- CITABLE SOURCE ---\\nFile: modules/ROOT/pages/api-changelog.adoc\\nBranch: docs/scal-26-11-0-cl-doc-updates\\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\\n---\\n\\n{\\n \\\"path\\\": \\\"modules/ROOT/pages/api-changelog.adoc\\\",\\n \\\"name\\\": \\\"api-changelog.adoc\\\",\\n \\\"size\\\": 9616,\\n \\\"content\\\": \\\"--- CITABLE SOURCE ---\\\\nFile: modules/ROOT/pages/api-changelog.adoc\\\\nBranch: docs/scal-26-11-0-cl-doc-updates\\\\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\\\\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\\\\n---\\\\n\\\\n{\\\\n \\\\\\\"path\\\\\\\": \\\\\\\"modules/ROOT/pages/api-changelog.adoc\\\\\\\",\\\\n \\\\\\\"name\\\\\\\": \\\\\\\"api-changelog.adoc\\\\\\\",\\\\n \\\\\\\"size\\\\\\\": 106492,\\\\n \\\\\\\"content\\\\\\\": \\\\\\\"= Visual Embed SDK changelog\\\\\\\\n:toc: true\\\\\\\\n:toclevels: 2\\\\\\\\n\\\\\\\\n:page-title: Visual Embed SDK changelog\\\\\\\\n:page-pageid: embed-sdk-changelog\\\\\\\\n:page-description: Changelog for the Visual Embed SDK\\\\\\\\n\\\\\\\\nThis 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].\\\\\\\\n\\\\\\\\n== Version 1.54.0, November 2026\\\\n\\\\n [width=\\\\\\\"100%\\\\\\\", cols=\\\\\\\"1,4\\\\\\\"]\\\\n |====\\\\n |[tag greenBackground]#NEW#\\\\n a|\\\\n [discrete]\\\\n ===== SpotterX embed support\\\\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\\\\n\\\\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\\\\n\\\\n |[tag greenBackground]#NEW#\\\\n a|\\\\n [discrete]\\\\n ===== Host-controlled tooltip rendering\\\\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\\\\n\\\\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\\\\n\\\\n |[tag greenBackground]#NEW#\\\\n a|\\\\n [discrete]\\\\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\\\\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\\\\n\\\\n |====\\\\n\\\\n == Version 1.54.0, November 2026\\n\\n [width=\\\"100%\\\", cols=\\\"1,4\\\"]\\n |====\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== SpotterX embed support\\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\\n\\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Host-controlled tooltip rendering\\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\\n\\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\\n\\n |====\\n\\n == Version 1.54.0, November 2026\n\n [width=\"100%\", cols=\"1,4\"]\n |====\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== SpotterX embed support\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\n\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Host-controlled tooltip rendering\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\n\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\n\n |====\n\n == Version 1.54.0, November 2026 [width="100%", cols="1,4"] |==== @@ -37,6 +37,6 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs |==== - == Version 1.53.0, October 2026\\\\n\\\\n[width=\\\\\\\"100%\\\\\\\", cols=\\\\\\\"1,4\\\\\\\"]\\\\n|====\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Spotter Analyst embed\\\\nYou can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`.\\\\nFor more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst].\\\\n\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Spotter embedding\\\\n\\\\n`spotterChatPinConfig`::\\\\nYou can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations].\\\\n\\\\n`starterPrompts`::\\\\nYou can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills].\\\\n\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Liveboards in embedded view\\\\nThe SDK includes the following enhancements for the Liveboards in your embedded app.\\\\n\\\\n* `isScopedLiveboardFilteringEnabled` +\\\\nEnables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`.\\\\n* `openSpotterOnLiveboardByDefault` +\\\\nOpens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`.\\\\n* `starterPrompts.liveboard` +\\\\nStarter prompts for the Spotter chat panel on a Liveboard.\\\\n\\\\n|[tag greenBackground]#NEW#\\\\na|\\\\n[discrete]\\\\n===== Action IDs for embedded Spotter and Liveboard interfaces\\\\n\\\\nThe following `Action` enum members are added in this release:\\\\n\\\\n* `Action.SpotterChatPin` +\\\\nControls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu.\\\\n* `Action.SpotterAnalystList` +\\\\nControls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface.\\\\n* `Action.SpotterDefaultAnalyst` +\\\\nControls th + == Version 1.53.0, October 2026\\\\\\\\n\\\\\\\\n[width=\\\\\\\\\\\\\\\"100%\\\\\\\\\\\\\\\", cols=\\\\\\\\\\\\\\\"1,4\\\\\\\\\\\\\\\"]\\\\\\\\n|====\\\\\\\\n|[tag greenBackground]#NEW#\\\\\\\\na|\\\\\\\\n[discrete]\\\\\\\\n===== Spotter Analyst embed\\\\\\\\nYou can now e -... [truncated, 10,659 chars total] \ No newline at end of file +... [truncated, 10,859 chars total] \ No newline at end of file From 5a1108dbfec66f5ef6fe5b934dda8cfc55b73004 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:44:19 +0530 Subject: [PATCH 036/169] docs: add Input Tables and Link Customization API reference entries SCAL-332820, SCAL-337682 --- modules/ROOT/pages/rest-api-v2-reference.adoc | 1477 +---------------- 1 file changed, 68 insertions(+), 1409 deletions(-) diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index c400ff740..ed7e308a3 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -1,1411 +1,70 @@ -= REST API v2.0 Reference -:toc: true - -:page-title: REST API Reference Guide -:page-pageid: rest-apiv2-reference -:page-description: REST API Reference - -This API Reference page lists the REST API v2.0 endpoints and provides basic information about the resource URLs and supported operations. If you want to try out these APIs, view detailed documentation, and download code samples, visit the +++REST API v2.0 Playground+++. - -[NOTE] -==== -Access to ThoughtSpot data is controlled based on xref:api-user-management.adoc#group-privileges[user privileges] and xref:configure-user-access.adoc#_object_level_permissions[object-level permissions]. Some operations are available to all users and may require at least view access to the metadata object. ThoughtSpot users are assigned access privileges based on the group to which they belong. Additionally, object owners can control access to a metadata object using `MODIFY` (*Can edit*), `READ_ONLY` (*Can view*), or `NO_ACCESS` permission when sharing an object with other users and groups. -==== - -== AI - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link - -a|`POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a conversation session with ThoughtSpot's Spotter agent. -|ThoughtSpot Cloud: __10.13.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/conversation/create` + -Creates a conversation session with ThoughtSpot Spotter -|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/data-source-suggestions` + -Gets data source recommendations for a given query. -|ThoughtSpot Cloud: __26.2.0.cl or later__ + -|+++Try it out+++ - -a|`POST /api/rest/2.0/ai/relevant-questions/` + -Breaks down a user submitted query into relevant questions -|ThoughtSpot Cloud: __10.13.0.cl or later__ + -|+++Try it out+++ - -a| `POST /api/rest/2.0/ai/agent/converse/sse` + -Allows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. -|ThoughtSpot Cloud: __10.13.0.cl or later__ -| +++Try it out+++ - -a| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + -Generates responses to user queries and follow-up questions sent in the specified conversation session. -|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/answer/create` + -Generates an Answer for a Natural Language Search query. -|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + -Allows sending a query to an ongoing conversation session with Spotter agent and generate response. -|ThoughtSpot Cloud: __10.15.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + -Stops an in-progress Spotter agent response for a given conversation session. -|ThoughtSpot Cloud: __26.6.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/instructions/set` + -Sets data model instructions. -|ThoughtSpot Cloud: __10.15.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/instructions/get` + -Retrieves data model instructions. -|ThoughtSpot Cloud: __10.15.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`PUT /api/rest/2.0/ai/agent/instructions/set` + -Sets custom instructions for the Spotter agent. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`GET /api/rest/2.0/ai/agent/instructions/get` + -Retrieves the custom instructions currently configured for the Spotter agent. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`GET /api/rest/2.0/ai/agent/conversations` + -Retrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}` + -Retrieves the full message history of a single saved Spotter agent conversation, including user prompts and agent response items for each turn. Requires `CAN_USE_SPOTTER` privilege. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + -Updates the display title of a saved Spotter agent conversation. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + -Permanently deletes a saved Spotter agent conversation and all its associated messages. This operation is irreversible. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation. -|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 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 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+++ -|===== --- +--- CITABLE SOURCE --- +File: modules/ROOT/pages/rest-api-v2-reference.adoc +Branch: docs/scal-26-11-0-cl-doc-updates +URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc +To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc#L{line_number} +--- + +{ + "path": "modules/ROOT/pages/rest-api-v2-reference.adoc", + "name": "rest-api-v2-reference.adoc", + "size": 68802, + "content": "= REST API v2.0 Reference\n:toc: true\n\n:page-title: REST API Reference Guide\n:page-pageid: rest-apiv2-reference\n:page-description: REST API Reference\n\nThis API Reference page lists the REST API v2.0 endpoints and provides basic information about the resource URLs and supported operations. If you want to try out these APIs, view detailed documentation, and download code samples, visit the +++REST API v2.0 Playground+++.\n\n[NOTE]\n====\nAccess to ThoughtSpot data is controlled based on xref:api-user-management.adoc#group-privileges[user privileges] and xref:configure-user-access.adoc#_object_level_permissions[object-level permissions]. Some operations are available to all users and may require at least view access to the metadata object. ThoughtSpot users are assigned access privileges based on the group to which they belong. Additionally, object owners can control access to a metadata object using `MODIFY` (*Can edit*), `READ_ONLY` (*Can view*), or `NO_ACCESS` permission when sharing an object with other users and groups.\n====\n\n== AI\n\n[div boxAuto]\n--\n[width=\"100%\" cols=\"6,6,3\"]\n[options='header']\n|=====\n|API endpoint| Release version | Playground link\n\na|`POST /api/rest/2.0/ai/agent/conversation/create` +\nCreates a conversation session with ThoughtSpot's Spotter agent.\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/conversation/create` +\nCreates a conversation session with ThoughtSpot Spotter\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/data-source-suggestions` +\nGets data source recommendations for a given query.\n|ThoughtSpot Cloud: __26.2.0.cl or later__ +\n|+++Try it out+++\n\na|`POST /api/rest/2.0/ai/relevant-questions/` +\nBreaks down a user submitted query into relevant questions\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\n|+++Try it out+++\n\na| `POST /api/rest/2.0/ai/agent/converse/sse` +\nAllows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details.\n|ThoughtSpot Cloud: __10.13.0.cl or later__\n| +++Try it out+++\n\na| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +\nGenerates responses to user queries and follow-up questions sent in the specified conversation session.\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/answer/create` +\nGenerates an Answer for a Natural Language Search query.\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` +\nAllows sending a query to an ongoing conversation session with Spotter agent and generate response.\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` +\nStops an in-progress Spotter agent response for a given conversation session.\n|ThoughtSpot Cloud: __26.6.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/instructions/set` +\nSets data model instructions.\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/instructions/get` +\nRetrieves data model instructions.\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`PUT /api/rest/2.0/ai/agent/instructions/set` +\nSets custom instructions for the Spotter agent.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`GET /api/rest/2.0/ai/agent/instructions/get` +\nRetrieves the custom instructions currently configured for the Spotter agent.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`GET /api/rest/2.0/ai/agent/conversations` +\nRetrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}` +\nRetrieves the full message history of a single saved Spotter agent conversation, including user prompts and agent response items for each turn. Requires `CAN_USE_SPOTTER` privilege.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` +\nUpdates the display title of a saved Spotter agent conversation. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not ava + +... [truncated, 71,771 chars total] + [#inputTables] + == Input Tables + [div tableContainer] + -- + [width="100%", cols="2,1,4"] + [options='header'] + |=== + |API endpoint | HTTP verb | Description + + |`/api/rest/2.0/input/tables/create` + |POST + |Creates an input table and links it to a ThoughtSpot model. Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. + + |`/api/rest/2.0/input/tables/\{input_table_identifier}/update` + |POST + |Updates the name, description, or both of an input table. Requires `MODIFY` permission on the input table. + + |`/api/rest/2.0/input/tables/\{input_table_identifier}/delete` + |POST + |Deletes an input table. Requires `MODIFY` permission on the table's parent model. + + |`/api/rest/2.0/input/tables/columns/create` + |POST + |Adds a column to an existing input table. Requires `MODIFY` permission on the input table. + + |`/api/rest/2.0/input/tables/columns/\{column_identifier}/delete` + |POST + |Deletes a column from an input table. Requires `MODIFY` permission on the input table. + |=== + -- + + For more information, see xref:input-table-api.adoc[Input Table APIs]. -== Authentication - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`GET /api/rest/2.0/auth/session/user` + -Gets session information for the currently logged-in user. + - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software:__ 9.0.1.sw or later __ a| -+++Try it out+++ -|`GET /api/rest/2.0/auth/session/token` + -Generates a new bearer token from an existing authenticated session. - -|ThoughtSpot Cloud: __9.4.0.cl or later__ + -ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ - -| -`POST /api/rest/2.0/auth/session/login` + -Creates a login session for a ThoughtSpot user. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a| `POST /api/rest/2.0/auth/token/object` + - -Gets an authentication token that grants access only to the metadata object specified in the API request. -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/auth/token/full` + -Gets an authentication token from ThoughtSpot that grants access to a full application session. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/auth/session/logout` + -Logs out the currently logged-in user. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ -a|`POST /api/rest/2.0/auth/token/revoke` + -Revokes authentication token granted for a user. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ - -a| `POST /api/rest/2.0/auth/token/validate` + -Validates the authentication token specified in the API request. a| ThoughtSpot Cloud: __9.12.0.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out +++ - -a| `POST /api/rest/2.0/auth/token/custom` + -Generates an authentication token with pre-defined RLS rules and filter attributes for a user. a| ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out +++ - -a| `POST /api/rest/2.0/auth/configure` + -Enables or disables authentication. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + -a| +++Try it out +++ - -a| `POST /api/rest/2.0/auth/search` + -Retrieves the authentication configuration for the specified auth type. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + -a| +++Try it out +++ - -|===== --- - -== Collections -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/collections/create` + - -Creates a new Collection. - -|ThoughtSpot Cloud: __26.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ + a| +++Try it out+++ - -a|`POST /api/rest/2.0/collections/search` - -Gets a list of Collections available in ThoughtSpot. - -|ThoughtSpot Cloud: __26.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ + a| +++Try it out+++ - -a|`POST /api/rest/2.0/collections/{collection_identifier}/update` + - -Updates an existing Collection. - -|ThoughtSpot Cloud: __26.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ + a| +++Try it out +++ - -a|`POST /api/rest/2.0/collections/delete` + - -Deletes one or more Collections. - -|ThoughtSpot Cloud: __26.4.0.cl or later__ + -ThoughtSpot Software: __Not available__ + a| +++Try it out +++ - -|===== --- - -== Connections - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/connection/search` + - -Gets connection objects from ThoughtSpot. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/connection/create` - -Creates a connection to the data warehouse specified in the API request. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/connection/update` [tag redBackground]#DEPRECATED# + - -Updates a connection object. - -__Note: This API endpoint is deprecated in ThoughtSpot 10.4.0.cl and later versions. To update a connection, use `POST /api/rest/2.0/connections/{connection_identifier}/update`. __ - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/connections/{connection_identifier}/update` + -Updates a connection object. -a|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/connection/delete` [tag redBackground]#DEPRECATED# + -Deletes a connection object. - -__Note: This API endpoint is deprecated in ThoughtSpot 10.4.0.cl and later versions. To delete a connection, use `api/rest/2.0/connections/delete/{connection_identifier}`. __ - -a|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/connections/{connection_identifier}/delete` + -Deletes a connection -a|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ a| -+++Try it out +++ - -a| -`POST /api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + -Validates the connection metadata differences between Cloud Data Warehouse and ThoughtSpot. -|ThoughtSpot Cloud: __9.10.5.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ -a|+++Try it out +++ -a| -`POST /api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + -Downloads connection metadata differences between Cloud Data Warehouse and ThoughtSpot. -|ThoughtSpot Cloud: __9.10.5.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ -a| -+++Try it out +++ - -a| `POST /api/rest/2.0/connections/{connection_identifier}/status` + -Deactivates or activates a connection. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + -a| +++Try it out +++ - -|===== --- -== Connection Configuration - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/connection-configurations/create` - -Creates a connection configuration to the connection object specified in the API request. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ + a| +++Try it out+++ - -a|`POST /api/rest/2.0/connection-configurations/search` + - -Gets the connection configuration for the specified connection object. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ + a| +++Try it out+++ - - -a|`POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + - -Updates the connection configuration object. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ + a| -+++Try it out +++ - - -a| `POST /api/rest/2.0/connection-configurations/delete` + -Deletes the connection configuration object. -a|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ + a| -+++Try it out +++ -|===== --- - -== Custom actions - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/customization/custom-actions/search` + - -Gets custom action objects. - -|ThoughtSpot Cloud: __9.6.0.cl or later__ + -ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/custom-actions` - -Creates a custom action and assigns it to a given metadata object. - -|ThoughtSpot Cloud: __9.6.0.cl or later__ + -ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + - -Updates the properties of a custom action object. - -|ThoughtSpot Cloud: __9.6.0.cl or later__ + -ThoughtSpot Software: __9.8.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + - -Deletes a custom action. - -|ThoughtSpot Cloud: __9.6.0.cl or later__ + -ThoughtSpot Software: __9.8.0.sw or later__ a| -+++Try it out +++ -|===== --- - -== Custom calendars - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a| `POST /api/rest/2.0/calendars/create` + -Creates a custom calendar. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ -a| +++Try it out+++ -| `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + -Deletes a custom calendar. -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ -a| +++Try it out+++ -| `POST /api/rest/2.0/calendars/generate-csv` + -Exports a custom calendar in the CSV format. -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ -a| +++Try it out+++ -|`POST /api/rest/2.0/calendars/search` + -Gets custom calendars for the connection ID specified in the API request. -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ -a| +++Try it out+++ -|`POST /api/rest/2.0/calendars/{calendar_identifier}/update` + -Updates a custom calendar. -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ -a|+++Try it out+++ -|==== --- - -== Data - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/searchdata` + - -Generates results for the search query specified in the API request. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/metadata/liveboard/data` - -Gets details of a Liveboard and its visualizations. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/metadata/answer/data` + - -Gets Answer data from ThoughtSpot. You can fetch data for saved Answers only. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ -|===== --- - -== DBT - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/dbt/dbt-connection` + - -Creates a DBT connection object in ThoughtSpot. - -|ThoughtSpot Cloud: __9.10.0.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/dbt/generate-tml` + - -Creates TML for the given data objects and imports the TML data to ThoughtSpot. - -|ThoughtSpot Cloud: __9.10.0.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/dbt/generate-sync-tml` + - -Resynchronizes the existing list of Models and Tables TML content for the specified DBT connection object and imports these to ThoughtSpot. - -|ThoughtSpot Cloud: __9.10.0.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/dbt/search` + - -Gets a list of DBT connection objects. - -|ThoughtSpot Cloud: __9.10.0.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ a| -+++Try it out +++ - - -a|`POST /api/rest/2.0/dbt/{dbt_connection_identifier}` - -Updates a DBT connection object. - -|ThoughtSpot Cloud: __9.10.0.cl or later__ + -ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out+++ -|===== --- - -== Email customization - -[earlyAccess eaBackground] - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/customization/email` + - -Creates the customized configuration for the notification emails. - -|ThoughtSpot Cloud: __10.10.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/email/delete` - -Deletes the existing customized configuration set for the notification emails. - -|ThoughtSpot Cloud: __10.10.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/email/search` + - -Searches the customized configuration set for the notification emails. - -|ThoughtSpot Cloud: __10.10.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/customization/email/update` + - -Updates an existing email customization set for the notification emails. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/customization/email/validate` + - -Validates the customized configuration set for the notification emails. - -|ThoughtSpot Cloud: __10.10.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out +++ -|===== --- - -== Groups - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/groups/search` + -Gets details of one or several Groups. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/groups/create` - -Creates a Group object. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/groups/{group_identifier}/update` + -Updates the object properties of a group. You can also use this API to add or remove users, sub-groups, and privileges. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/groups/{group_identifier}/delete` + - -Removes a group object from ThoughtSpot. - -a|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/groups/import` - -Imports group objects from external databases into ThoughtSpot. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ -|===== --- - - -== Jobs - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/jobs/history/communication-channels/search` + -Gets information about the execution and delivery status for scheduled jobs such as webhook delivery. -|ThoughtSpot Cloud: __26.4.0.cl or later__ -ThoughtSpot Software: __Not available__ - a| +++Try it out+++ -|===== --- - -== Logs - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/logs/fetch` + - -Gets security audit logs from the ThoughtSpot system. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -|===== --- - -== Localizations - -[div boxAuto] --- -[width="100%", cols="8,5,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link - -a|`POST /api/rest/2.0/localizations/manual-translation/import` + -Imports a CSV file containing custom locale-specific translations for ThoughtSpot UI strings. New entries are inserted and existing entries are updated (upsert). -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out+++ - -a|`POST /api/rest/2.0/localizations/manual-translation/export` + -Exports all manual translations for the specified org scope as a CSV file. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out+++ - -a|`POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + -Returns all manual translations for the specified locale as a JSON object. Accessible to all authenticated users. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out+++ - -a|`POST /api/rest/2.0/localizations/manual-translation/delete` + -Deletes all manual translations for the specified org scope. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out+++ -|===== --- - -== Metadata - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/metadata/worksheets/convert` + -Converts a Worksheet to a Model. |ThoughtSpot Cloud: __10.6.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ - - -a|`POST /api/rest/2.0/metadata/copyobject` + -Creates a copy of an object. |ThoughtSpot Cloud: __10.6.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ -a| +++Try it out+++ - -a|`POST /api/rest/2.0/metadata/delete` + -Removes a metadata object. -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/metadata/tml/export` - -Exports TML representation of the metadata objects from ThoughtSpot in JSON or YAML format. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - - -a|`POST /api/rest/2.0/metadata/tml/export/batch` + -Exports a complete set of TML for a user, user group, or Role object. -|ThoughtSpot Cloud: __10.1.0.cl or later__ + -ThoughtSpot Software: __10.1.0.sw or later__ -a|+++Try it out +++ - - -a|`POST /api/rest/2.0/metadata/answer/sql` + -Gets SQL query data for a saved Answer. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/metadata/tml/async/status` + -Gets status details for scheduled TML import tasks. -|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/metadata/liveboard/sql` + - -Gets SQL query data for the visualizations on a Liveboard. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - - -a| `POST /api/rest/2.0/metadata/tml/import` + - -Imports TML representation of the metadata objects into ThoughtSpot. - -a|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - - -a| `POST /api/rest/2.0/metadata/tml/async/import` + - -Schedules an asynchronous TML import task for the given objects. -|ThoughtSpot Cloud: __10.4.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/metadata/search` + -Gets details of metadata objects from ThoughtSpot. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a| `POST /api/rest/2.0/metadata/parameterize-fields` + -Allows you to parameterize multiple fields for a given metadata object. -a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/metadata/parameterize` [tag redBackground]#DEPRECATED# + -Allows you to parameterize fields in metadata objects. -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + -Allows removing parameterization from fields in metadata objects - -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/metadata/headers/update` + -Updates the header attributes of a metadata object. -|ThoughtSpot Cloud: __10.6.0.cl or later__ + -ThoughtSpot Software: __10.7.0.sw or later__ -a| -+++Try it out+++ - -a| `POST /api/rest/2.0/metadata/update-obj-id` + -Updates object IDs for given metadata objects. -|ThoughtSpot Cloud: __10.8.0.cl or later__ + -ThoughtSpot Software: __10.10.0.sw or later__ -a| -+++Try it out+++ -|===== --- - -== Orgs - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/orgs/search` + -Gets a list of Orgs configured on the ThoughtSpot system. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __Not Applicable__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/orgs/create` + -Creates an Org object. + - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __Not Applicable__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/orgs/{org_identifier}/update` + -Modifies the object properties of an Org. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __Not Applicable__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/orgs/{org_identifier}/delete` + - -Deletes an Org object from ThoughtSpot. - -a|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __Not Applicable__ a| -+++Try it out +++ -|===== --- - -== Reports - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/report/liveboard` + -Exports a Liveboard and its visualizations as a PDF or PNG file. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/report/answer` + - -Downloads a saved Answer in PDF, CSV, PNG, or XLSX format. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ -|===== --- - -[#rbacRoles] -== Roles - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/roles/search` + - -Gets Role objects from ThoughtSpot. - -|ThoughtSpot Cloud: __9.5.0.cl or later__ + -ThoughtSpot Software: __Not applicable__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/roles/create` - -Creates a Role with a defined set of privileges. - -|ThoughtSpot Cloud: __9.5.0.cl or later__ + -ThoughtSpot Software: __Not applicable__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/roles/{role_identifier}/update` + - -Updates a Role object. - -|ThoughtSpot Cloud: __9.5.0.cl or later__ + -ThoughtSpot Software: __Not applicable__ a| -+++Try it out +++ - - -a|`POST /api/rest/2.0/roles/{role_identifier}/delete` + - -Deletes a Role object. - -|ThoughtSpot Cloud: __9.5.0.cl or later__ + -ThoughtSpot Software: __Not applicable__ a| -+++Try it out +++ -|===== --- - - -== Schedules - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/schedules/create` + - -Creates a Liveboard schedule job. - -|ThoughtSpot Cloud: __9.4.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/schedules/search` + - -Gets details of the scheduled Liveboard jobs. - -|ThoughtSpot Cloud: __9.4.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/schedules/{schedule_identifier}/update` + - -Updates a Liveboard job schedule. - -|ThoughtSpot Cloud: __9.4.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - - -a|`POST /api/rest/2.0/schedules/{schedule_identifier}/delete` - -Deletes a scheduled Liveboard job. - -|ThoughtSpot Cloud: __9.4.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ - -|===== --- - -== Security - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link - -a|`POST /api/rest/2.0/security/metadata/assign` + -Assigns a new author or changes the author of a metadata object. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/security/column/rules/fetch` + -Fetches column security rules for the Tables specified in the API request. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/security/principals/fetch-permissions` + -Gets a list of objects that a user or group has access to. You can also specify the metadata type in the API request to fetch user permission details for Liveboards, Worksheets, or Answers. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a| `POST /api/rest/2.0/security/metadata/fetch-object-privileges` + -Retrieves details of object-level privileges assigned to users or groups for a specified set of data objects. - -|ThoughtSpot Cloud: __26.3.0.cl or later__ + -ThoughtSpot Software: Not available a| +++Try it out+++ - -a|`POST /api/rest/2.0/security/metadata/fetch-permissions` - -Gets access permission details for metadata objects. To get object access details for a user or group, specify the user or group identifiers. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a| `POST /api/rest/2.0/security/metadata/manage-object-privilege` + -Allows assigning object-level permissions to other users and groups and granting access to Spotter coaching information. - -|ThoughtSpot Cloud: __26.3.0.cl or later__ + -ThoughtSpot Software: Not available a| +++Try it out+++ - -| `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + -Allows publishing metadata objects to one or several Orgs on an instance. -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/security/metadata/share` + - -Allows sharing metadata objects, such as Liveboards, saved Answers, and Worksheets with another user or group in ThoughtSpot. - -a|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -| `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + -Removes published metadata objects from the Orgs specified in the API request. -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/security/column/rules/update` + -Adds or updates column security rules applied on the Table specified in the API request. - -|ThoughtSpot Cloud: __10.12.0.cl or later__ a| -+++Try it out +++ -|===== --- -== Style customization - -// SOURCE: SCAL-293070, SCAL-293071 - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link - -a|`POST /api/rest/2.0/customization/styles/search` + -Gets the current style configuration at the cluster and active Org scope. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/styles/update` + -Updates style settings such as the navigation panel color, chart color palette, logos, embedded footer text, and visualization font assignments at the cluster or Org scope. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/styles/fonts/upload` + -Uploads a custom font file to ThoughtSpot. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/styles/fonts/search` + -Gets custom fonts uploaded to the ThoughtSpot instance. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -a|`PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + -Updates the display name, weight, style, or color of an existing custom font. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/styles/fonts/delete` + -Deletes one or more custom fonts from the font library. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -a|`POST /api/rest/2.0/customization/styles/logos/export` + -Exports the current logo files as a ZIP archive. -|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ -a| +++Try it out+++ - -|===== --- - -== System - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version| Playground link -a|`Get System Information` + -Gets system information of your current logged-in cluster. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`GET /api/rest/2.0/system` + -Gets details of the current configuration running on your cluster. - - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`GET /api/rest/2.0/system/config-overrides` + -Gets details of the configuration overrides on your cluster. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/system/config-update` + - -Updates the current configuration of your instance. - -a|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/system/preferences/communication-channels/configure` + -Allows configuring communication channel preferences. -a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/system/communication-channels/validate` + -Validates a communication channel, for example, a webhook connection. -a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/system/preferences/communication-channels/search` + -Allows searching communication channel preferences. -a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/system/security-settings/configure` + -Allows configuring security settings. -a|ThoughtSpot Cloud: __26.2.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ a| +++Try it out +++ - -a|`POST /api/rest/2.0/system/security-settings/search` + -Allows fetching security settings. -a|ThoughtSpot Cloud: __26.2.0.cl or later__ + -ThoughtSpot Software: __26.3.0.sw or later__ a| +++Try it out +++ - -|===== - --- - - -== Tags - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/tags/search` + -Gets details of tag objects from ThoughtSpot. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/tags/create` + -Creates a tag object in ThoughtSpot. + - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/tags/{tag_identifier}/update` + -Modifies the object properties of a tag. + - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/tags/{tag_identifier}/delete` + - -Deletes a tag object from ThoughtSpot. - -a|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/tags/assign` + -Assigns a tag to metadata objects. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/tags/unassign` + - -Removes the tag assigned to a metadata object. - -a|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ -|===== --- - - -== Users - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a|`POST /api/rest/2.0/users/search` + -Gets details of one or several ThoughtSpot users. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/users/create` + -Creates a user. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/users/{user_identifier}/update` + -Updates the properties of a user object. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ - -a| `POST /api/rest/2.0/users/{user_identifier}/delete` + - -Deletes a user object from ThoughtSpot. - -a|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/users/import` + -Imports users from an external database to ThoughtSpot. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/users/change-password` + -Allows ThoughtSpot users to change the password of their account. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/users/reset-password` + -Resets the password of a user account. - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/users/force-logout` + -Logs out users from their current sessions. - - -|ThoughtSpot Cloud: __9.0.0.cl or later__ + -ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ -a|`POST /api/rest/2.0/users/activate` + - -Activates a deactivated user account. - -|ThoughtSpot Cloud: __9.7.0.cl or later__ + -ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out +++ - -|`POST /api/rest/2.0/users/deactivate` + -Deactivates a user account. - -|ThoughtSpot Cloud: __9.7.0.cl or later__ + -ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out +++ -|===== --- - -== Version control - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -a| `POST /api/rest/2.0/vcs/git/config/search` + -Gets Git repository connections configured on the ThoughtSpot instance. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/vcs/git/commits/search` + - -Gets Git commit history for a given metadata object. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ - -a|`POST /api/rest/2.0/vcs/git/config/create` + -Connects your ThoughtSpot instance to a Git repository. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/vcs/git/config/update` + - -Updates the Git repository settings configured for a ThoughtSpot instance. - -a|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/vcs/git/config/delete` + - -Deletes the Git repository configuration. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/vcs/git/branches/commit` - -Commits TML files to the Git branch configured on your instance. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/vcs/git/commits/{commit_id}/revert` - -Reverts to a previous commit in the Git branch. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/vcs/git/branches/validate` - -Validates the content of your source branch against the objects in your destination environment and identifies merge conflicts. - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ - -a|`POST /api/rest/2.0/vcs/git/commits/deploy` - -Deploys commits to the destination environment (`Staging` or `Production`). - -|ThoughtSpot Cloud: __9.2.0.cl or later__ + -ThoughtSpot Software: __9.5.0.sw or later__ a| -+++Try it out +++ -|===== --- - -== Variable [beta betaBackground]^Beta^ - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -| `POST /api/rest/2.0/template/variables/create` + -Allows creating a template variable. - -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/template/variables/search` + -Allows searching template variables. -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -|`POST /api/rest/2.0/template/variables/update` [tag redBackground]#DEPRECATED# + -Allows you to add, remove, or replace properties of one or several template variables. - -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| Not available in the Playground - -| `POST /api/rest/2.0/template/variables/{identifier}/update` + -Allows updating properties of a variable. - -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -| `POST /api/rest/2.0/template/variables/{identifier}/update-values` + -Allows you to assign, modify, replace, or reset variable values, and define the Org and object scope for each set of variable values. - -a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| -+++Try it out +++ - -| `POST /api/rest/2.0/template/variables/delete` + -Deletes one or more template variables. -a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| -+++Try it out +++ - -| `POST /api/rest/2.0/template/variables/update-values` [tag redBackground]#DEPRECATED# + -Allows updating properties of one or several variables. - -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ - -| `POST /api/rest/2.0/template/variables/{identifier}/delete` [tag redBackground]#DEPRECATED# + -Deletes a template variable. -a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| -+++Try it out +++ -|===== --- - -== Webhooks [beta betaBackground]^Beta^ - -[div boxAuto] --- -[width="100%" cols="6,6,3"] -[options='header'] -|===== -|API endpoint| Release version | Playground link -| `POST /api/rest/2.0/webhooks/create` + -Allows creating a webhook and configuring a destination endpoint for webhook payloads. - -a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| -+++Try it out +++ - -a| `POST /api/rest/2.0/webhooks/search` + -Retrieves webhook objects. -a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| -+++Try it out +++ - -a|`GET /api/rest/2.0/webhooks/storage-config` + -Retrieves the AWS S3 storage destination configuration for a webhook. Returns data only if the webhook has a storage destination configured. Requires `ADMINISTRATION` or `DEVELOPER` privilege. -a|ThoughtSpot Cloud: __26.7.0.cl or later__ + -ThoughtSpot Software: __Not available__ a| -+++Try it out+++ - -|`POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + -Allows you to edit properties of a webhook object. - -a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| -+++Try it out +++ - -| `POST /api/rest/2.0/webhooks/delete` + -Deletes a webhook object. -a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| -+++Try it out +++ -|===== --- + [#linkCustomization] + == Link Customization + [div tableContainer] + -- + [width="100%", cols="2,1,4"] + [options='header'] + |=== + |API endpoint | HTTP verb | Description + + |`/api/rest/2.0/customization/links/search` + |POST + |Returns the URL templates at the `CLUSTER` level or for the caller's Org. Templates define the URLs generated for shareable links, scheduled emails, and alert notifications. + + |`/api/rest/2.0/customization/links/update` + |POST + |Sets or resets URL templates. Use `REPLACE` to set a template or `RESET` to clear an Org-level override and fall back to the cluster default. + |=== + -- + + For more information, see xref:link-customization-api.adoc[Link Customization APIs]. + + \ No newline at end of file From ac63b09106fefe4b33c10e6b31dc277d8e5d86a2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:44:21 +0530 Subject: [PATCH 037/169] docs: add Input Tables and Link Customization API reference entries SCAL-332820, SCAL-337682 --- modules/ROOT/pages/rest-api-v2-reference.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index ed7e308a3..6c9bd9c61 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -8,10 +8,10 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs { "path": "modules/ROOT/pages/rest-api-v2-reference.adoc", "name": "rest-api-v2-reference.adoc", - "size": 68802, - "content": "= REST API v2.0 Reference\n:toc: true\n\n:page-title: REST API Reference Guide\n:page-pageid: rest-apiv2-reference\n:page-description: REST API Reference\n\nThis API Reference page lists the REST API v2.0 endpoints and provides basic information about the resource URLs and supported operations. If you want to try out these APIs, view detailed documentation, and download code samples, visit the +++REST API v2.0 Playground+++.\n\n[NOTE]\n====\nAccess to ThoughtSpot data is controlled based on xref:api-user-management.adoc#group-privileges[user privileges] and xref:configure-user-access.adoc#_object_level_permissions[object-level permissions]. Some operations are available to all users and may require at least view access to the metadata object. ThoughtSpot users are assigned access privileges based on the group to which they belong. Additionally, object owners can control access to a metadata object using `MODIFY` (*Can edit*), `READ_ONLY` (*Can view*), or `NO_ACCESS` permission when sharing an object with other users and groups.\n====\n\n== AI\n\n[div boxAuto]\n--\n[width=\"100%\" cols=\"6,6,3\"]\n[options='header']\n|=====\n|API endpoint| Release version | Playground link\n\na|`POST /api/rest/2.0/ai/agent/conversation/create` +\nCreates a conversation session with ThoughtSpot's Spotter agent.\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/conversation/create` +\nCreates a conversation session with ThoughtSpot Spotter\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/data-source-suggestions` +\nGets data source recommendations for a given query.\n|ThoughtSpot Cloud: __26.2.0.cl or later__ +\n|+++Try it out+++\n\na|`POST /api/rest/2.0/ai/relevant-questions/` +\nBreaks down a user submitted query into relevant questions\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\n|+++Try it out+++\n\na| `POST /api/rest/2.0/ai/agent/converse/sse` +\nAllows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details.\n|ThoughtSpot Cloud: __10.13.0.cl or later__\n| +++Try it out+++\n\na| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +\nGenerates responses to user queries and follow-up questions sent in the specified conversation session.\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/answer/create` +\nGenerates an Answer for a Natural Language Search query.\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` +\nAllows sending a query to an ongoing conversation session with Spotter agent and generate response.\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` +\nStops an in-progress Spotter agent response for a given conversation session.\n|ThoughtSpot Cloud: __26.6.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/instructions/set` +\nSets data model instructions.\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/instructions/get` +\nRetrieves data model instructions.\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`PUT /api/rest/2.0/ai/agent/instructions/set` +\nSets custom instructions for the Spotter agent.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`GET /api/rest/2.0/ai/agent/instructions/get` +\nRetrieves the custom instructions currently configured for the Spotter agent.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`GET /api/rest/2.0/ai/agent/conversations` +\nRetrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}` +\nRetrieves the full message history of a single saved Spotter agent conversation, including user prompts and agent response items for each turn. Requires `CAN_USE_SPOTTER` privilege.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not available__ a| +++Try it out+++\n\na|`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` +\nUpdates the display title of a saved Spotter agent conversation. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation.\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\nThoughtSpot Software: __Not ava + "size": 9921, + "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/rest-api-v2-reference.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/rest-api-v2-reference.adoc\",\n \"name\": \"rest-api-v2-reference.adoc\",\n \"size\": 68802,\n \"content\": \"= REST API v2.0 Reference\\n:toc: true\\n\\n:page-title: REST API Reference Guide\\n:page-pageid: rest-apiv2-reference\\n:page-description: REST API Reference\\n\\nThis API Reference page lists the REST API v2.0 endpoints and provides basic information about the resource URLs and supported operations. If you want to try out these APIs, view detailed documentation, and download code samples, visit the +++REST API v2.0 Playground+++.\\n\\n[NOTE]\\n====\\nAccess to ThoughtSpot data is controlled based on xref:api-user-management.adoc#group-privileges[user privileges] and xref:configure-user-access.adoc#_object_level_permissions[object-level permissions]. Some operations are available to all users and may require at least view access to the metadata object. ThoughtSpot users are assigned access privileges based on the group to which they belong. Additionally, object owners can control access to a metadata object using `MODIFY` (*Can edit*), `READ_ONLY` (*Can view*), or `NO_ACCESS` permission when sharing an object with other users and groups.\\n====\\n\\n== AI\\n\\n[div boxAuto]\\n--\\n[width=\\\"100%\\\" cols=\\\"6,6,3\\\"]\\n[options='header']\\n|=====\\n|API endpoint| Release version | Playground link\\n\\na|`POST /api/rest/2.0/ai/agent/conversation/create` +\\nCreates a conversation session with ThoughtSpot's Spotter agent.\\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/conversation/create` +\\nCreates a conversation session with ThoughtSpot Spotter\\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/data-source-suggestions` +\\nGets data source recommendations for a given query.\\n|ThoughtSpot Cloud: __26.2.0.cl or later__ +\\n|+++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/relevant-questions/` +\\nBreaks down a user submitted query into relevant questions\\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\\n|+++Try it out+++\\n\\na| `POST /api/rest/2.0/ai/agent/converse/sse` +\\nAllows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details.\\n|ThoughtSpot Cloud: __10.13.0.cl or later__\\n| +++Try it out+++\\n\\na| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +\\nGenerates responses to user queries and follow-up questions sent in the specified conversation session.\\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/answer/create` +\\nGenerates an Answer for a Natural Language Search query.\\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` +\\nAllows sending a query to an ongoing conversation session with Spotter agent and generate response.\\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` +\\nStops an in-progress Spotter agent response for a given conversation session.\\n|ThoughtSpot Cloud: __26.6.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/instructions/set` +\\nSets data model instructions.\\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/instructions/get` +\\nRetrieves data model instructions.\\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`PUT /api/rest/2.0/ai/agent/instructions/set` +\\nSets custom instructions for the Spotter agent.\\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`GET /api/rest/2.0/ai/agent/instructions/get` +\\nRetrieves the custom instructions currently configured for the Spotter agent.\\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`GET /api/rest/2.0/ai/agent/conversations` +\\nRetrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege.\\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`GET /a -... [truncated, 71,771 chars total] +... [truncated, 11,002 chars total] [#inputTables] == Input Tables [div tableContainer] From 27fc45302f4cb4b77b0e19db1ffb5908d907a27e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:53:38 +0530 Subject: [PATCH 038/169] docs: add Spotter Usage Data API page for 26.11.0.cl --- .../ROOT/pages/spotter-usage-data-api.adoc | 416 ++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 modules/ROOT/pages/spotter-usage-data-api.adoc diff --git a/modules/ROOT/pages/spotter-usage-data-api.adoc b/modules/ROOT/pages/spotter-usage-data-api.adoc new file mode 100644 index 000000000..2b18c8767 --- /dev/null +++ b/modules/ROOT/pages/spotter-usage-data-api.adoc @@ -0,0 +1,416 @@ += Spotter Usage Data APIs +:toc: true +:toclevels: 2 + +:page-title: Spotter Usage Data APIs +:page-pageid: spotter-usage-data-api +:page-description: Use the Spotter Usage Data APIs to manage Spotter question allowances for users, user groups, and Orgs. + +Spotter usage pools let administrators control how many Spotter questions a user, user group, or Org can ask. Each pool tracks a question allowance, a warning threshold, and how many questions have been consumed. + +The Spotter Usage Data REST API v2.0 endpoints allow you to create, retrieve, update, and delete usage pools programmatically. Use these APIs to provision limits for new users, monitor consumption, raise or lower limits, or reset usage at the start of a billing period. + +[NOTE] +==== +[.version-badge.new]#Beta# + +The Spotter Usage Data APIs are in Beta in ThoughtSpot Cloud 26.11.0.cl. Breaking changes may be introduced before the endpoints are made Generally Available. +==== + +== Concepts + +=== Usage pools + +A *usage pool* is a Spotter question allowance assigned to an entity — a user, a user group, or an Org. Each pool tracks: + +* `usage` — questions consumed from the pool. +* `warning_limit` — usage level at which users start seeing a warning. Optional. +* `limit` — maximum questions the pool allows. Optional; when absent the pool is unlimited. + +=== Metering scope + +A cluster meters Spotter usage at exactly one scope: per user, per user group, or per Org. The first pool created on the cluster sets the scope. Every pool created after that must use the same `entity_type`. To switch scope, delete all existing pools first using the <> endpoint. + +=== How users draw from pools + +A user draws from every pool that meters them: their own pool (if per-user metering), the pools of the user groups they belong to, including inherited groups (if per-group metering), or their Org's pool (if per-Org metering). Totals in the <> response are sums across those pools. + +A user who draws from no pool is not metered and can use Spotter without a limit. + +== Required privileges + +* **Get usage data for user** — Any user can retrieve their own usage. Retrieving another user's usage requires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege. +* **Search, Update, Delete** — Require `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege. Users with only `CAN_MANAGE_SPOTTER`, and Org administrators without cluster-level `ADMINISTRATION`, cannot call these endpoints. + +[#get-usage-data-for-user] +== Get usage data for user + +Retrieves a user's combined Spotter usage: every usage pool the user draws from, with usage, warning limits, and limits summed across them. Use this endpoint to show users how many Spotter questions they have left or to check whether a user is blocked by a usage limit. + +=== Endpoint + +---- +GET /api/rest/2.0/ai/usage-data/user +---- + +=== Query parameters + +[width="100%", cols="2,1,1,4", options="header"] +|=== +| Parameter | Type | Required | Description + +| `user_identifier` +| String +| No +| GUID of the user whose usage to retrieve. Defaults to the authenticated user. Passing another user's GUID requires `ADMINISTRATION` privilege. + +|=== + +=== Response + +If the request is successful, the API returns a `summary` object with the following properties: + +[width="100%", cols="2,1,4", options="header"] +|=== +| Property | Type | Description + +| `pools` +| Array +| The individual pools the user draws from. + +| `total_usage` +| Integer +| Total questions consumed across all pools. + +| `total_warning_limit` +| Integer +| Sum of warning limits across all pools. + +| `total_limit` +| Integer +| Sum of limits across all pools. + +| `total_remaining` +| Integer +| Questions the user can still ask. Absent when `has_unlimited_pool` is `true`. + +| `is_at_warning` +| Boolean +| `true` when usage has reached the combined warning limit. + +| `is_at_limit` +| Boolean +| `true` when usage has reached the combined limit and further Spotter questions are blocked. + +| `has_unlimited_pool` +| Boolean +| `true` when any of the user's pools has no limit, making the user effectively unlimited. + +|=== + +=== Request example + +.cURL +[source, cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/user' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {access-token}' +---- + +.cURL (retrieve another user's usage) +[source, cURL] +---- +curl -X GET -G \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/user' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-urlencode 'user_identifier={user-guid}' +---- + +=== Response codes + +[width="100%", cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Successful operation. +| **400** | Invalid request. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller requested another user's usage without `ADMINISTRATION` privilege. +| **500** | Internal server error. +|=== + +[#search-usage-data] +== Search usage data + +Retrieves Spotter usage pools. A usage pool is the Spotter question allowance configured for a user, user group, or Org, together with how many questions have been consumed. Use this endpoint to monitor usage across your users, for example to find pools that are close to their limit. + +=== Endpoint + +---- +POST /api/rest/2.0/ai/usage-data/search +---- + +=== Request parameters + +[width="100%", cols="2,1,1,4", options="header"] +|=== +| Parameter | Type | Required | Description + +| `keys` +| Array of objects +| No +| Keys of the pools to retrieve. Each key has an `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and an `entity_identifier` (the GUID of the user or user group, or the ID of the Org). Omit to retrieve every pool on the cluster. + +|=== + +=== Response + +If the request is successful, the API returns `usage_data`, one entry per pool: + +[width="100%", cols="2,1,4", options="header"] +|=== +| Property | Type | Description + +| `key` +| Object +| The entity the pool meters, with `entity_type` and `entity_identifier`. + +| `usage` +| Integer +| Questions consumed from the pool. + +| `warning_limit` +| Integer +| Usage level at which users are warned. Absent when no warning is configured. + +| `limit` +| Integer +| Maximum questions the pool allows. Absent when the pool is unlimited. + +| `updated_time_in_millis` +| Long +| Timestamp of when the pool was last configured. + +| `updated_by` +| String +| User who last configured the pool. + +|=== + +=== Request example + +.cURL (retrieve all pools) +[source, cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-raw '{}' +---- + +.cURL (retrieve specific pools) +[source, cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-raw '{ + "keys": [ + { + "entity_type": "USER", + "entity_identifier": "{user-guid}" + } + ] +}' +---- + +=== Response codes + +[width="100%", cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Successful operation. +| **400** | Invalid request. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have `ADMINISTRATION` privilege. +| **500** | Internal server error. +|=== + +[#update-usage-data] +== Create or update usage data + +Creates or updates Spotter usage pools. Use this endpoint to provision limits for new users or groups, raise or lower an existing limit, or reset usage at the start of a billing period. + +A pool that does not exist is created. Fields omitted from an update keep their current value. + +=== Endpoint + +---- +POST /api/rest/2.0/ai/usage-data/update +---- + +=== Request parameters + +[width="100%", cols="2,1,1,4", options="header"] +|=== +| Parameter | Type | Required | Description + +| `updates` +| Array of objects +| Yes +| At least one entry. Each entry contains the following properties. + +| `updates[].key` +| Object +| Yes +| The pool to create or update, with `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and `entity_identifier` (the GUID of the user or user group, or the ID of the Org). + +| `updates[].limit` +| Integer +| No +| Maximum Spotter questions the pool allows. + +| `updates[].warning_limit` +| Integer +| No +| Usage level at which users are warned that they are approaching the limit. + +| `updates[].usage` +| Integer +| No +| Questions consumed so far. Set to `0` to reset the pool. + +|=== + +=== Response + +If the request is successful, the API returns `usage_data`, with each updated pool as it stands after the change. The response structure is the same as the <> response. + +=== Request example + +.cURL (create a pool for a user) +[source, cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/update' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-raw '{ + "updates": [ + { + "key": { + "entity_type": "USER", + "entity_identifier": "{user-guid}" + }, + "limit": 500, + "warning_limit": 400 + } + ] +}' +---- + +.cURL (reset a pool's usage to zero) +[source, cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/update' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-raw '{ + "updates": [ + { + "key": { + "entity_type": "USER", + "entity_identifier": "{user-guid}" + }, + "usage": 0 + } + ] +}' +---- + +=== Response codes + +[width="100%", cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Successful operation. +| **400** | `updates` is empty, a key is missing its `entity_type` or `entity_identifier`, or a key uses a different `entity_type` from the cluster's existing pools. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have `ADMINISTRATION` privilege. +| **500** | Internal server error. +|=== + +[#delete-usage-data] +== Delete usage data + +Deletes Spotter usage pools. Use this endpoint to remove a limit from a user, user group, or Org, or to clear every pool before switching the metering scope. + +Deleting a pool removes its limit rather than blocking its users. A user who no longer draws from any pool is not metered and can use Spotter without a limit. + +[WARNING] +==== +This operation cannot be undone. To recreate a deleted pool, use the <> endpoint. The new pool's usage restarts from `0`. +==== + +=== Endpoint + +---- +POST /api/rest/2.0/ai/usage-data/delete +---- + +=== Request parameters + +[width="100%", cols="2,1,1,4", options="header"] +|=== +| Parameter | Type | Required | Description + +| `keys` +| Array of objects +| Yes +| At least one entry. Each key has an `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and an `entity_identifier` (the GUID of the user or user group, or the ID of the Org). + +|=== + +=== Response + +If the request is successful, the API returns `deleted_keys`, the keys of the pools that existed and were deleted. Keys that matched no pool are omitted from the response. + +=== Request example + +.cURL +[source, cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/delete' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-raw '{ + "keys": [ + { + "entity_type": "ORG", + "entity_identifier": "{org-id}" + } + ] +}' +---- + +=== Response codes + +[width="100%", cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Successful operation. +| **400** | `keys` is empty, or a key is missing its `entity_type` or `entity_identifier`. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have `ADMINISTRATION` privilege. +| **500** | Internal server error. +|=== From 226e0d201f8b894496e51b335bd8d50224ec7c78 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:57:08 +0530 Subject: [PATCH 039/169] docs: restore full REST API v2 reference and add Spotter Usage Data, Input Table, Link Customization endpoints --- modules/ROOT/pages/rest-api-v2-reference.adoc | 1460 ++++++++++++++++- 1 file changed, 1441 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index 6c9bd9c61..be5a04d0b 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -1,17 +1,1441 @@ ---- CITABLE SOURCE --- -File: modules/ROOT/pages/rest-api-v2-reference.adoc -Branch: docs/scal-26-11-0-cl-doc-updates -URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc -To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc#L{line_number} ---- - -{ - "path": "modules/ROOT/pages/rest-api-v2-reference.adoc", - "name": "rest-api-v2-reference.adoc", - "size": 9921, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/rest-api-v2-reference.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-api-v2-reference.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/rest-api-v2-reference.adoc\",\n \"name\": \"rest-api-v2-reference.adoc\",\n \"size\": 68802,\n \"content\": \"= REST API v2.0 Reference\\n:toc: true\\n\\n:page-title: REST API Reference Guide\\n:page-pageid: rest-apiv2-reference\\n:page-description: REST API Reference\\n\\nThis API Reference page lists the REST API v2.0 endpoints and provides basic information about the resource URLs and supported operations. If you want to try out these APIs, view detailed documentation, and download code samples, visit the +++REST API v2.0 Playground+++.\\n\\n[NOTE]\\n====\\nAccess to ThoughtSpot data is controlled based on xref:api-user-management.adoc#group-privileges[user privileges] and xref:configure-user-access.adoc#_object_level_permissions[object-level permissions]. Some operations are available to all users and may require at least view access to the metadata object. ThoughtSpot users are assigned access privileges based on the group to which they belong. Additionally, object owners can control access to a metadata object using `MODIFY` (*Can edit*), `READ_ONLY` (*Can view*), or `NO_ACCESS` permission when sharing an object with other users and groups.\\n====\\n\\n== AI\\n\\n[div boxAuto]\\n--\\n[width=\\\"100%\\\" cols=\\\"6,6,3\\\"]\\n[options='header']\\n|=====\\n|API endpoint| Release version | Playground link\\n\\na|`POST /api/rest/2.0/ai/agent/conversation/create` +\\nCreates a conversation session with ThoughtSpot's Spotter agent.\\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/conversation/create` +\\nCreates a conversation session with ThoughtSpot Spotter\\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/data-source-suggestions` +\\nGets data source recommendations for a given query.\\n|ThoughtSpot Cloud: __26.2.0.cl or later__ +\\n|+++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/relevant-questions/` +\\nBreaks down a user submitted query into relevant questions\\n|ThoughtSpot Cloud: __10.13.0.cl or later__ +\\n|+++Try it out+++\\n\\na| `POST /api/rest/2.0/ai/agent/converse/sse` +\\nAllows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details.\\n|ThoughtSpot Cloud: __10.13.0.cl or later__\\n| +++Try it out+++\\n\\na| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +\\nGenerates responses to user queries and follow-up questions sent in the specified conversation session.\\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/answer/create` +\\nGenerates an Answer for a Natural Language Search query.\\n|ThoughtSpot Cloud: __10.4.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` +\\nAllows sending a query to an ongoing conversation session with Spotter agent and generate response.\\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` +\\nStops an in-progress Spotter agent response for a given conversation session.\\n|ThoughtSpot Cloud: __26.6.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/instructions/set` +\\nSets data model instructions.\\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`POST /api/rest/2.0/ai/instructions/get` +\\nRetrieves data model instructions.\\n|ThoughtSpot Cloud: __10.15.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`PUT /api/rest/2.0/ai/agent/instructions/set` +\\nSets custom instructions for the Spotter agent.\\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`GET /api/rest/2.0/ai/agent/instructions/get` +\\nRetrieves the custom instructions currently configured for the Spotter agent.\\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`GET /api/rest/2.0/ai/agent/conversations` +\\nRetrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege.\\n|ThoughtSpot Cloud: __26.7.0.cl or later__ +\\nThoughtSpot Software: __Not available__ a| +++Try it out+++\\n\\na|`GET /a - -... [truncated, 11,002 chars total] += REST API v2.0 Reference +:toc: true + +:page-title: REST API Reference Guide +:page-pageid: rest-apiv2-reference +:page-description: REST API Reference + +This API Reference page lists the REST API v2.0 endpoints and provides basic information about the resource URLs and supported operations. If you want to try out these APIs, view detailed documentation, and download code samples, visit the +++REST API v2.0 Playground+++. + +[NOTE] +==== +Access to ThoughtSpot data is controlled based on xref:api-user-management.adoc#group-privileges[user privileges] and xref:configure-user-access.adoc#_object_level_permissions[object-level permissions]. Some operations are available to all users and may require at least view access to the metadata object. ThoughtSpot users are assigned access privileges based on the group to which they belong. Additionally, object owners can control access to a metadata object using `MODIFY` (*Can edit*), `READ_ONLY` (*Can view*), or `NO_ACCESS` permission when sharing an object with other users and groups. +==== + +== AI + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link + +a|`POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a conversation session with ThoughtSpot's Spotter agent. +|ThoughtSpot Cloud: __10.13.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/conversation/create` + +Creates a conversation session with ThoughtSpot Spotter +|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/data-source-suggestions` + +Gets data source recommendations for a given query. +|ThoughtSpot Cloud: __26.2.0.cl or later__ + +|+++Try it out+++ + +a|`POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user submitted query into relevant questions +|ThoughtSpot Cloud: __10.13.0.cl or later__ + +|+++Try it out+++ + +a| `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. +|ThoughtSpot Cloud: __10.13.0.cl or later__ +| +++Try it out+++ + +a| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + +Generates responses to user queries and follow-up questions sent in the specified conversation session. +|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/answer/create` + +Generates an Answer for a Natural Language Search query. +|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + +Allows sending a query to an ongoing conversation session with Spotter agent and generate response. +|ThoughtSpot Cloud: __10.15.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + +Stops an in-progress Spotter agent response for a given conversation session. +|ThoughtSpot Cloud: __26.6.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/instructions/set` + +Sets data model instructions. +|ThoughtSpot Cloud: __10.15.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/instructions/get` + +Retrieves data model instructions. +|ThoughtSpot Cloud: __10.15.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets custom instructions for the Spotter agent. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the custom instructions currently configured for the Spotter agent. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/conversations` + +Retrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}` + +Retrieves the full message history of a single saved Spotter agent conversation, including user prompts and agent response items for each turn. Requires `CAN_USE_SPOTTER` privilege. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates the display title of a saved Spotter agent conversation. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +Permanently deletes a saved Spotter agent conversation and all its associated messages. This operation is irreversible. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation. +|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 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 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+++ + + a|`GET /api/rest/2.0/ai/usage-data/user` + + Retrieves a user's combined Spotter usage: every pool the user draws from, with usage, warning limits, and limits summed across them. + |ThoughtSpot Cloud: __26.11.0.cl or later__ + + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + + a|`POST /api/rest/2.0/ai/usage-data/search` + + Retrieves Spotter usage pools: the question allowance configured for each user, user group, or Org and how much has been consumed. + |ThoughtSpot Cloud: __26.11.0.cl or later__ + + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + + a|`POST /api/rest/2.0/ai/usage-data/update` + + Creates or updates Spotter usage pools, setting the question allowance for a user, user group, or Org. + |ThoughtSpot Cloud: __26.11.0.cl or later__ + + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + + a|`POST /api/rest/2.0/ai/usage-data/delete` + + Deletes Spotter usage pools. Users who no longer draw from any pool are no longer metered. + |ThoughtSpot Cloud: __26.11.0.cl or later__ + + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + + a|`POST /api/rest/2.0/ai/shareAnalyst` + + Updates share permissions for a Spotter Analyst. Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. + |ThoughtSpot Cloud: __26.11.0.cl or later__ + + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + |===== +-- + + +== Authentication + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`GET /api/rest/2.0/auth/session/user` + +Gets session information for the currently logged-in user. + + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software:__ 9.0.1.sw or later __ a| ++++Try it out+++ +|`GET /api/rest/2.0/auth/session/token` + +Generates a new bearer token from an existing authenticated session. + +|ThoughtSpot Cloud: __9.4.0.cl or later__ + +ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ + +| +`POST /api/rest/2.0/auth/session/login` + +Creates a login session for a ThoughtSpot user. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a| `POST /api/rest/2.0/auth/token/object` + + +Gets an authentication token that grants access only to the metadata object specified in the API request. +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/auth/token/full` + +Gets an authentication token from ThoughtSpot that grants access to a full application session. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/auth/session/logout` + +Logs out the currently logged-in user. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ +a|`POST /api/rest/2.0/auth/token/revoke` + +Revokes authentication token granted for a user. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ + +a| `POST /api/rest/2.0/auth/token/validate` + +Validates the authentication token specified in the API request. a| ThoughtSpot Cloud: __9.12.0.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out +++ + +a| `POST /api/rest/2.0/auth/token/custom` + +Generates an authentication token with pre-defined RLS rules and filter attributes for a user. a| ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out +++ + +a| `POST /api/rest/2.0/auth/configure` + +Enables or disables authentication. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + +a| +++Try it out +++ + +a| `POST /api/rest/2.0/auth/search` + +Retrieves the authentication configuration for the specified auth type. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + +a| +++Try it out +++ + +|===== +-- + +== Collections +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/collections/create` + + +Creates a new Collection. + +|ThoughtSpot Cloud: __26.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ + a| +++Try it out+++ + +a|`POST /api/rest/2.0/collections/search` + +Gets a list of Collections available in ThoughtSpot. + +|ThoughtSpot Cloud: __26.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ + a| +++Try it out+++ + +a|`POST /api/rest/2.0/collections/{collection_identifier}/update` + + +Updates an existing Collection. + +|ThoughtSpot Cloud: __26.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ + a| +++Try it out +++ + +a|`POST /api/rest/2.0/collections/delete` + + +Deletes one or more Collections. + +|ThoughtSpot Cloud: __26.4.0.cl or later__ + +ThoughtSpot Software: __Not available__ + a| +++Try it out +++ + +|===== +-- + +== Connections + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/connection/search` + + +Gets connection objects from ThoughtSpot. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/connection/create` + +Creates a connection to the data warehouse specified in the API request. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/connection/update` [tag redBackground]#DEPRECATED# + + +Updates a connection object. + +__Note: This API endpoint is deprecated in ThoughtSpot 10.4.0.cl and later versions. To update a connection, use `POST /api/rest/2.0/connections/{connection_identifier}/update`. __ + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/connections/{connection_identifier}/update` + +Updates a connection object. +a|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/connection/delete` [tag redBackground]#DEPRECATED# + +Deletes a connection object. + +__Note: This API endpoint is deprecated in ThoughtSpot 10.4.0.cl and later versions. To delete a connection, use `api/rest/2.0/connections/delete/{connection_identifier}`. __ + +a|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/connections/{connection_identifier}/delete` + +Deletes a connection +a|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ a| ++++Try it out +++ + +a| +`POST /api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + +Validates the connection metadata differences between Cloud Data Warehouse and ThoughtSpot. +|ThoughtSpot Cloud: __9.10.5.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ +a|+++Try it out +++ +a| +`POST /api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + +Downloads connection metadata differences between Cloud Data Warehouse and ThoughtSpot. +|ThoughtSpot Cloud: __9.10.5.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ +a| ++++Try it out +++ + +a| `POST /api/rest/2.0/connections/{connection_identifier}/status` + +Deactivates or activates a connection. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + +a| +++Try it out +++ + +|===== +-- +== Connection Configuration + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/connection-configurations/create` + +Creates a connection configuration to the connection object specified in the API request. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ + a| +++Try it out+++ + +a|`POST /api/rest/2.0/connection-configurations/search` + + +Gets the connection configuration for the specified connection object. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ + a| +++Try it out+++ + + +a|`POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + + +Updates the connection configuration object. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ + a| ++++Try it out +++ + + +a| `POST /api/rest/2.0/connection-configurations/delete` + +Deletes the connection configuration object. +a|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ + a| ++++Try it out +++ +|===== +-- + +== Custom actions + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/customization/custom-actions/search` + + +Gets custom action objects. + +|ThoughtSpot Cloud: __9.6.0.cl or later__ + +ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/custom-actions` + +Creates a custom action and assigns it to a given metadata object. + +|ThoughtSpot Cloud: __9.6.0.cl or later__ + +ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + + +Updates the properties of a custom action object. + +|ThoughtSpot Cloud: __9.6.0.cl or later__ + +ThoughtSpot Software: __9.8.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + + +Deletes a custom action. + +|ThoughtSpot Cloud: __9.6.0.cl or later__ + +ThoughtSpot Software: __9.8.0.sw or later__ a| ++++Try it out +++ +|===== +-- + +== Custom calendars + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a| `POST /api/rest/2.0/calendars/create` + +Creates a custom calendar. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ +a| +++Try it out+++ +| `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + +Deletes a custom calendar. +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ +a| +++Try it out+++ +| `POST /api/rest/2.0/calendars/generate-csv` + +Exports a custom calendar in the CSV format. +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ +a| +++Try it out+++ +|`POST /api/rest/2.0/calendars/search` + +Gets custom calendars for the connection ID specified in the API request. +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ +a| +++Try it out+++ +|`POST /api/rest/2.0/calendars/{calendar_identifier}/update` + +Updates a custom calendar. +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ +a|+++Try it out+++ +|==== +-- + +== Data + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/searchdata` + + +Generates results for the search query specified in the API request. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/metadata/liveboard/data` + +Gets details of a Liveboard and its visualizations. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/metadata/answer/data` + + +Gets Answer data from ThoughtSpot. You can fetch data for saved Answers only. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ +|===== +-- + +== DBT + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/dbt/dbt-connection` + + +Creates a DBT connection object in ThoughtSpot. + +|ThoughtSpot Cloud: __9.10.0.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/dbt/generate-tml` + + +Creates TML for the given data objects and imports the TML data to ThoughtSpot. + +|ThoughtSpot Cloud: __9.10.0.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/dbt/generate-sync-tml` + + +Resynchronizes the existing list of Models and Tables TML content for the specified DBT connection object and imports these to ThoughtSpot. + +|ThoughtSpot Cloud: __9.10.0.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/dbt/search` + + +Gets a list of DBT connection objects. + +|ThoughtSpot Cloud: __9.10.0.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ a| ++++Try it out +++ + + +a|`POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + +Updates a DBT connection object. + +|ThoughtSpot Cloud: __9.10.0.cl or later__ + +ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out+++ +|===== +-- + +== Email customization + +[earlyAccess eaBackground] + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/customization/email` + + +Creates the customized configuration for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/email/delete` + +Deletes the existing customized configuration set for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/email/search` + + +Searches the customized configuration set for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/customization/email/update` + + +Updates an existing email customization set for the notification emails. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/customization/email/validate` + + +Validates the customized configuration set for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out +++ +|===== +-- + +== Groups + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/groups/search` + +Gets details of one or several Groups. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/groups/create` + +Creates a Group object. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/groups/{group_identifier}/update` + +Updates the object properties of a group. You can also use this API to add or remove users, sub-groups, and privileges. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/groups/{group_identifier}/delete` + + +Removes a group object from ThoughtSpot. + +a|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/groups/import` + +Imports group objects from external databases into ThoughtSpot. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ +|===== +-- + + +== Jobs + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/jobs/history/communication-channels/search` + +Gets information about the execution and delivery status for scheduled jobs such as webhook delivery. +|ThoughtSpot Cloud: __26.4.0.cl or later__ +ThoughtSpot Software: __Not available__ + a| +++Try it out+++ +|===== +-- + +== Logs + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/logs/fetch` + + +Gets security audit logs from the ThoughtSpot system. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +|===== +-- + +== Localizations + +[div boxAuto] +-- +[width="100%", cols="8,5,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link + +a|`POST /api/rest/2.0/localizations/manual-translation/import` + +Imports a CSV file containing custom locale-specific translations for ThoughtSpot UI strings. New entries are inserted and existing entries are updated (upsert). +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + +a|`POST /api/rest/2.0/localizations/manual-translation/export` + +Exports all manual translations for the specified org scope as a CSV file. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + +a|`POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + +Returns all manual translations for the specified locale as a JSON object. Accessible to all authenticated users. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + +a|`POST /api/rest/2.0/localizations/manual-translation/delete` + +Deletes all manual translations for the specified org scope. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ +|===== +-- + +== Metadata + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/metadata/worksheets/convert` + +Converts a Worksheet to a Model. |ThoughtSpot Cloud: __10.6.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ + + +a|`POST /api/rest/2.0/metadata/copyobject` + +Creates a copy of an object. |ThoughtSpot Cloud: __10.6.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/metadata/delete` + +Removes a metadata object. +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/metadata/tml/export` + +Exports TML representation of the metadata objects from ThoughtSpot in JSON or YAML format. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + + +a|`POST /api/rest/2.0/metadata/tml/export/batch` + +Exports a complete set of TML for a user, user group, or Role object. +|ThoughtSpot Cloud: __10.1.0.cl or later__ + +ThoughtSpot Software: __10.1.0.sw or later__ +a|+++Try it out +++ + + +a|`POST /api/rest/2.0/metadata/answer/sql` + +Gets SQL query data for a saved Answer. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/metadata/tml/async/status` + +Gets status details for scheduled TML import tasks. +|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/metadata/liveboard/sql` + + +Gets SQL query data for the visualizations on a Liveboard. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + + +a| `POST /api/rest/2.0/metadata/tml/import` + + +Imports TML representation of the metadata objects into ThoughtSpot. + +a|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + + +a| `POST /api/rest/2.0/metadata/tml/async/import` + + +Schedules an asynchronous TML import task for the given objects. +|ThoughtSpot Cloud: __10.4.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/metadata/search` + +Gets details of metadata objects from ThoughtSpot. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a| `POST /api/rest/2.0/metadata/parameterize-fields` + +Allows you to parameterize multiple fields for a given metadata object. +a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/metadata/parameterize` [tag redBackground]#DEPRECATED# + +Allows you to parameterize fields in metadata objects. +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + +Allows removing parameterization from fields in metadata objects + +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/metadata/headers/update` + +Updates the header attributes of a metadata object. +|ThoughtSpot Cloud: __10.6.0.cl or later__ + +ThoughtSpot Software: __10.7.0.sw or later__ +a| ++++Try it out+++ + +a| `POST /api/rest/2.0/metadata/update-obj-id` + +Updates object IDs for given metadata objects. +|ThoughtSpot Cloud: __10.8.0.cl or later__ + +ThoughtSpot Software: __10.10.0.sw or later__ +a| ++++Try it out+++ +|===== +-- + +== Orgs + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/orgs/search` + +Gets a list of Orgs configured on the ThoughtSpot system. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __Not Applicable__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/orgs/create` + +Creates an Org object. + + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __Not Applicable__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/orgs/{org_identifier}/update` + +Modifies the object properties of an Org. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __Not Applicable__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/orgs/{org_identifier}/delete` + + +Deletes an Org object from ThoughtSpot. + +a|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __Not Applicable__ a| ++++Try it out +++ +|===== +-- + +== Reports + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/report/liveboard` + +Exports a Liveboard and its visualizations as a PDF or PNG file. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/report/answer` + + +Downloads a saved Answer in PDF, CSV, PNG, or XLSX format. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ +|===== +-- + +[#rbacRoles] +== Roles + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/roles/search` + + +Gets Role objects from ThoughtSpot. + +|ThoughtSpot Cloud: __9.5.0.cl or later__ + +ThoughtSpot Software: __Not applicable__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/roles/create` + +Creates a Role with a defined set of privileges. + +|ThoughtSpot Cloud: __9.5.0.cl or later__ + +ThoughtSpot Software: __Not applicable__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/roles/{role_identifier}/update` + + +Updates a Role object. + +|ThoughtSpot Cloud: __9.5.0.cl or later__ + +ThoughtSpot Software: __Not applicable__ a| ++++Try it out +++ + + +a|`POST /api/rest/2.0/roles/{role_identifier}/delete` + + +Deletes a Role object. + +|ThoughtSpot Cloud: __9.5.0.cl or later__ + +ThoughtSpot Software: __Not applicable__ a| ++++Try it out +++ +|===== +-- + + +== Schedules + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/schedules/create` + + +Creates a Liveboard schedule job. + +|ThoughtSpot Cloud: __9.4.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/schedules/search` + + +Gets details of the scheduled Liveboard jobs. + +|ThoughtSpot Cloud: __9.4.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/schedules/{schedule_identifier}/update` + + +Updates a Liveboard job schedule. + +|ThoughtSpot Cloud: __9.4.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + + +a|`POST /api/rest/2.0/schedules/{schedule_identifier}/delete` + +Deletes a scheduled Liveboard job. + +|ThoughtSpot Cloud: __9.4.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ + +|===== +-- + +== Security + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link + +a|`POST /api/rest/2.0/security/metadata/assign` + +Assigns a new author or changes the author of a metadata object. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/security/column/rules/fetch` + +Fetches column security rules for the Tables specified in the API request. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/security/principals/fetch-permissions` + +Gets a list of objects that a user or group has access to. You can also specify the metadata type in the API request to fetch user permission details for Liveboards, Worksheets, or Answers. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a| `POST /api/rest/2.0/security/metadata/fetch-object-privileges` + +Retrieves details of object-level privileges assigned to users or groups for a specified set of data objects. + +|ThoughtSpot Cloud: __26.3.0.cl or later__ + +ThoughtSpot Software: Not available a| +++Try it out+++ + +a|`POST /api/rest/2.0/security/metadata/fetch-permissions` + +Gets access permission details for metadata objects. To get object access details for a user or group, specify the user or group identifiers. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a| `POST /api/rest/2.0/security/metadata/manage-object-privilege` + +Allows assigning object-level permissions to other users and groups and granting access to Spotter coaching information. + +|ThoughtSpot Cloud: __26.3.0.cl or later__ + +ThoughtSpot Software: Not available a| +++Try it out+++ + +| `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + +Allows publishing metadata objects to one or several Orgs on an instance. +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/security/metadata/share` + + +Allows sharing metadata objects, such as Liveboards, saved Answers, and Worksheets with another user or group in ThoughtSpot. + +a|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +| `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + +Removes published metadata objects from the Orgs specified in the API request. +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/security/column/rules/update` + +Adds or updates column security rules applied on the Table specified in the API request. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ a| ++++Try it out +++ +|===== +-- +== Style customization + +// SOURCE: SCAL-293070, SCAL-293071 + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link + +a|`POST /api/rest/2.0/customization/styles/search` + +Gets the current style configuration at the cluster and active Org scope. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/update` + +Updates style settings such as the navigation panel color, chart color palette, logos, embedded footer text, and visualization font assignments at the cluster or Org scope. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/fonts/search` + +Gets custom fonts uploaded to the ThoughtSpot instance. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates the display name, weight, style, or color of an existing custom font. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +|===== +-- + +== System + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version| Playground link +a|`Get System Information` + +Gets system information of your current logged-in cluster. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/system` + +Gets details of the current configuration running on your cluster. + + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/system/config-overrides` + +Gets details of the configuration overrides on your cluster. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/system/config-update` + + +Updates the current configuration of your instance. + +a|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/preferences/communication-channels/configure` + +Allows configuring communication channel preferences. +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/communication-channels/validate` + +Validates a communication channel, for example, a webhook connection. +a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/preferences/communication-channels/search` + +Allows searching communication channel preferences. +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/security-settings/configure` + +Allows configuring security settings. +a|ThoughtSpot Cloud: __26.2.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ a| +++Try it out +++ + +a|`POST /api/rest/2.0/system/security-settings/search` + +Allows fetching security settings. +a|ThoughtSpot Cloud: __26.2.0.cl or later__ + +ThoughtSpot Software: __26.3.0.sw or later__ a| +++Try it out +++ + +|===== + +-- + + +== Tags + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/tags/search` + +Gets details of tag objects from ThoughtSpot. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/tags/create` + +Creates a tag object in ThoughtSpot. + + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/tags/{tag_identifier}/update` + +Modifies the object properties of a tag. + + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/tags/{tag_identifier}/delete` + + +Deletes a tag object from ThoughtSpot. + +a|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/tags/assign` + +Assigns a tag to metadata objects. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/tags/unassign` + + +Removes the tag assigned to a metadata object. + +a|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ +|===== +-- + + +== Users + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/users/search` + +Gets details of one or several ThoughtSpot users. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/users/create` + +Creates a user. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/users/{user_identifier}/update` + +Updates the properties of a user object. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ + +a| `POST /api/rest/2.0/users/{user_identifier}/delete` + + +Deletes a user object from ThoughtSpot. + +a|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/users/import` + +Imports users from an external database to ThoughtSpot. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/users/change-password` + +Allows ThoughtSpot users to change the password of their account. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/users/reset-password` + +Resets the password of a user account. + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/users/force-logout` + +Logs out users from their current sessions. + + +|ThoughtSpot Cloud: __9.0.0.cl or later__ + +ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ +a|`POST /api/rest/2.0/users/activate` + + +Activates a deactivated user account. + +|ThoughtSpot Cloud: __9.7.0.cl or later__ + +ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out +++ + +|`POST /api/rest/2.0/users/deactivate` + +Deactivates a user account. + +|ThoughtSpot Cloud: __9.7.0.cl or later__ + +ThoughtSpot Software: __9.8.0.sw or later__ a| +++Try it out +++ +|===== +-- + +== Version control + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a| `POST /api/rest/2.0/vcs/git/config/search` + +Gets Git repository connections configured on the ThoughtSpot instance. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/vcs/git/commits/search` + + +Gets Git commit history for a given metadata object. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/vcs/git/config/create` + +Connects your ThoughtSpot instance to a Git repository. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/vcs/git/config/update` + + +Updates the Git repository settings configured for a ThoughtSpot instance. + +a|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/vcs/git/config/delete` + + +Deletes the Git repository configuration. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/vcs/git/branches/commit` + +Commits TML files to the Git branch configured on your instance. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/vcs/git/commits/{commit_id}/revert` + +Reverts to a previous commit in the Git branch. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/vcs/git/branches/validate` + +Validates the content of your source branch against the objects in your destination environment and identifies merge conflicts. + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/vcs/git/commits/deploy` + +Deploys commits to the destination environment (`Staging` or `Production`). + +|ThoughtSpot Cloud: __9.2.0.cl or later__ + +ThoughtSpot Software: __9.5.0.sw or later__ a| ++++Try it out +++ +|===== +-- + +== Variable [beta betaBackground]^Beta^ + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +| `POST /api/rest/2.0/template/variables/create` + +Allows creating a template variable. + +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/template/variables/search` + +Allows searching template variables. +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +|`POST /api/rest/2.0/template/variables/update` [tag redBackground]#DEPRECATED# + +Allows you to add, remove, or replace properties of one or several template variables. + +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| Not available in the Playground + +| `POST /api/rest/2.0/template/variables/{identifier}/update` + +Allows updating properties of a variable. + +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +| `POST /api/rest/2.0/template/variables/{identifier}/update-values` + +Allows you to assign, modify, replace, or reset variable values, and define the Org and object scope for each set of variable values. + +a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| ++++Try it out +++ + +| `POST /api/rest/2.0/template/variables/delete` + +Deletes one or more template variables. +a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| ++++Try it out +++ + +| `POST /api/rest/2.0/template/variables/update-values` [tag redBackground]#DEPRECATED# + +Allows updating properties of one or several variables. + +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ + +| `POST /api/rest/2.0/template/variables/{identifier}/delete` [tag redBackground]#DEPRECATED# + +Deletes a template variable. +a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| ++++Try it out +++ +|===== +-- + +== Webhooks [beta betaBackground]^Beta^ + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +| `POST /api/rest/2.0/webhooks/create` + +Allows creating a webhook and configuring a destination endpoint for webhook payloads. + +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| ++++Try it out +++ + +a| `POST /api/rest/2.0/webhooks/search` + +Retrieves webhook objects. +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| ++++Try it out +++ + +a|`GET /api/rest/2.0/webhooks/storage-config` + +Retrieves the AWS S3 storage destination configuration for a webhook. Returns data only if the webhook has a storage destination configured. Requires `ADMINISTRATION` or `DEVELOPER` privilege. +a|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + +|`POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +Allows you to edit properties of a webhook object. + +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| ++++Try it out +++ + +| `POST /api/rest/2.0/webhooks/delete` + +Deletes a webhook object. +a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| ++++Try it out +++ +|===== +-- + + [#inputTables] == Input Tables [div tableContainer] @@ -25,11 +1449,11 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs |POST |Creates an input table and links it to a ThoughtSpot model. Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. - |`/api/rest/2.0/input/tables/\{input_table_identifier}/update` + |`/api/rest/2.0/input/tables/{input_table_identifier}/update` |POST |Updates the name, description, or both of an input table. Requires `MODIFY` permission on the input table. - |`/api/rest/2.0/input/tables/\{input_table_identifier}/delete` + |`/api/rest/2.0/input/tables/{input_table_identifier}/delete` |POST |Deletes an input table. Requires `MODIFY` permission on the table's parent model. @@ -37,7 +1461,7 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs |POST |Adds a column to an existing input table. Requires `MODIFY` permission on the input table. - |`/api/rest/2.0/input/tables/columns/\{column_identifier}/delete` + |`/api/rest/2.0/input/tables/columns/{column_identifier}/delete` |POST |Deletes a column from an input table. Requires `MODIFY` permission on the input table. |=== @@ -45,7 +1469,6 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs For more information, see xref:input-table-api.adoc[Input Table APIs]. - [#linkCustomization] == Link Customization [div tableContainer] @@ -66,5 +1489,4 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs -- For more information, see xref:link-customization-api.adoc[Link Customization APIs]. - \ No newline at end of file From bb2aacc540b9095568875def02eba06fb5a0defb Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:57:11 +0530 Subject: [PATCH 040/169] docs: restore full REST API v2 reference and add Spotter Usage Data, Input Table, Link Customization endpoints From 202bfd43a9d7535de22d15ae611361694fd8ace9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:57:36 +0530 Subject: [PATCH 041/169] docs: add Spotter Usage Data and Share Analyst API entries to REST API v2 changelog --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 7e5d2491e..3a5f25c22 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -51,6 +51,26 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. + + === Spotter Usage Data APIs [Beta] + ThoughtSpot introduces four REST API v2.0 endpoints for managing Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. + + * `GET /api/rest/2.0/ai/usage-data/user` + + Retrieves a user's combined Spotter usage across all pools. + * `POST /api/rest/2.0/ai/usage-data/search` + + Retrieves usage pools configured for users, user groups, or Orgs. + * `POST /api/rest/2.0/ai/usage-data/update` + + Creates or updates usage pools, setting question allowances. + * `POST /api/rest/2.0/ai/usage-data/delete` + + Deletes usage pools. + + For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data APIs]. + + === Share Analyst API + The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. + + Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. + == Version 26.10.0.cl, October 2026\\n\\n=== Spotter AI APIs\\n\\nSpotter Analyst APIs::\\nThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically.\\n\\n* `POST /api/rest/2.0/ai/agent/analysts/create` +\\nCreates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts.\\n* `POST /api/rest/2.0/ai/agent/analysts/search` +\\nReturns the Spotter Analysts visible to the caller.\\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` +\\nUpdates a Spotter Analyst.\\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` +\\nDeletes a Spotter Analyst.\\n+\\nFor more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\\n\\nPin conversations in the update conversation API::\\nThe `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation].\\n\\nSpotter conversation enhancements::\\n\\n* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation.\\n* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification.\\n\\n=== TML and metadata type additions\\n\\n* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`.\\n* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response.\\n\\n=== Databricks semantic integrations\\n\\nThe `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it.\\n\\n=== Feature Management API\\nThis release introduces the following new REST API v2.0 endpoints for programmatic feature management.\\n\\n* `POST /api/rest/2.0/configurations/features/search` +\\nReturns feature configurations grouped by feature group.\\n* `POST /api/rest/2.0/configurations/features/assignments/update` +\\nUpdates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations.\\n* `POST /api/rest/2.0/configurations/features/values/update` +\\nSets feature value at `CLUSTER` or `ORG` scope.\\n\\nFor more information, see xref:feature-management-api.adoc[Feature Management API].\\n\\n=== Multi-Org tokens [beta betaBackground]^Beta^\\n\\nAuthentication token endpoints now support Org scope at issuance and inspection:\\n\\n* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens ... [truncated, 11,939 chars total] \ No newline at end of file From 93cf1002161a6927c112bf75022fe6277f194c29 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:57:38 +0530 Subject: [PATCH 042/169] docs: add Spotter Usage Data and Share Analyst API entries to REST API v2 changelog From 1b51fbe3a1cb5df204c91753dcb632d8e55165f8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:58:23 +0530 Subject: [PATCH 043/169] docs: restore full REST API v2 changelog and add November 2026 section with all new APIs --- modules/ROOT/pages/rest-apiv2-changelog.adoc | 1550 +++++++++++++++++- 1 file changed, 1520 insertions(+), 30 deletions(-) diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 3a5f25c22..1700f8f41 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -1,15 +1,14 @@ ---- CITABLE SOURCE --- -File: modules/ROOT/pages/rest-apiv2-changelog.adoc -Branch: docs/scal-26-11-0-cl-doc-updates -URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc -To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc#L{line_number} ---- - -{ - "path": "modules/ROOT/pages/rest-apiv2-changelog.adoc", - "name": "rest-apiv2-changelog.adoc", - "size": 10995, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/rest-apiv2-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/rest-apiv2-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/rest-apiv2-changelog.adoc\",\n \"name\": \"rest-apiv2-changelog.adoc\",\n \"size\": 77050,\n \"content\": \"= REST API v2.0 changelog\\n:toc: true\\n:toclevels: 1\\n\\n:page-title: REST API v2.0 changelog\\n:page-pageid: rest-v2-changelog\\n:page-description: Changelog of REST APIs\\n\\nThis 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].\\n\\n== Version 26.11.0.cl, November 2026\n\n === Org-level API rate limiting enforced\n The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response.\n\n For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests].\n\n === Link Customization APIs\n ThoughtSpot introduces two REST API v2.0 endpoints for managing the URL templates used when ThoughtSpot generates shareable links.\n\n * `POST /api/rest/2.0/customization/links/search` +\n Retrieves the URL templates at the cluster level or for the Org the caller is signed in to.\n * `POST /api/rest/2.0/customization/links/update` +\n Updates the URL templates at the cluster level or for the caller's Org, using `REPLACE` to set templates or `RESET` to clear overrides.\n\n Supported link types include `LIVEBOARD_SHARE_URL`, `VISUALIZATION_SHARE_URL`, `ANSWER_SHARE_URL`, `SPOTIQ_ANALYSIS_URL`, `UNSUBSCRIBE_URL`, `GENERIC_URL`, and `CONVERSATION_SHARE_URL`.\n\n Requires `ADMINISTRATION` or `DEVELOPER` privilege.\n\n For more information, see xref:link-customization-api.adoc[Link Customization APIs].\n\n === Input Table APIs\n ThoughtSpot introduces REST API v2.0 endpoints for creating and managing input tables programmatically.\n\n * `POST /api/rest/2.0/input-tables/create` -- Creates an input table and links it to a model (worksheet).\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` -- Adds editable columns to an existing input table.\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` -- Deletes an input table and drops the physical CDW table.\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` -- Deletes a single column from an input table.\n * `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` -- Writes rows into an input table using a keyed upsert (MERGE) operation.\n\n Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. If RBAC is enabled, the `CAN_MANAGE_INPUT_TABLES` privilege is required.\n\n For more information, see xref:input-table-api.adoc[Input Table APIs].\n\n === Share Analyst API\n\n `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share`::\n Updates share permissions on a Spotter Analyst for one or more principals (users or groups). Supports `READ_ONLY`, `MODIFY`, and `NO_ACCESS` share modes. Granting access also shares the Analyst's data sources with the recipient. Requires ownership of the Analyst, or `ADMINISTRATION` or `CAN_MANAGE_SPOTTER` privilege.\n +\n For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\n\n\n == Version 26.11.0.cl, November 2026 += REST API v2.0 changelog +:toc: true +:toclevels: 1 + +:page-title: REST API v2.0 changelog +:page-pageid: rest-v2-changelog +:page-description: Changelog of REST APIs + +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.11.0.cl, November 2026 === Org-level API rate limiting enforced The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response. @@ -31,27 +30,23 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs For more information, see xref:link-customization-api.adoc[Link Customization APIs]. === Input Table APIs - ThoughtSpot introduces REST API v2.0 endpoints for creating and managing input tables programmatically. + ThoughtSpot introduces five REST API v2.0 endpoints for managing input tables — user-editable tables stored in an external Cloud Data Warehouse and linked to a ThoughtSpot model. - * `POST /api/rest/2.0/input-tables/create` -- Creates an input table and links it to a model (worksheet). - * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` -- Adds editable columns to an existing input table. - * `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` -- Deletes an input table and drops the physical CDW table. - * `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` -- Deletes a single column from an input table. - * `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` -- Writes rows into an input table using a keyed upsert (MERGE) operation. + * `POST /api/rest/2.0/input/tables/create` + + Creates an input table. + * `POST /api/rest/2.0/input/tables/{input_table_identifier}/update` + + Updates an input table's name or description. + * `POST /api/rest/2.0/input/tables/{input_table_identifier}/delete` + + Deletes an input table. + * `POST /api/rest/2.0/input/tables/columns/create` + + Adds a column to an input table. + * `POST /api/rest/2.0/input/tables/columns/{column_identifier}/delete` + + Deletes a column from an input table. - Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. If RBAC is enabled, the `CAN_MANAGE_INPUT_TABLES` privilege is required. + Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. For more information, see xref:input-table-api.adoc[Input Table APIs]. - === Share Analyst API - - `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share`:: - Updates share permissions on a Spotter Analyst for one or more principals (users or groups). Supports `READ_ONLY`, `MODIFY`, and `NO_ACCESS` share modes. Granting access also shares the Analyst's data sources with the recipient. Requires ownership of the Analyst, or `ADMINISTRATION` or `CAN_MANAGE_SPOTTER` privilege. - + - For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. - - - === Spotter Usage Data APIs [Beta] ThoughtSpot introduces four REST API v2.0 endpoints for managing Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. @@ -71,6 +66,1501 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. - == Version 26.10.0.cl, October 2026\\n\\n=== Spotter AI APIs\\n\\nSpotter Analyst APIs::\\nThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically.\\n\\n* `POST /api/rest/2.0/ai/agent/analysts/create` +\\nCreates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts.\\n* `POST /api/rest/2.0/ai/agent/analysts/search` +\\nReturns the Spotter Analysts visible to the caller.\\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` +\\nUpdates a Spotter Analyst.\\n* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` +\\nDeletes a Spotter Analyst.\\n+\\nFor more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API].\\n\\nPin conversations in the update conversation API::\\nThe `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation].\\n\\nSpotter conversation enhancements::\\n\\n* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation.\\n* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification.\\n\\n=== TML and metadata type additions\\n\\n* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`.\\n* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response.\\n\\n=== Databricks semantic integrations\\n\\nThe `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it.\\n\\n=== Feature Management API\\nThis release introduces the following new REST API v2.0 endpoints for programmatic feature management.\\n\\n* `POST /api/rest/2.0/configurations/features/search` +\\nReturns feature configurations grouped by feature group.\\n* `POST /api/rest/2.0/configurations/features/assignments/update` +\\nUpdates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations.\\n* `POST /api/rest/2.0/configurations/features/values/update` +\\nSets feature value at `CLUSTER` or `ORG` scope.\\n\\nFor more information, see xref:feature-management-api.adoc[Feature Management API].\\n\\n=== Multi-Org tokens [beta betaBackground]^Beta^\\n\\nAuthentication token endpoints now support Org scope at issuance and inspection:\\n\\n* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens + == Version 26.10.0.cl, October 2026 + +=== Spotter AI APIs + +Spotter Analyst APIs:: +ThoughtSpot introduces the following REST API v2.0 endpoints to manage Spotter Analysts programmatically. + +* `POST /api/rest/2.0/ai/agent/analysts/create` + +Creates a Spotter Analyst with a name, description, data sources, and optional instructions, MCP connectors, and starter prompts. +* `POST /api/rest/2.0/ai/agent/analysts/search` + +Returns the Spotter Analysts visible to the caller. +* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` + +Updates a Spotter Analyst. +* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` + +Deletes a Spotter Analyst. ++ +For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. + +Pin conversations in the update conversation API:: +The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` endpoint now accepts an `is_pinned` attribute. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updating a conversation]. + +Spotter conversation enhancements:: + +* The `POST /api/rest/2.0/ai/agent/conversation/create` endpoint accepts an optional `analyst_identifier` to start the conversation from a Spotter Analyst, using the Analyst's data sources, instructions, and connectors. `metadata_context` is now required only when `analyst_identifier` is not provided; passing both or neither is rejected. The response includes the Analyst's `analyst_id` when applicable, and the `GET /api/rest/2.0/ai/agent/conversations` list response includes `analyst_id` per conversation. +* The `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` endpoint accepts an optional `notify_on_share` boolean. When `true` (default), recipients receive an in-app notification. + +=== TML and metadata type additions + +* The `TEMPLATE_VARIABLE` type is supported on `POST /api/rest/2.0/metadata/tml/export`, `POST /api/rest/2.0/metadata/update-obj-id`, and `POST /api/rest/2.0/metadata/headers/update`. +* The `ROLE` type is supported on `POST /api/rest/2.0/metadata/update-obj-id` and `POST /api/rest/2.0/metadata/headers/update`. The `POST /api/rest/2.0/template/variables/create` and `search` endpoints return `obj_id` in the response. + +=== Databricks semantic integrations + +The `POST /api/rest/2.0/semantic-integrations/create` endpoint accepts the `RDBMS_DATABRICKS` integration type, and the `search` endpoint returns it. + +=== Feature Management API +This release introduces the following new REST API v2.0 endpoints for programmatic feature management. + +* `POST /api/rest/2.0/configurations/features/search` + +Returns feature configurations grouped by feature group. +* `POST /api/rest/2.0/configurations/features/assignments/update` + +Updates Org assignments for a feature using `ADD`, `REMOVE`, or `REPLACE` operations. +* `POST /api/rest/2.0/configurations/features/values/update` + +Sets feature value at `CLUSTER` or `ORG` scope. + +For more information, see xref:feature-management-api.adoc[Feature Management API]. + +=== Multi-Org tokens [beta betaBackground]^Beta^ + +Authentication token endpoints now support Org scope at issuance and inspection: + +* The `/api/rest/2.0/auth/token/full`, `/api/rest/2.0/auth/token/custom`, and `/api/rest/2.0/auth/token/object` endpoints accept an optional `scope` object to allow administrators to generate multi-org tokens. +* Token responses, including `POST /api/rest/2.0/auth/token/validate`, retrun `scope/org_scope` and `scope/org_ids`, indicating the Orgs the token is authorized for. +* API requests made with a multi-Org token select the target Org using the `X-Org-Selector` header. The header selects from the Orgs already authorized on the token; it does not grant new access. + +For more information, see xref:authentication.adoc#multi-org-tokens[Multi-Org tokens]. + +== Version 26.9.0.cl, September 2026 + +=== Answer Export API + +The following enhancements for the `POST /api/rest/2.0/report/answer` endpoint are now GA: + +`type` parameter:: +The request body accepts a new `type` parameter that specifies the kind of Answer to export: ++ +* `SAVED` (default): exports a saved Answer. +* `PINNED`: exports a pinned Answer from a Liveboard. + +Pinned Answer export:: +Set `type` to `PINNED` to export a pinned Answer (a visualization on a Liveboard) directly. The Answer downloads with Liveboard context: Liveboard-level filters, Runtime Filters, and Column Security Rules are applied automatically. + +Personalized View support:: +Pass `personalised_view_identifier` to export data from a specific Personalized View of a Liveboard. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter-generated Answers, in addition to CSV and PNG. + +Custom PNG dimensions:: +Use `x_resolution` and `y_resolution` parameters to specify custom pixel dimensions for PNG exports. + +Display scaling:: +Use `scaling` to adjust the relative size of chart elements in a PNG export without cropping the image. + +Dynamic file naming:: +Exported files are automatically named based on the Answer title with the correct file extension (`.png`, `.pdf`, `.csv`, `.xlsx`) appended. + +For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer Report API]. + +=== Snowflake Semantic View integration APIs +This release introduces the following new REST API v2.0 endpoints for managing Snowflake Semantic View integrations programmatically. + +* `POST /api/rest/2.0/semantic-integrations/create` + +Creates a new semantic integration by reading a Snowflake Semantic View and generating a ThoughtSpot data model. +* `POST /api/rest/2.0/semantic-integrations/search` + +Returns a list of semantic integrations matching the specified filter criteria. +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/import` + +Re-imports semantic updates from Snowflake and refreshes the associated ThoughtSpot data model. +* `POST /api/rest/2.0/semantic-integrations/{semantic_integration_identifier}/delete` + +Deletes a semantic integration and its generated ThoughtSpot data model. + +For more information, see xref:semantic-integrations-api.adoc[Snowflake Semantic View integration APIs]. + +=== Conversation sharing APIs +ThoughtSpot introduces the following REST API v2.0 endpoints to share Spotter agent conversations with other users or groups. + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share` + +Share a conversation with users or groups with `READ_ONLY` access. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content` + +Retrieve the shared messages and answers in a conversation. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info` + +Retrieve the list of principals a conversation is shared with and their access levels. + +For more information, see xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. + +=== KPI Sparkline setting in metadata search response +The `POST /api/rest/2.0/metadata/search` API response now includes the `isSparklineEnabled` parameter in the `AnswerSpecHeader` object for KPI chart type answers. This boolean parameter indicates whether the sparkline trend line is enabled for the KPI visualization. + +//// +=== Outline Encoding for Muze charts +Developers building custom charts with Muze can now bind a data field to `encoding.outline` to produce ordinal color palettes (for categorical fields) or continuous gradient ramps (for measures), with full legend rendering and legend-to-mark interaction. + +The static `outline` config (`{ fill, color, width, dash }`) remains fully backward compatible. Supported mark types: Point, Bar, Arc. +//// + +=== Personalized Views TML portability +The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances: + +* The `author` field in Personalized View TML maps to the view owner's username or email, ensuring ownership is retained while delegating ownership to another user during import. +* The `obj_id` field provides a stable cross-environment identifier for inter-Org deployments. +* Smart merge import: when importing a Liveboard TML that contains Personalized Views, ThoughtSpot preserves views that exist only in the target environment, appends new views from the imported TML, and updates views present in both. + +For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability in TML]. + +=== Support for Scheduled Liveboards process type in Connection configuration +The connection configuration API endpoints now support `SCHEDULED_LIVEBOARDS` as a process type: + +* `POST /api/rest/2.0/connection/configuration/create` +* `PUT /api/rest/2.0/connection/configuration/{configuration_identifier}/update` + +Administrators can add `SCHEDULED_LIVEBOARDS` as a valid process type for connection configurations, allowing scheduled Liveboard delivery jobs to use an alternative connection configuration, with separate warehouse, credentials, or non-OAuth authentication instead of the parent connection's defaults. + +== Version 26.8.0.cl, August 2026 + +=== Spotter AI APIs + +Spotter memory APIs::: +ThoughtSpot 26.8.0.cl introduces two new REST API v2.0 endpoints for managing Spotter memory programmatically: + +* `POST /api/rest/2.0/ai/memory/import` + +Imports Spotter 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 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 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-import.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. + + +=== 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 C# SDK +ThoughtSpot provides the REST API C# SDK (`ThoughtSpot.RestApi.Sdk`) to help .NET developers interact programmatically with ThoughtSpot REST API v2 endpoints. The SDK targets `net8.0` and is available on link:https://www.nuget.org/packages/ThoughtSpot.RestApi.Sdk[NuGet, window=_blank]. + +For information about how to install and use the SDK, see xref:rest-api-csharp-sdk.adoc[C# SDK for REST APIs]. + +== Version 26.7.0.cl, July 2026 + +=== Spotter AI APIs + +Save chat AI APIs:: +ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates attributes of an existing agent conversation. +* `GET /api/rest/2.0/ai/agent/conversations` + +Retrieves the list of saved agent conversations for the currently authenticated user. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + +Retrieves the full content of a saved conversation with Spotter agent. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates the display title of a saved conversation. +* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +Deletes a saved conversation and all its associated messages. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + +Loads the full answer payload for a specific answer item in an agent conversation. + ++ +For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. + +Save chat settings in conversation create API:: + +The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. + +Agent instructions APIs:: +The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. + +* `PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. + +* `GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. ++ +For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. + +=== Webhooks + +New API endpoint:: +The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. + +Enhancements:: + +* 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 + +The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. + +=== Style customization APIs + +ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. + +Style configuration:: + +* `POST /api/rest/2.0/customization/styles/search` + +Returns the current style configuration at the `CLUSTER` or active `ORG` scope. + +* `POST /api/rest/2.0/customization/styles/update` + +Updates style settings at the `CLUSTER` or `ORG` scope. + +Custom fonts:: + +* `POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. + +* `POST /api/rest/2.0/customization/styles/fonts/search` + +Returns custom fonts uploaded to the instance. + +* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates the display name, weight, style, or color of an existing custom font. + +* `POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. + +Logo export:: + +* `POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive containing the default logo and the wide logo. + +For more information, see xref:customize-style-api.adoc[Style customization APIs]. + +=== Manual translation APIs +The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. + +* `POST /api/rest/2.0/localizations/manual-translation/import` + +Allows importing a CSV file containing translated terms and labels. +* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + +Retrieves all translations for a specific locale as a JSON map. +* `POST /api/rest/2.0/localizations/manual-translation/export` + +Downloads all manually translated terms and labels in the Org context as a CSV file. +* `POST /api/rest/2.0/localizations/manual-translation/delete` + +Deletes all manual translations from the Org. + +For more information, see xref:manual-translation.adoc[Manual translations]. + +=== 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 how to install and use the SDK, see xref:rest-api-python-sdk.adoc[Python SDK]. + +== Version 26.6.0.cl, June 2026 + +=== Spotter AI APIs + +Stop in-progress agent response:: + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + +Stops a Spotter agent response that is currently in progress for a given conversation session. + +For more information, see xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. + +=== Authentication +The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. + +* `POST /api/rest/2.0/auth/configure` + +Enables or disables authentication at cluster or Org level for the specified auth type. +* `POST /api/rest/2.0/auth/search` + +Returns the authentication configuration for the specified auth type at cluster and Org level. + +=== Connection deactivate and activate API [beta betaBackground]^Beta^ + +// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 + +ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: + +* `POST /api/rest/2.0/connections/{connection_identifier}/status` + +Deactivates or activates a connection. + +=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# + +The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: + +Pinned Answer export:: +// SOURCE: SCAL-236681, SCAL-306548 +You can now export a pinned Answer directly from a Liveboard using the Answer report API. +To export a pinned Answer, specify the `viz_guid` parameter in your API request. +Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. ++ +To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. + +Spotter Answer export:: +XLSX and PDF export formats are now supported for Spotter (conversational) Answers. + +Custom PNG dimensions:: +PNG exports now support custom dimensions via the following new parameters: ++ +* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. +* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. + +Display scaling:: +A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. +Valid range: 80–500%. + +Automatic file naming:: +The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). + +Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. +For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer report API documentation]. + +=== Share metadata API: Collections support [beta betaBackground]^Beta^ + +The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. + +To share a Collection, set `metadata_type` to `COLLECTION` in the request body. +For more information, see xref:collections.adoc#share-collection[Share a Collection]. + +== Version 26.5.0.cl, May 2026 + +=== Sync connection metadata attributes +You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. + +=== Spotter APIs + +==== New API endpoints + +The following new endpoints allow sending messages to an active conversation +session with a Spotter agent. + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send` + +Allows sending a message to an active Spotter AI conversation and returns a synchronous response. +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +Allows sending to an active Spotter AI conversation and returns the response as a real-time Server-Sent Events (SSE) stream. + +These new endpoints replace the legacy agent conversation and SSE streaming APIs. + +==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# + +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` + +These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. + +==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# + +The following enhancements have been introduced for the conversation creation operation workflow with the `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint: + +metadata_context:: +To define the conversation context, the API request must include the `metadata_context` parameter with one of the following values: + +* `AUTO_MODE`: Automatically discovers and selects the most relevant datasets for the user's queries. +* `DATA_SOURCE`: Sets the target context as the data source. You must specify at least one data source ID. +** To set a single data source object metadata context, specify a `data_source_identifier`. +** For multi-data source context, specify the `data_source_identifiers`. ++ +[IMPORTANT] +==== +The `data_source` and `guid` attributes are deprecated in the 26.5.0.cl release version. Integrations using these parameters in ThoughtSpot versions 26.2.0.cl through 26.4.0.cl will continue to work until further notice. However, ThoughtSpot recommends using either `AUTO_MODE` or `DATA_SOURCE` with `data_source_identifier` or `data_source_identifiers` for the metadata context. +==== + +Other context options:: +The `answer_context` and `liveboard_context` are removed and no longer supported. Any existing integration or embedding application passing `answer_context` or `liveboard_context` in the request body must update their workflows to use the `AUTO_MODE` or `DATA_SOURCE` option. + +Enable save chat:: +The `enable_save_chat` parameter, when set to `true`, saves the conversation. + +API response:: +The API response now returns the `conversation_identifier`, which is used in all +subsequent send message or SSE streaming calls. + +=== Liveboard report API enhancements [beta betaBackground]^Beta^ +The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: + +* `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. +* `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. + +For more information, see xref:report-apis-v2.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 +The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-import.adoc[TML import documentation]. + +== Version 26.4.0.cl, April 2026 + +=== Variable API endpoints +The following endpoints are introduced for bulk delete and update operations for variables: + +* `POST /api/rest/2.0/template/variables/{identifier}/update-values` + +Assigns multiple values to a variable and sets the scope for variable values in a single API request. +* `POST /api/rest/2.0/template/variables/delete` + +Deletes one or more variables in a single API request. + +These new API endpoints replace the following legacy API endpoints deprecated in 26.4.0.cl. + +* `POST /api/rest/2.0/template/variables/{identifier}/delete` +* `POST /api/rest/2.0/template/variables/update-values` + +Your existing implementation with the legacy API endpoints will continue to work until further notice. However, these endpoints will be removed from ThoughtSpot in a future release. Hence, we recommend updating your workflows to use the API endpoints at your earliest convenience. + +For more information, see xref:variables.adoc[Variable API documentation]. + +=== Metadata parameterization +You can now parameterize multiple fields in a metadata object in a single API request using the `/api/rest/2.0/metadata/parameterize-fields` API endpoint. +This endpoint replaces the legacy `/api/rest/2.0/metadata/parameterize` endpoint, which is deprecated in 26.4.0.cl. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization API documentation]. + +=== Webhook integration +This release introduces the following features and enhancements to the webhook integration workflows: + +Custom HTTP headers in webhook requests:: +Administrators can configure custom HTTP headers to send in webhook requests triggered by ThoughtSpot, in addition to the standard HTTP and authentication headers. You can specify these headers in the `additional_headers` attribute during webhook creation (`/api/rest/2.0/webhooks/create`) and update (`/api/rest/2.0/webhooks/{webhook_identifier}/update`) via REST APIs. + +Webhook connection validation:: +You can now validate a webhook connection by sending a test payload via an API request to the `/api/rest/2.0/system/communication-channels/validate` endpoint. The API returns a response indicating the connection and authentication status for a given webhook connection. + +Webhook monitoring:: +To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. + +For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. + +=== Collections API endpoints + +The following APIs are introduced for Collections: + +* `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + +Creates a new Collection. +* `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + +Searches for a Collection in ThoughtSpot +* `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + +Updates an existing Collection +* `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + +Deletes a Collection + +For more information, see xref:collections.adoc[Collections]. + +=== Email customization API enhancements + +The `template_properties` parameter now has the `hide_logo_url` elements for email template customization. Set it to `true` to entirely hide the logo component in the ThoughtSpot notification emails. + +=== Spotter API enhancements +Spotter AI APIs now support the following error responses: + +* 401 Unauthorized: authentication token is missing, expired, or invalid. +* 403 Forbidden: the authenticated user does not have `CAN_USE_SPOTTER` privilege or view access to the underlying metadata sources. + +=== Pivot table .xlsx exports +The following API endpoints now support pivot tables in `.xlsx` downloads with full visual and structural parity: + +* `POST /api/rest/2.0/report/answer` +* `POST /api/rest/2.0/schedules/create` + +To enable pivot formatting on your ThoughtSpot instance, contact ThoughtSpot Support. + +== Version 26.3.0.cl, March 2026 + +=== Webhook APIs + +The Webhook API allows configuring Amazon S3 buckets as a storage destination for webhook payload delivery. + +* `POST /api/rest/2.0/webhooks/create` + +Configures storage destination for webhook delivery. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +Allows modifying storage configuration for a webhook. +* `POST /api/rest/2.0/webhooks/search` + +Retrieves storage configuration details. + +=== Object privilege APIs +Administrators and users with edit access to data models can now use `/api/rest/2.0/security/metadata/manage-object-privilege` to assign object-level permissions to users and groups and control access to Spotter data model instructions. + +To fetch object privileges for a data model, user, or group, use the `/api/rest/2.0/security/metadata/fetch-object-privileges` API endpoint. + +For more information, see xref:spotter-nl-instructions.adoc#_allowing_access_to_spotter_data_model_instructions[Allowing access to Spotter data model instructions]. + + +=== User API enhancements + +The user APIs now support setting browser language as the default locale for ThoughtSpot users. Administrators can set the `use_browser_language` parameter as the default locale for ThoughtSpot users during the following API operations: + +* When creating a new user via `POST /api/rest/2.0/users/create` + +* When importing users via `POST /api/rest/2.0/users/import` + +* When updating user preferences via `POST /api/rest/2.0/users/{user_identifier}/update` + + +When set to `true`, a user's current locale preference is overridden and the browser's language takes precedence. + +The status of the browser language setting for a given user can also be retrieved using the following API endpoints: + +* `POST /api/rest/2.0/users/search` + +* `POST /api/rest/2.0/users/activate` + +* `GET /api/rest/2.0/auth/session/user` + + +=== Custom token generation API +Note the following changes to request parameters for the `/api/rest/2.0/auth/token/custom` API endpoint: + +* The `filter_rules` parameter on the custom token authentication (`/api/rest/2.0/auth/token/custom`) page in the REST API Playground is no longer available for new configurations. Existing implementations that use `filter_rules` continue to work. However, we strongly recommend migrating to `variable_values` and ABAC via RLS for data security. + +* The `parameter_values` property is supported in the current release but will be deprecated in an upcoming version. Using `parameter_values` for row-level security will be phased out with this deprecation. Therefore, we recommend generating JWTs that pass data security attributes through formula variable attributes instead of `filter_rules` or `parameter_values` for ABAC. + +For more information, see xref:abac-migration-guide.adoc[ABAC JWT migration guide] and xref:abac_rls-variables.adoc[ABAC via RLS]. + +== Version 26.2.0.cl, February 2026 + +=== Security settings APIs +This release introduces the following Security settings APIs: + +* `POST /api/rest/2.0/system/security-settings/configure` + +Allows configuring security settings at the Org level or for all Orgs on a ThoughtSpot instance. +* `POST /api/rest/2.0/system/security-settings/search` + +Gets a list of security settings configured on a specific Org or for all Orgs on a ThoughtSpot instance. + +For more information, see xref:security-settings.adoc[Security Settings]. + +=== Connection API +ThoughtSpot administrators can now revoke OAuth refresh tokens for users who no longer require access to a data warehouse connection via the `/api/rest/2.0/connections/{connection_identifier}/revoke-refresh-tokens` API endpoint. When a token is revoked, the affected user's session for that connection is terminated, and they must re-authenticate to regain access. + +=== Connection configuration API enhancements +You can now include `same_as_parent` and `policy_process_options` attributes in your API request to `/api/rest/2.0/connection-configurations/create` and `/api/rest/2.0/connection-configurations/{configuration_identifier}/update` endpoints. + +The `same_as_parent` parameter specifies if the configuration should inherit settings from its parent. The `policy_process_options` attribute can be used to define additional policy or processing options for the connection, to allow granular control over connection behavior. + +=== Liveboard Report API enhancements +You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. + +For more information, see xref:report-apis-v2.adoc[Report APIs]. + +=== Email customization API enhancements + +The `template_properties` parameter now has two additional elements for email template customization: + +* `contact_support_url` to add a customized link for contacting customer support. +* `hide_contact_support_url` to hide the option of adding a link for customer support. + +=== System configuration API enhancements +The API response from the `/api/rest/2.0/system/config` endpoint indicates whether SAML or Okta authentication is enabled on the system. + +=== User API enhancements + +* `POST /api/rest/2.0/users/import` + +The `preferred_locale` parameter allows configuring the preferred locale for users being imported via API request. +* `POST /api/rest/2.0/users/search` + +The `include_variable_values` parameter in the API request allows including variable values in the search response. The variable values can be assigned for a user via xref:abac_rls-variables.adoc[ABAC tokens] or xref:variables.adoc#_define_values_and_scope_for_variables[variable API documentation]. + +== Version 10.15.0.cl, December 2025 + +=== Spotter APIs + +This release introduces the following Spotter APIs: + +* `POST /api/rest/2.0/ai/instructions/set` + +Allows configuring data model instructions to define how Spotter interprets queries, handles data nuances, and improves responses. +* `POST /api/rest/2.0/ai/instructions/get` + +Gets data model instructions that are currently assigned to a model. +* `POST /api/rest/2.0/ai/data-source-suggestions` + +Retrieves a list of recommended data sources based on the specified query string. + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +=== Variable APIs + +You can now create formula variables using the `/api/rest/2.0/template/variables/create` API endpoint, and assign values and scope to these variables using the `/api/rest/2.0/template/variables/update-values` API endpoint. + +For more information, see xref:variables.adoc[Configure variables]. + +=== ABAC tokens with formula variable attributes +The `/api/rest/2.0/auth/token/custom` API endpoint allows creating a token request with formula variables for ABAC via RLS implementation. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +== Version 10.14.0.cl, November 2025 + +=== New API endpoints + + + +System:: +This release introduces the following endpoints for configuring communication channel preferences. + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. +* `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + +Gets details of the communication channel preferences configured on ThoughtSpot. ++ +For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. + +Webhook:: +The following APIs are introduced for webhook CRUD operations: +* `POST /api/rest/2.0/webhooks/create` +Creates a webhook. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` +Updates the properties of a webhook. +* `POST /api/rest/2.0/webhooks/search` +Gets a list of webhooks configured in ThoughtSpot or in a specific Org. +* `POST /api/rest/2.0/webhooks/delete` +Deletes the webhook. ++ +For more information, see xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. + +Column security rules:: + +* `POST /api/rest/2.0/security/column/rules/update` + +Updates column security rules for a given Table. + +* `POST /api/rest/2.0/security/column/rules/fetch` + +Gets details of column security rules for the tables specified in the API request. + +//// + +Spotter:: +POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse +//// +=== Variable API enhancements + +The variable API enhancements are listed in the following sections. For additional details, see xref:variables.adoc[Define variables]. + +==== Variable creation API + +* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. +* The `sensitive` parameter is renamed as `is_sensitive`. + +==== Variables update APIs [tag redBackground]#BREAKING CHANGE# + +The `/api/rest/2.0/template/variables/update` endpoint is deprecated and replaced with `/api/rest/2.0/template/variables/update-values`. + +To update the properties of a specific variable, use the `/api/rest/2.0/template/variables/{identifier}/update` endpoint and to assign values to one or several variables in a single API call, use the `POST /api/rest/2.0/template/variables/update-values` endpoint. + +==== Variables search API + +* The variables search API endpoint `/api/rest/2.0/template/variables/search` now includes the `value_scope` parameter that allows you to filter the API response by the objects to which the variable is mapped. +* Filtering API response by `EDITABLE_METADATA_AND_VALUES` is no longer supported. + + +=== User API enhancements +The following APIs now support the `variable_values` parameter. The `variable_values` property can be used for user-specific customization. + +* `POST /api/rest/2.0/users/create` +* `POST /api/rest/2.0/users/search` +* `POST /api/rest/2.0/users/activate` + +=== DBT API enhancements +The `/api/rest/2.0/dbt/generate-tml` endpoint supports the `model_tables` attribute to list models and their tables. + +//// + +=== Authentication API +Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API calls. + +//// + +== Version 10.13.0.cl, October 2025 + +=== New API endpoints + +Spotter:: + +* `POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + + + +* `POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +Email customization:: +`POST /api/rest/2.0/customization/email/update` + +Updates an existing email customization. For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== API enhancements +The following APIs were modified to include new parameters: + +TML export:: +The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. + +Email customization:: +The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== Deprecated endpoints + +Spotter:: +The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. + +Email customization:: +The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete`. + + +//// +=== Deprecated endpoints +The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/analytical-questions` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +//// + +== Version 10.12.0.cl, September 2025 + +=== New API endpoints + +The following API endpoints are now available: + +Custom calendar:: +* `POST /api/rest/2.0/calendars/create` + +Creates a custom calendar. +* `POST /api/rest/2.0/calendars/generate-csv` + +Exports a custom calendar in the CSV format. +* `POST /api/rest/2.0/calendars/search` + +Gets custom calendars for the connection ID specified in the API request. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + +Deletes a custom calendar. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + +Updates a custom calendar. + +Connection configuration:: +* `POST /api/rest/2.0/connection-configurations/create` + +Creates an additional configuration to an existing connection to a data warehouse. +* `POST /api/rest/2.0/connection-configurations/search` + +Gets the required connection configuration objects. +* `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` + +Updates an existing connection configuration object. +* `POST /api/rest/2.0/connection-configurations/delete` + +Deletes the connection configuration object. + +=== Enhancements to APIs + +Export API endpoint:: + +* Answer TML: + +The `POST /api/rest/2.0/metadata/tml/export` API endpoint now allows fetching TML for Answer objects that do not have an ID or name assigned. The `session_identifier` and `generation_number` parameters allow you to define the session ID and the Answer generation number in the API request. These optional attributes can be used for unsaved Answers generated from Spotter queries. + +* Table TML: + +The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column security rules for Table TML objects. This attribute will export column security rules only if the object specified in the API request has column security applied and when `export_associated` is set to `true`. + +== Version 10.11.0.cl, July 2025 + +=== Search metadata API enhancements +The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: + +* The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. +* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. +* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. + + +=== System API +The API response generated from the `GET /api/rest/2.0/system/config-overrides` requests now returns the overrides in the `config_override_info` object. + +=== TML API +The API response for the `POST /api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/async/status` now includes the `author_display_name` property. This property shows the display name of user that initiated the asynchronous TML import request. + +=== REST API Java SDK + +The REST API Java SDK library artifacts are now available in the `com.thoughtspot` Maven namespace. If you are using Maven Central to import the REST API SDK artifacts, update the group ID in your `pom.xml` file to `com.thoughtspot` and the artifact ID to `rest-api-sdk`. + +For more information, see xref:rest-api-java-sdk.adoc#_import_the_sdk_to_your_application_environment[REST API Java SDK]. + +== Version 10.10.0.cl, July 2025 + +=== Email template customization APIs +This release introduces the following new endpoints for email template customization: + +* `POST /api/rest/2.0/customization/email` + +Allows you to personalize the ThoughtSpot notification emails content. +* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + +Removes the customizations done for the ThoughtSpot notification emails. +* `POST /api/rest/2.0/customization/email/search` + +Allows searching the email customization configuration if configured for ThoughtSpot. +* `POST /api/rest/2.0/customization/email/validate` + +Validates the email customization configuration if configured for ThoughtSpot. + +=== Group API + +The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: + +* `include_users` + +When set to `true`, it includes user details in the group search API response. +* `include_sub_groups` + +When set to `true`, it includes sub-groups in the group search response. + +=== Schedule API +You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: + +* `POST /api/rest/2.0/schedules/create` +To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. + +== Version 10.9.0.cl, June 2025 + +=== Metadata parameterization and content publishing across Orgs + +This release introduces the following new endpoints for metadata parameterization [beta betaBackground]^Beta^ and content publishing [beta betaBackground]^Beta^ across Orgs. To enable the content publishing feature and the related API operations on your instance, contact ThoughtSpot Support. + +* `POST /api/rest/2.0/metadata/parameterize` [beta betaBackground]^Beta^ + +Allows you to parameterize fields in metadata objects. +* `POST /api/rest/2.0/metadata/unparameterize` [beta betaBackground]^Beta^ + +Allows removing parameterization from fields in metadata objects +* `POST /api/rest/2.0/security/metadata/publish` [beta betaBackground]^Beta^ + +Publish metadata objects to one or several Orgs on an instance. +* `POST /api/rest/2.0/security/metadata/unpublish` [beta betaBackground]^Beta^ + +Removes published metadata objects from the Orgs specified in the API request. +* `POST /api/rest/2.0/template/variables/create` [beta betaBackground]^Beta^ + +Allows creating a template variable which can be used to parameterize fields in a metadata object. +* `POST /api/rest/2.0/template/variables/search` [beta betaBackground]^Beta^ + +Allows searching template variables +* `POST /api/rest/2.0/template/variables/{identifier}/update` [beta betaBackground]^Beta^ + +Allows updating properties of a template variable. +* `POST /api/rest/2.0/template/variables/update` [beta betaBackground]^Beta^ + +Allows you to add, remove, or replace properties of one or several template variables. +* `POST /api/rest/2.0/template/variables/{identifier}/delete` [beta betaBackground]^Beta^ + +Deletes a template variable. + +If your metadata objects are parameterized, you can use the `show_resolved_parameters` to filter the API response from `/api/rest/2.0/connection/search` and `/api/rest/2.0/metadata/search` endpoints to get only the objects with resolved parameterized values. + +=== Liveboard Report API +The Liveboard Report API now allows you to define the following properties: + +* `tab_identifiers` + +Optional parameter to specify the name or GUID of a Liveboard tab to export only the visualizations in that tab. +* `personalised_view_identifier` + +Optional parameter to specify the GUID of the Liveboard personalized view that you want to download. + +In addition to these parameters, you can also define the following properties for PNG downloads: + +* `image_resolution` +* `image_scale` +* `include_header` + +For more information, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API]. + +=== REST API Java SDK + +The REST API Java SDK enables developers to interact programmatically with ThoughtSpot REST APIs from Java applications. It provides a client library with Java methods and classes that map to API endpoints, handle authentication, send API requests, and allow creating and modifying ThoughtSpot resources and objects. + +For information about how to install and use the SDK, see xref:rest-api-java-sdk.adoc[Java SDK for REST APIs]. + + +== Version 10.8.0.cl, April 2025 + +=== New API endpoints + +This version introduces the following endpoints: + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Update object IDs for given metadata objects. + + +[NOTE] +==== +An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. +Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. +==== + +=== Metadata API + +* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: + +** `include_discoverable_objects` + +Allows including Answers and Liveboards that are marked as discoverable by the object owner. +** `metadata_obj_id` + +Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. + +=== TML APIs + +* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. + +* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. + +=== Report APIs +The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. + +For more information, see xref:report-apis-v2.adoc#_override_filters[Override filters]. + +== Version 10.6.0.cl, March 2025 + +=== New metadata API endpoints + +* `POST /api/rest/2.0/metadata/headers/update` + +Updates metadata header for a given list of objects. +* `POST /api/rest/2.0/metadata/worksheets/convert` + +Converts a Worksheet object to a Model. + +=== Report APIs +[tag redBackground]#BREAKING CHANGE# + +Downloading Liveboard reports in the CSV and XLSX file format via `POST /api/rest/2.0/report/liveboard` API endpoint is not supported. The CSV and XLSX `file_format` options have been removed because they were not functioning in the expected manner. + +==== Parameters for regional settings + +The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow users to define the following `regional_settings` attributes: + +* `currency_format` +* `user_locale` +* `number_format_locale` +* `date_format_locale` + +=== Custom object ID in TML and Metadata APIs + +The following API endpoints allow you to specify a custom object ID (`obj_identifier`) in the metadata object properties: + +* `POST /api/rest/2.0/metadata/search` +* `POST /api/rest/2.0/metadata/headers/update` +* `POST /api/rest/2.0/metadata/tml/export` + + +=== TML import API + +The `/api/rest/2.0/metadata/tml/async/import` and `POST /api/rest/2.0/metadata/tml/import` endpoints allow skipping diff check when processing TMLs for imports. The `skip_diff_check` attribute is disabled by default and can be enabled to avoid importing objects that do not have any changes. + +=== API response changes + +The 200 and 201 response body from `POST /api/rest/2.0/ai/answer/create` and `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API calls now includes the `display_tokens` property. + + +== Version 10.5.0.cl, December 2024 + +=== Custom access token API +The `/api/rest/2.0/auth/token/custom` API endpoint allows setting the following attributes in API requests: + +* `auto_create` + +Creates a user if username specified in the API request is not available in ThoughtSpot. By default, the `auto_create` is set to `true`. +* `REPLACE` enum for `persist_option` + +Allows replacing persisted values with new attributes defined in the token generation API request. For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +=== TML import APIs + +TML async import:: + +The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: ++ +* `import_policy` + +Allows you to specify if all objects should be imported during the TML import operation. Valid values are: + +** `PARTIAL_OBJECT` (default) +** `PARTIAL` +** `VALIDATE_ONLY` +** `ALL_OR_NONE` + +* `enable_large_metadata_validation` + +Indicates if the TMLs with large and complex metadata should be validated before the import. ++ +For more information about these attributes, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +TML import API:: + +The `/api/rest/2.0/metadata/tml/import` API also supports setting the `enable_large_metadata_validation` attribute for large and complex metadata objects during TML import. + +TML export API:: + +The `/api/rest/2.0/metadata/tml/export` endpoint now allows you to include additional attributes when exporting TML for an object from ThoughtSpot. The `export_options` allows you to include the following optional attributes: + +* `include_obj_id_ref` + +Specifies whether to export `user_defined_id` of the referenced object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_guid` + +Specifies whether to export the GUID of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. +* `include_obj_id` + +Specifies whether to export the `user_defined_id` of the object. This setting is valid only if the `UserDefinedId` property in TML is enabled. + + +Share metadata:: + +The `email` attribute is now optional in the `POST` request body sent to the `/api/rest/2.0/security/metadata/share` API endpoint. + +Role API:: + +The `/api/rest/2.0/roles/create` API endpoint now allows setting `read_only` attribute to specify if the role is read only. A read-only role cannot be updated or deleted. + +== Version 10.4.0.cl, November 2024 + +=== New API endpoints + +Spotter AI APIs [beta betaBackground]^Beta^ :: + +* `POST /api/rest/2.0/ai/conversation/create` + +Creates a conversation session. +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + +Generates responses for user queries and follow-up questions. +* `POST /api/rest/2.0/ai/answer/create` + +Generates an Answer from a Natural Language Search query. + +Authentication:: +The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. + ++ +ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +Connections:: +The following new API endpoints are available for updating and deleting a connection object: + +* `POST /api/rest/2.0/connections/{connection_identifier}/update` +* `POST /api/rest/2.0/connections/{connection_identifier}/delete` + ++ +ThoughtSpot recommends using these APIs instead of `POST /api/rest/2.0/connection/update` and `POST /api/rest/2.0/connection/delete`. + +TML:: +The following API endpoints are available for asynchronous TML import: + +* `POST /api/rest/2.0/metadata/tml/async/import` + +Validates and imports TML objects asynchronously. Use this API endpoint when importing large metadata objects. +* `POST /api/rest/2.0/metadata/tml/async/status` + +Fetches task status for the async TML import operations. + +For more information, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. + +=== API enhancements + +User session:: + +* The 200 API response for the `/api/rest/2.0/auth/session/user` and `/api/rest/2.0/users/search` is modified to show `access_control_properties`. + +* You can now manage account activation status for IAMv2 users using the following API endpoints: + +** `POST /api/rest/2.0/users/create` + +** `POST /api/rest/2.0/users/{user_identifier}/update` + +Report API:: + +The `POST /api/rest/2.0/report/answer` API endpoint supports downloading an Answer generated by the Spotter AI APIs: + +* `session_identifier` + +Session ID returned in API response by the `/api/rest/2.0/ai/answer/create` or `/api/rest/2.0/ai/conversation/create` endpoint. +* `generation_number` + +Number assigned to the Answer session with Spotter. ++ +If you are downloading an Answer generated by Spotter, you must specify the session ID. The `metadata_identifier` property is not required. + +=== Deprecated features + +Connection APIs:: + +The following connection API endpoints are deprecated: + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` + ++ +Use `POST /api/rest/2.0/connections/{connection_identifier}/update` and `POST /api/rest/2.0/connections/{connection_identifier}/delete` APIs to update and delete a connection object respectively. + +Authentication:: + +The `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs is deprecated. ++ +ThoughtSpot recommends using `/api/rest/2.0/auth/token/custom` API endpoint with `filter_rules` and `parameter_values` to configure user properties for ABAC via tokens. + +== Version 10.3.0.cl, October 2024 + +=== New API endpoint + +You can now create a copy of a Liveboard or Answer object using `/api/rest/2.0/metadata/copyobject` API endpoint. + +== Version 10.1.0.cl, August 2024 + +=== New API endpoints + +* `POST /api/rest/2.0/metadata/tml/export/batch` + +Exports a batch of TML for user, user group, or Role objects. + +=== Security APIs +The `/api/rest/2.0/security/metadata/fetch-permissions` API endpoint supports the following parameters: + +* `record_offset` + +Specifies the starting record number from which the records for each metadata type will be included in the API response. +* `record_size` + +Specifies the number of records that should be included for each metadata type in the API response. +* `permission_type` + +Specifies the type of permission. Valid values are: +** `EFFECTIVE` - If user permission to the metadata objects is granted by the privileges assigned to the groups to which they belong. +** `DEFINED` - If a user or user group received access to metadata objects via object sharing by another user. + +== Version 10.0.0.cl, July 2024 + +=== Roles + +You can now assign the `CAN_MANAGE_VERSION_CONTROL` role using any of the following API endpoints: + +* `POST /api/rest/2.0/roles/create` +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +The `CAN_MANAGE_VERSION_CONTROL` Role privilege is required for Git integration with ThoughtSpot. + +== Version 9.12.0.cl, May 2024 + +=== New features + +Authentication API:: + +* `/api/rest/2.0/auth/token/validate` + +Validates the authentication token of the logged-in user. + +TML API:: +The export TML API requests now support the following parameters: ++ +* `export_schema_version` + +Specifies the schema version for datasets during TML export. By default, the API request uses v1 schema for Worksheet TML export. For Models, set `export_schema_version` to `v2`. + +* `export_dependent` + +Allows exporting dependent Tables while exporting a Connection. +* `export_connection_as_dependent` + +Specifies if a Connection can be exported as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard. This parameter works only when `export_associated` is set to `true` in the API request. + +=== Deprecated features + +Token authentication APIs:: + +The `jwt_user_options` object property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` is deprecated. Use the `user_parameters` property to define security entitlements to a user session. For more information, see xref:abac-user-parameters.adoc[ABAC via token][beta betaBackground]^Beta^. + +== Version 9.10.5.cl, April 2024 + +=== New features + +Authentication:: + +The `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` API endpoints support generating JWT token for Attribute-Based Access Control. The `user_parameters` object allows you to define security entitlements for a given user. + +For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. + +Roles:: + +The `/api/rest/2.0/roles/create` and `/api/rest/2.0/roles/{role_identifier}/update` API endpoints support assigning the following privileges to a Role for granular data access control and management: + +* `CAN_MANAGE_CUSTOM_CALENDAR` +* `CAN_CREATE_OR_EDIT_CONNECTIONS` +* `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` + +DBT:: + +You can now use `file_content` to upload DBT Manifest and Catalog artifact files as a ZIP file in your API requests to the `/api/rest/2.0/dbt/dbt-connection`, `/api/rest/2.0/dbt/generate-tml`, `/api/rest/2.0/dbt/generate-sync-tml`, and `/api/rest/2.0/dbt/update-dbt-connection` endpoints. This field is required if the `import_type` parameter is set to `'ZIP_FILE'`. + +Connections:: + +* `/api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier}` + +Validates the differences in Connection metadata between Cloud Data Warehouse and ThoughtSpot. +* `/api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier}` + +Downloads the connection metadata differences identified between Cloud Data Warehouse and ThoughtSpot. + +Logs:: +The `/api/rest/2.0/logs/fetch` API endpoint allows fetching all logs in a single API request. To get all logs, set `get_all_logs` to `true`. + +Share metadata:: + +The `/api/rest/2.0/security/metadata/share` API supports the following new properties: + +* `notify_on_share` + +Sends a share notification to the email addresses specified in the API request. +* `has_lenient_discoverability` + +Sets the shared metadata object as a discoverable object. Applies to Saved Answers and Liveboards only. + +Users:: +The `trigger_activation_email` property allows you to specify if an activation email must be sent to the user's email address in the user creation request to the `/api/rest/2.0/users/create` endpoint. + +=== Deprecated features + +Version Control APIs:: + +The following parameters in `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` are deprecated from 9.10.5.cl onward: + +* `default_branch_name` + +Replaced by `commit_branch_name` +* `guid_mapping_branch_name` + +Replaced by `configuration_branch_name` + +For more information, see xref:version_control.adoc[Git integration and version control]. + +== Version 9.10.0.cl, March 2024 + +=== New API endpoints + +DBT:: + +* `POST /api/rest/2.0/dbt/dbt-connection` + +Creates a DBT connection. +* `POST /api/rest/2.0/dbt/generate-tml` + +Generates Worksheets and Tables for a given DBT connection. +* `POST /api/rest/2.0/dbt/generate-sync-tml` + +Synchronizes the existing TML of data models and Worksheets and imports them to ThoughtSpot. +* `POST /api/rest/2.0/dbt/search` + +Gets a list of DBT connection objects for a given user or Org. +* `POST /api/rest/2.0/dbt/{dbt_connection_identifier}` + +Updates a DBT connection. + +System:: + +`GET api/rest/2.0/system/banner` + +Gets cluster maintenance status and banner text. + ++ +For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[Cluster maintenance and upgrade]. + +== Version 9.8.0.cl, January 2024 + +The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. + +== Version 9.7.0.cl, November 2023 + +=== Version Control APIs + +This release introduces the following enhancements to the Version Control API endpoints: + +==== Git connection creation and update APIs + +The `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints include the following enhancements: + +New parameters:: + +* `commit_branch_name` + +Allows configuring a commit branch for Git connections on your ThoughtSpot instance. ThoughtSpot recommends using `commit_branch_name` instead of `default_branch_name` in the API calls to prevent users from committing changes to the default deployment branch. +* `configuration_branch_name` + +Allows configuring a separate Git branch for storing and maintaining configuration files, such as GUID mapping and commit tracking files. If the `configuration_branch_name` property is defined, the `guid_mapping_branch_name` parameter is not required. + +Modified parameters:: +The `enable_guid_mapping` parameter is enabled by default. + +Separate branches for Orgs:: +If you are using Orgs and want to move content between these Orgs using version control APIs, ensure that you set a separate Git branch for each Org. If two Orgs are connected to the same Git `repository_url`, the `POST /api/rest/2.0/vcs/git/config/create` and `POST /api/rest/2.0/vcs/git/config/update` API endpoints do not support configuring the same branch name for these Orgs. + +Deprecation notice:: + +The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. + +For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. + +==== Commit API + +The `POST /api/rest/2.0/vcs/git/branches/commit` API endpoint allows the following new attribute in the request body: + +* `delete_aware` ++ +When set to true, the system runs a check between the objects and files in the Git branch and destination environment or Org. If an object exists in the Git branch, but not the destination environment or Org, it will be deleted from the Git branch during the commit operation. + +For more information, see xref:version_control.adoc#_commit_files_and_changes[Commit files]. + +==== Deploy API + +Note the following changes: + +* The `branch_name` attribute is now mandatory in the `POST /api/rest/2.0/vcs/git/commits/deploy` API requests. Ensure that you specify the name of the Git branch from which the commits can be picked and deployed on the destination environment or Org. + +* After a successful deployment, a tracking file is generated with the `commit_id` and saved in the Git branch that is used for storing configuration files. The `commit_id` recorded in the tracking file is used for comparing changes when new commits are pushed in the subsequent API calls. + +For more information, see xref:version_control.adoc#_deploy_commits[Deploy commits]. + +=== User API + +The following new API endpoints are introduced for user account management: + +* `POST /api/rest/2.0/users/activate` + +Activates an inactive user account. + +* `POST /api/rest/2.0/users/deactivate` + +Deactivates a user account. + +=== Support for sorting of columns at runtime +The following data API endpoints now support runtime sorting of columns: + +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + + +For more information, see xref:runtime-sort.adoc[Runtime sorting of columns]. + +== Version 9.6.0.cl, October 2023 + +=== New API endpoints + +* `POST /api/rest/2.0/customization/custom-actions/search` + +Gets custom action objects +* `POST /api/rest/2.0/customization/custom-actions` + +Creates a custom action +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update` + +Updates the properties of a custom action object. +* `POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete` + +Deletes a custom action + +=== SDK for TypeScript + +ThoughtSpot provides TypeScript SDK to help client applications call REST APIs using TypeScript. You can download the SDK from the link:https://www.npmjs.com/package/@thoughtspot/rest-api-sdk?activeTab=readme[NPM site, window=_blank]. + +== Version 9.5.0.cl, September 2023 + +=== New API endpoints for Role-Based Access Control [beta betaBackground]^Beta^ + +* `POST /api/rest/2.0/roles/search` + +Gets details of role objects available in the ThoughtSpot system. +* `POST /api/rest/2.0/roles/create` + +Creates a role and assigns privileges +* `POST /api/rest/2.0/roles/{role_identifier}/update` + +Updates the properties of a given role +* `POST /api/rest/2.0/roles/{role_identifier}/delete` + +Removes a role object from the ThoughtSpot system + +For more information, see xref:roles.adoc[Role-based access control]. + +[NOTE] +==== +The roles APIs work only if the Role-Based Access Control (RBAC) [beta betaBackground]^Beta^ feature is enabled on your instance. The RBAC feature is turned off by default. To enable this feature, contact ThoughtSpot Support. +==== + +=== Enhancements and API modifications + +Support for runtime parameter overrides:: +The following data and report API endpoints support applying runtime parameter overrides: +* `POST /api/rest/2.0/searchdata` + +* `POST /api/rest/2.0/metadata/liveboard/data` + +* `POST /api/rest/2.0/metadata/answer/data` + +* `POST /api/rest/2.0/report/liveboard` + +* `POST /api/rest/2.0/report/answer` + +Git integration support for Orgs:: + +The Version Control API endpoints support using Orgs as disparate deployment environments. You can create separate Orgs for `dev`, `staging`, and `prod` and integrate these environments with a GitHub repo. + ++ +For more information, see xref:version_control.adoc[Git integration and version control]. + +=== Response code change [tag redBackground]#BREAKING CHANGE# + +The following endpoints now return the 204 response code instead of 200. The 204 code does not return a response body. This change may affect your current implementation, so we recommend that you update your code to avoid issues. + +* `POST /api/rest/2.0/connection/delete` +* `POST /api/rest/2.0/connection/update` +* `POST /api/rest/2.0/users/{user_identifier}/update` +* `POST /api/rest/2.0/users/{user_identifier}/delete` +* `POST /api/rest/2.0/users/change-password` +* `POST /api/rest/2.0/users/reset-password` +* `POST /api/rest/2.0/users/force-logout` +* `POST /api/rest/2.0/groups/{group_identifier}/update` +* `POST /api/rest/2.0/groups/{group_identifier}/delete` +* `POST /api/rest/2.0/metadata/delete` +* `POST /api/rest/2.0/orgs/{org_identifier}/update` +* `POST /api/rest/2.0/orgs/{org_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/delete` +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +* `POST /api/rest/2.0/security/metadata/assign` +* `POST /api/rest/2.0/security/metadata/share` +* `POST /api/rest/2.0/system/config-update` +* `POST /api/rest/2.0/tags/{tag_identifier}/update` +* `POST /api/rest/2.0/tags/{tag_identifier}/delete` +* `POST /api/rest/2.0/tags/assign` +* `POST /api/rest/2.0/tags/unassign` +* `POST /api/rest/2.0/vcs/git/config/delete` +* `POST /api/rest/2.0/auth/session/login` +* `POST /api/rest/2.0/auth/session/logout` +* `POST /api/rest/2.0/auth/token/revoke` + + +== Version 9.4.0.cl, August 2023 + +=== API endpoints to schedule and manage Liveboard jobs + +* `*POST* /api/rest/2.0/schedules/create` + +Creates a scheduled job for a Liveboard +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/update` + +Updates a scheduled job +* `*POST* /api/rest/2.0/schedules/search` + +Gets a list of Liveboard jobs configured on a ThoughtSpot instance +* `*POST* /api/rest/2.0/schedules/{schedule_identifier}/delete` + +Deletes a scheduled job. + +For more information, see link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fschedules%2Fsearch-schedule[REST API v2.0 Reference]. + +=== API to fetch authentication token + +The `GET /api/rest/2.0/auth/session/token` API endpoint fetches the current authentication token used by the currently logged-in user. + +=== Version Control API enhancements + +* The following Version Control API endpoints support generating and maintaining a GUID mapping file on a Git branch connected to a ThoughtSpot instance: + +** `*POST* /api/rest/2.0/vcs/git/config/create` +** `*POST* /api/rest/2.0/vcs/git/config/update` + +=== User and group API enhancements + +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` and `**POST** /api/rest/2.0/groups/{group_identifier}/update` support specifying the type of operation API request. For example, if you are removing a property of a user or group object, you can specify the `operation` type as `REMOVE` in the API request. +* The `**POST** /api/rest/2.0/users/{user_identifier}/update` allows you to define locale settings, preferences, and other properties for a user object. + +== Version 9.3.0.cl, June 2023 + +The following Version Control [beta betaBackground]^Beta^ API endpoints are now available for the lifecycle management of content on your deployment environments: + +* `*POST* /api/rest/2.0/vcs/git/config/search` +* `*POST* /api/rest/2.0/vcs/git/commits/search` +* `*POST* /api/rest/2.0/vcs/git/config/create` +* `*POST* /api/rest/2.0/vcs/git/config/update` +* `*POST* /api/rest/2.0/vcs/git/config/delete` +* `*POST* /api/rest/2.0/vcs/git/branches/commit` +* `*POST* /api/rest/2.0/vcs/git/commits/{commit_id}/revert` +* `*POST* /api/rest/2.0/vcs/git/branches/validate` +* `*POST* /api/rest/2.0/vcs/git/commits/deploy` + +For more information, see xref:version_control.adoc[Version control and Git integration]. + +== Version 9.2.0.cl, May 2023 + +New endpoints:: + +* System ++ +** `POST /api/rest/2.0/system/config-update` + +Updates system configuration ++ +** `GET /api/rest/2.0/system/config-overrides` + +Gets system configuration overrides + +* Connections ++ +** POST /api/rest/2.0/connection/create + +Creates a data connection + +** `POST /api/rest/2.0/connection/search` + +Gets a list of data connections + +** `POST /api/rest/2.0/connection/update` + +Updates a data connection + +** `POST /api/rest/2.0/connection/delete` + +Deletes a data connection + +Enhancements:: + +* Support for runtime filters and runtime sorting of columns + +The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_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` + +* Search users by their favorites ++ +The `/api/rest/2.0/users/search` API endpoint allows searching users by their favorite objects and home Liveboard setting. + +* Ability to log in to a specific Org ++ +The `/api/rest/2.0/auth/session/login` API endpoint now allows ThoughtSpot users to log in to a specific Org context. + +== Version 9.0.0.cl, February 2023 + +The ThoughtSpot Cloud 9.0.0.cl release introduces the REST API v2.0 endpoints and Playground. For information about REST API v2.0 endpoints and Playground, see the following articles: -... [truncated, 11,939 chars total] \ No newline at end of file +* xref:rest-api-v2.adoc[REST API v2.0] +* xref:rest-api-v2-getstarted.adoc[Get started with REST API v2.0] +* xref:rest-api-v2-reference.adoc[REST API v2.0 reference] +* xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison] From dd33c8942b9e527b0fbba1254447809f868f5a84 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:58:25 +0530 Subject: [PATCH 044/169] docs: restore full REST API v2 changelog and add November 2026 section with all new APIs From bb69225994a39e873f2c59d4e8723c314ac38893 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:59:25 +0530 Subject: [PATCH 045/169] docs: restore full What's New and add complete November 2026 section incl. Usage Data APIs --- modules/ROOT/pages/whats-new.adoc | 1031 ++++++++++++++++++++++++++++- 1 file changed, 1030 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index ec6077f68..416bfdc7c 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -1 +1,1030 @@ -Unknown tool: github_get_file \ No newline at end of file += What's new +:toc: true +:toclevels: 1 +:page-title: What's new +:page-pageid: whats-new +:page-description: New features and enhancements + +This page lists new features, enhancements, and deprecated functionality introduced for ThoughtSpot Embedded instances in 2026. For information about the features introduced in the previous release versions, see xref:whats-new-prev-history.adoc[release history]. + +// ============================================================ +// VERSION TEMPLATE — copy this block for each new release +// ============================================================ +// +// +// [.version-badge.breaking]#Breaking# / +// [.version-badge.new]#New# / +// [.version-badge.deprecated]#Deprecated# / +// [.version-badge.fixed]#Fixed# +// +// *API version string:* `?api-version=YYYY-MM-DD` +// *Status:* Current / Supported / Deprecated +// *Affects:* Developers, Administrators, End Users +// ============================================================ + + +== November 2026 + + **Release version**: ThoughtSpot Cloud 26.11.0.cl + + *Upgrade notes*: Includes API rate limit enforcement and new REST API endpoints. Review the details in this page and the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + + *Recommended SDK versions*: Visual Embed SDK v1.54.0 or later + + [.cl-table, cols="2,4", frame=none, grid=none] + |=== + a| + [.cl-label] + *Version 26.11.0.cl* + + a| + + [discrete] + ==== SpotterX embed support + ThoughtSpot introduces SpotterX, the next-generation Spotter experience, with full embedding support in the Visual Embed SDK. SpotterX provides a redesigned conversational interface with improved chat layout, enhanced branding controls, and new configuration options for embedded applications. + + SpotterX is opt-in. Set `spotterVersion` to `SpotterVersion.SpotterX` in your `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` configuration to enable it. Existing Spotter embeds remain unchanged unless explicitly opted in. + + For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. + + [discrete] + ==== API rate limit enforcement + The Org-level rate limit of 50 requests per second (RPS) per Org, announced in 26.10.0.cl, is now enforced. Requests exceeding the limit receive `HTTP 429: Too Many Requests`. This applies to all public REST API v2.0 endpoints on instances with Orgs enabled and operates independently of the existing cluster-level limit of 100 RPS per client IP. + + For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. + + [discrete] + ==== Link Customization APIs + [.version-badge.new]#New# + + Two new REST API v2.0 endpoints allow you to manage the URL templates ThoughtSpot uses when generating shareable links. Use these APIs to redirect links in scheduled emails, Share dialogs, and alerts to your embedding application. + + * `POST /api/rest/2.0/customization/links/search` + * `POST /api/rest/2.0/customization/links/update` + + For more information, see xref:link-customization-api.adoc[Link Customization APIs]. + + [discrete] + ==== Input Table APIs + [.version-badge.new]#New# + + Five new REST API v2.0 endpoints allow you to create and manage input tables — user-editable tables stored in an external CDW and linked to a ThoughtSpot model. + + For more information, see xref:input-table-api.adoc[Input Table APIs]. + + [discrete] + ==== Spotter Usage Data APIs [Beta] + [.version-badge.new]#New# + + Four new REST API v2.0 endpoints allow you to manage Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. Use these APIs to provision limits, monitor consumption, and reset usage. + + * `GET /api/rest/2.0/ai/usage-data/user` + * `POST /api/rest/2.0/ai/usage-data/search` + * `POST /api/rest/2.0/ai/usage-data/update` + * `POST /api/rest/2.0/ai/usage-data/delete` + + For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data APIs]. + + [discrete] + ==== Share Analyst API + [.version-badge.new]#New# + + The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. + + [discrete] + ==== Default RBAC enablement for new clusters + Starting with 26.11.0.cl, Role-Based Access Control (RBAC) is enabled by default on all new ThoughtSpot Cloud clusters. Existing clusters are not affected. For more information about RBAC, see xref:rbac.adoc[Role-based access control]. + + [discrete] + ==== New locale support + ThoughtSpot now supports four additional locales for UI localization: + + * Turkish (`tr-TR`) + * Polish (`pl-PL`) + * Romanian (`ro-RO`) + * Ukrainian (`uk-UA`) + + For more information, see xref:locale-setting.adoc[Customize locale]. + + [discrete] + ==== Host-controlled tooltip rendering + The Visual Embed SDK now supports host-controlled tooltip rendering for embedded charts. You can use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. + + [discrete] + ==== Programmatic Liveboard filter overrides [Beta] + [.version-badge.new]#Beta# + + You can now programmatically update Liveboard filter values at runtime using URL-based filter overrides, without re-rendering the entire component. + + |=== + + == October 2026 + +**Release version**: ThoughtSpot Cloud 26.10.0.cl + +*Upgrade notes*: ⚠️ Includes a deprecation and an upcoming change to API rate limits. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.53.0 or later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.10.0.cl* + +a| + +[discrete] +==== Spotter Analyst + +Embed Spotter Analyst:: +You can now embed a single, pinned Spotter Analyst in your application using the Visual Embed SDK. The `spotterAnalystConfig.analystId` property in `SpotterEmbed` locks the embed to one governed Analyst experience. For more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst]. + +Spotter Analyst APIs:: +Spotter Analysts are governed AI agents you can create, configure, and manage via the REST API. Four new endpoints are available under `/api/rest/2.0/ai/agent/analysts/` to create, search, update, and delete Analysts programmatically. Each Analyst is configured with a name, description, one or more data sources, and optional instructions, MCP connectors, and starter prompts. For more information, see xref:spotter-analyst-api.adoc[Spotter Analyst API]. + +--- + +[discrete] +==== Pinning Spotter conversations +Users can now pin Spotter conversations in the embedded view and through the REST API, so that pinned conversations appear at the top of the conversation list for quick access. For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations] and xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Spotter conversation APIs]. + +--- + +[discrete] +==== Feature management through APIs +ThoughtSpot now supports programmatic feature management with new REST API v2 endpoints available under `/api/rest/2.0/configurations/features/`. Cluster and Org admins can search feature configurations, assign features to Orgs, and set feature values without using the link:https://docs.thoughtspot.com/cloud/latest/admin-portal-2#_feature_management[new Admin portal, window=_blank]. For more information, see xref:feature-management-api.adoc[Feature Management]. + +--- + +[discrete] +==== Liveboard enhancements +* *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# ++ +Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]. + +* *Host Events* ++ +** The xref:HostEvent.adoc#_getgroups[`HostEvent.GetGroups`] event returns group details for the Liveboard, and the `applicability` attribute on `HostEvent.UpdateFilters` and `HostEvent.UpdateParameters` scopes filter updates to a specific tab or group. For more information, see xref:embed-events.adoc[Events and app interactions]. +** The xref:HostEvent.adoc#_openparameter[`HostEvent.OpenParameter`] event opens the parameter panel for a specific parameter on the Liveboard. It accepts an optional `applicability` object to scope the action to a tab or group. + +* *Centralized filter modal* in Liveboards is now generally available and enabled by default on ThoughtSpot embedded instances. + +* *Column security rules on Liveboards* ++ +Liveboards that were previously blocked by column security rules (CSR) now open and work normally, with column security fully enforced, including in embedded Liveboards. Filter values from inaccessible columns are masked instead of blocking the Liveboard, and scheduled Liveboard deliveries apply CSR separately for each recipient. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards]. + +--- + +[discrete] +==== HostEvent v1 framework deprecated [.version-badge.deprecated]#Deprecated# +Starting from ThoughtSpot Cloud 26.10.0.cl, the HostEvent v1 framework is deprecated and replaced by the HostEvent v2 framework, which provides context-aware event routing and stricter payload validation. If your embedded application uses HostEvent objects to trigger actions, evaluate the event behavior and its impact on your custom workflows in a development environment. For more information, see xref:deprecated-features.adoc#hostEventv1[HostEvent v1 framework deprecation] and the xref:hosteventsv2-migration.adoc[HostEvent v2 migration guide]. + +--- + +[discrete] +==== Upcoming changes to API rate limits +Starting from 26.11.0.cl, ThoughtSpot will enforce an API rate limit of 50 requests per second (RPS) per Org for all public REST API endpoints on instances with Orgs. This Org-level limit operates independently of the existing cluster-level limit of 100 RPS per client IP. + +ThoughtSpot recommends reviewing your existing API integrations to identify any workflows that may exceed 50 RPS within a single Org. Where possible, implement request throttling, and retry with exponential backoff when you receive an `HTTP 429: Too Many Requests` response. If your workflows require a higher rate limit, contact ThoughtSpot Support to discuss your requirements. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. + +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.53.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. + +--- + +[discrete] +==== REST API +For information about REST API v2.0 enhancements in this release, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|=== + + +== September 2026 + +**Release version**: ThoughtSpot Cloud 26.9.0.cl + +*Upgrade notes*: No breaking changes in this release. + +*Recommended SDK versions*: Visual Embed SDK v1.52.0 or later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.9.0.cl* + +a| + +[discrete] +==== Full application embed + +Default page settings:: +You can now embed Collections list page and set it as the default landing page using `Page.Collections` enumeration value. For more information, see xref:set-default-page.adoc#_set_the_default_page_using_pageid[Customizing default page]. + +Navigation panel customization:: +Embed developers can include *Collections* as a navigation option in the left navigation panel in full application embeds. For more information, see xref:full-app-customize.adoc[Customize the embedded ThoughtSpot experience]. + +UI experience:: +The classic V1 and V2 navigation and home page experience modes are no longer supported. All embedded sessions use V3 navigation and homepage by default and the V4 homepage experience if enabled in the embed. + +--- + +[discrete] +==== Spotter embed + +Spotter visual experience enhancements:: +The Spotter interface is redesigned and enhanced to provide a more streamlined and conversational experience to embedding application users. The classic Spotter interface remains the default for existing deployments, and you can choose to enable the new experience using the `updatedSpotterExperience` parameter in the SDK. For more information, see xref:customize-spotter-embed.adoc#_spotter_interface_in_the_embedded_view[Spotter experience]. + +Spotter conversation sharing in embedded views:: +Users can now share saved Spotter conversations with other users and groups directly from the embedded Spotter interface or via REST APIs. For more information, see xref:customize-spotter-sharing.adoc[Customize Spotter conversation sharing] and xref:spotter-agent-sharing-apis.adoc[Sharing Spotter conversations]. + +--- + + +[discrete] +==== Browser history management in embedded application +When ThoughtSpot is embedded in a host application, internal navigation pushes new entries onto the browser history stack, causing the browser *Back* button to step through ThoughtSpot's internal pages before returning to the host application. To override the browser history behavior for embedding application users and prevent users from getting trapped in back-button loops inside the embedded iframe environment, set `overrideHistoryState` in the Visual Embed SDK. + +--- + + +[discrete] +==== Lazy loading enabled by default for full-height embeds +To improve the initial load performance of large Liveboards, lazy loading is now enabled by default when `fullHeight` is set to `true`. For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of Liveboard visualizations]. + +--- + +[discrete] +==== Custom app scheme allowlisting for mobile embeds +ThoughtSpot now supports adding custom app schemes such as `capacitor://localhost` and `ionic://localhost` to the CSP and CORS allowlist. This allows mobile applications built with hybrid frameworks such as Capacitor and Ionic to embed ThoughtSpot content. For more information, see xref:security-settings.adoc#custom-app-schemes[Security settings]. + +--- + +[discrete] +==== Upcoming changes to `EmbedEvent.Error` framework +In the upcoming ThoughtSpot Cloud 26.10.0.cl and Visual Embed SDK 1.53.0 versions, `EmbedEvent.Error` will include a `severity` field that categorizes errors into three levels, `SEV1`, `SEV2`, and `SEV3`. ThoughtSpot recommends reviewing your error handling logic to prepare for this change. For more information, see xref:embed-event-error-best-practices.adoc[Handling embed errors]. + +--- + + +[discrete] +==== Personalized Views TML portability + +The Personalized Views TML portability feature is now GA and enabled on all ThoughtSpot Embedded instances. For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability]. + +--- + + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.52.0, see xref:api-changelog.adoc[Visual Embed SDK changelog]. + +--- + + +[discrete] +==== REST API v2 +This release introduces new API endpoints for sharing Spotter conversations, managing Snowflake Semantic integrations, and other enhancements. +For more information, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + +== 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:customize-spotter-analysts.adoc#_spotter_analysts[Customize Spotter Analysts]. + +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:customize-spotter-chat-experience.adoc#_spotter_starter_prompts[Enable starter prompts in Spotter]. + +--- + +[discrete] +==== Liveboard embedding enhancements +The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: + +* Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + +xref:customize-liveboard-filters.adoc#filter-visibility[Hides filters] that are not relevant to the displayed visualization in a tab. +* Compact header (`isLiveboardCompactHeaderEnabled`) + +Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:customize-liveboard-layout.adoc#compact-header[compact Liveboard header]. +* Cover page filtering options (`coverAndFilterOptionInPDF`) + +Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. +* Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + +Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. +* Filter interactivity (`isEnhancedFilterInteractivityEnabled`) + +Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. + +--- + +[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:deprecated-features.adoc#v1-v2-exp-fullApp-embed[V1 and V2 deprecation]. + +--- + +[discrete] +==== Wide logo dimension [.version-badge.breaking]#Breaking change# +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#logo-change[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-import.adoc#personalized-views-portability[Personalized Views portability]. + +--- + +[discrete] +==== Discoverability checkbox deprecation [.version-badge.breaking]#Breaking change# +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#liveboardDiscoverable[Deprecation announcements]. + +--- + +[discrete] +==== SpotterCode widget for documentation assistance +This developer documentation site now includes a SpotterCode AI assistant panel that replaces the earlier *AskDocs* feature. When you open the assistant panel, it displays prebuilt starter prompts relevant to the page you are currently viewing and allows you to explore topics instantly. You can also type your own questions about embedding, REST APIs, SDK configuration, and developer guides. For more information, see xref:spottercode.adoc[SpotterCode documentation]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.51.0 includes new features and enhancements for Spotter Analysts, starter prompts, 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 + +*Upgrade notes*: Includes breaking changes to SpotterCode + +*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.7.0.cl* + +a| +[discrete] +==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# +You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. + +For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +--- + +[discrete] +==== Spotter embedding + +Spotter file upload in embedded apps:: +Applications embedding the Spotter interface can now allow their users to xref:customize-spotter-chat-experience.adoc#fileUpload[upload files directly in the Spotter chat panel]. + +Spotter conversation history:: +You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +Spotter Agent instructions:: +You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. + +--- + +[discrete] +==== Focused home page experience [earlyAccess eaBackground]#Early Access# + +In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +--- + +[discrete] +==== SpotterCode authentication and workflow execution [.version-badge.breaking]#Breaking# +SpotterCode now supports authenticated sessions with your ThoughtSpot instance. When connecting your MCP client to the SpotterCode endpoint, you are now prompted to log in using your organization's identity provider. After authentication, SpotterCode can make ThoughtSpot API calls on your behalf. + +For more information, see the documentation on xref:spottercode.adoc#_mcp_server_endpoints[SpotterCode MCP Server] and xref:spottercode-integration.adoc#_authenticate_spottercode[Authenticating SpotterCode]. + +--- + +[discrete] +==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# + +The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, provides a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically and accelerates building code and iterating embed configurations. + +For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. + +--- + +[discrete] +==== Webhooks enhancements + +ThoughtSpot introduces the following features and enhancements for webhook configuration and management: + +* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + +The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. +* Storage configuration retrieval + +The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. +* GCS storage configuration for webhook delivery + +Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. +* Webhook activation and deactivation + +You can enable or disable a webhook connection in the UI or through REST API. +* Selective configuration reset + +The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. + +--- + + +[discrete] +==== 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. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + +== June 2026 + +**Release version**: ThoughtSpot Cloud 26.6.0.cl + +*Upgrade notes*: No breaking changes. + +*Recommended SDK versions*: Visual Embed SDK v1.49.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.6.0.cl* + +a| +[discrete] +==== Chart and table overrides [.version-badge.new]#New# +You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: + +* Chart overrides + +Control legend visibility and position, data label display and per-column filter +thresholds, regression lines, grid lines, axis range and label settings, series +colors, and conditional formatting rules including font and background styling. +* Table overrides + +Control column visibility, text wrapping, row height and padding density, table +theme, and column summary visibility with per-column exceptions. + +For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. + +--- + +[discrete] +==== Spotter AI and embedding enhancements [.version-badge.new]#New# + +This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. + +* Spotter embedding: + +Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. +* Spotter AI APIs: + +//** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. + New API endpoint xref:spotter-agent-conversation-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. + +--- + +[discrete] +==== Developer page enhancements +The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: + +* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. +* Removal of REST API v1 + +The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. +* Removal of GraphQL playgrounds + +The menu link to the GraphQL playground has been removed from the UI. + +[discrete] +==== 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]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|=== + + +== May 2026 + +**Release version**: ThoughtSpot Cloud 26.5.0.cl + +*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + +*Recommended SDK versions*: Visual Embed SDK v1.48.0 and later + + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.5.0.cl* + +a| + + +[discrete] +==== Liveboard downloads + +Continuous Liveboard PDF export [beta betaBackground]^Beta^:: +In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. + +Liveboard download in XLSX and CSV formats:: +Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. + +Excel exports for pivot tables:: +Pivot table visualizations can now be exported to Excel format. + +For more information, see xref:liveboard-data-downloads.adoc#liveboard-download-options[Liveboard download options]. + +--- + +[discrete] +==== Visualization edit interface within the Liveboard view + +Users can now edit the underlying query of an answer directly within the Liveboard. When this feature is enabled, the edit button for visualization appears in the answer's floating toolbar when the Liveboard is opened in the edit mode. Clicking the edit button opens the Answer interface preloaded with the answer's current query context. You can make the edits and save the changes without leaving the Liveboard. + +--- + +[discrete] +==== KPI charts in embedded Liveboards + +Embedded Liveboards support advanced controls KPI chart customization. For more information, see link:https://docs.thoughtspot.com/cloud/latest/chart-kpi#advanced[KPI charts]. + +--- + +[discrete] +==== Per-org and per-user timezone control via variables [beta betaBackground]^Beta^ + +You can centrally control timezone behavior per org and per user in embedded deployments using the new template variable `ts_user_timezone` and Variable APIs. + +For multi-org and multi-tenant environments, each tenant org and user can be configured independently, guaranteeing isolation and consistency of time-based analytics across regions. Administrators can reference the timezone variable in formulas to render and filter timestamp data correctly for each embedded user, without separate content per region. + +--- + +[discrete] +==== Timezone-aware keyword filtering [beta betaBackground]^Beta^ +ThoughtSpot now supports resolving relative date and time keywords, such as `today`, `yesterday`, and `last 7 days`, using a configurable per-user or per-Org timezone, instead of the system default timezone on a ThoughtSpot instance. This feature eliminates timezone-based inconsistencies in multi-region embedded deployments and removes the need for custom workarounds. + +For more information, see xref:timezone.adoc[Timezone-aware keywords and filters]. + +[NOTE] +==== +The timezone awareness feature is in Beta and disabled by default. To enable this feature, contact ThoughtSpot Support. +==== + + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.48.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +This release introduces new Spotter API endpoints and modifications to the agent conversation APIs, and deprecates legacy agent endpoints. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|=== + + +== April 2026 + +**Release version**: ThoughtSpot Cloud 26.4.0.cl + +*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#_version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.47.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== + +a| +[.cl-label] +*Version 26.4.0.cl* + +a| + +[discrete] +==== Theme builder in AI mode + +The Theme Builder now has an AI mode that enables developers to explore and preview style customizations for their embedded application's branding using natural language instructions and uploaded brand assets. You can execute style updates such as applying colors directly from a PDF branding guide, updating all button shapes with higher contrast, matching a header to a dark background based on a screenshot, or importing typography and spacing from a JSON file. In the AI mode, Theme builder interprets your intent and applies the changes instantly. + +For more information, see xref:theme-builder.adoc[Theme builder]. + +--- + + +[discrete] +==== Webhook integration +In this release version, the following enhancements are introduced in the webhook configuration and delivery status monitoring workflows: + +Channel validation:: +Administrators can verify the connection status of a webhook channel by sending a test payload in a `POST` request to the `/api/rest/2.0/system/communication-channels/validate` REST API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[Webhook channel validation]. + +Monitor webhook delivery:: +Administrators can also monitor the status of a webhook delivery via a `POST /api/rest/2.0/jobs/history/communication-channels/search` API request. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. + +Support for custom HTTP headers in webhook requests:: +When configuring or updating a webhook, you can now specify custom headers to include in every outbound request, in addition to the standard HTTP and authentication headers that ThoughtSpot sends. For more information, refer to the xref:webhooks.adoc#_webhook_delivery_behavior[webhook documentation]. + +--- + + +[discrete] +==== Spotter embed enhancements +You can now customize the appearance and contents of the chat history sidebar panel in Spotter embedding. + +You can also customize the branding and logo in the Spotter chat interface. + +For more information, see xref:customize-spotter-chat-experience.adoc[Customizing chat history sidebar] and xref:customize-spotter-chat-experience.adoc#_spotter_logo_and_thoughtspot_branding_label[Hiding logo and brand label in Spotter chat interface]. + +--- + +[discrete] +==== Liveboard enhancements +The following enhancements are introduced in Liveboard export and filtering workflows. + +Embedding a personalized Liveboard view:: +You can now embed a saved personalized Liveboard view using the `personalizedViewId` and load it along with the `liveboardId` in your app. + +Centralized filter modal:: +Liveboard users can modify multiple filters and parameters in a single session using the centralized filter modal. This is an early access feature and disabled by default on ThoughtSpot embedded instances. To enable this feature on embedded Liveboards, set the `isCentralizedLiveboardFilterUXEnabled` to `true`. + +Current period inclusion in rolling date filters:: +The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. + +Liveboard PNG export:: +The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard report API documentation]. + +--- + + +[discrete] +==== Full app embedding +In full application embedded deployments with the V3 navigation and home page experience, the default list page experience is set to ListPage v3 experience. + +The ListPage V3 experience provides a refreshed list layout and styling, including the following enhancements: + +* The **Views** column to show the number of views for each object. +* Sorting options for **Name**, **Author**, and **Views** columns. +* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. + +For more information, see xref:full-app-customize.adoc#_list_page_experience[List page customization]. + +--- + + +[discrete] +==== Variable API +The variable REST API provides new API endpoints for the following bulk operations: + +* Bulk deletion: +You can now delete multiple variables in a single API request using the `/api/rest/2.0/template/variables/delete` endpoint. +* Batch update of variable values: +You can now assign and update multiple values to a variable in a single API request using the `/api/rest/2.0/template/variables/{identifier}/update-values` endpoint. + +[NOTE] +==== +The `/api/rest/2.0/template/variables/update-values` and `/api/rest/2.0/template/variables/{identifier}/delete` endpoints are now deprecated. Use the new `/api/rest/2.0/template/variables/{identifier}/update-values` and `/api/rest/2.0/template/variables/delete` endpoints for the variable update and delete operations instead. +==== + +For more information, see xref:variables.adoc[Variables documentation]. + +--- + + +[discrete] +==== Metadata parameterization +You can now parameterize multiple properties of metadata objects using `POST /api/rest/2.0/metadata/parameterize-fields`. The legacy endpoint `/api/rest/2.0/metadata/parameterize` is deprecated in 26.4.0.cl and later versions, and is replaced with the new endpoint to allow updating multiple fields in a single API request. + +For more information, see xref:metadata-parameterization.adoc[Metadata parameterization documentation]. + +--- + + +[discrete] +==== Collections [beta betaBackground]^Beta^ +ThoughtSpot embedded users can now use REST APIs v2 to organize different ThoughtSpot objects into organizational containers called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. + +For more information, see xref:collections.adoc[Collections]. + +[NOTE] +==== +These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- +|=== + +== March 2026 + +**Release version**: ThoughtSpot Cloud 26.3.0.cl + +*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.46.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== + +a| +[.cl-label] +*Version 26.3.0.cl* + +a| +[discrete] +==== Amazon S3 storage destination for webhook delivery +You can now configure ThoughtSpot to deliver webhook payloads and attachments directly into your own Amazon S3 storage using secure AWS cross-account access. To enable this integration, your AWS administrator must create an IAM role with S3 permissions and trust policy, and then register a webhook in ThoughtSpot to deliver the payloads and attachments directly to your S3 bucket. + +For more information, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. + +--- + +[discrete] +==== Host event enhancements for context-aware routing + +HostEvents in the Visual Embed SDK are enhanced to improve event routing and context targeting in ThoughtSpot embedded applications. + +Developers can use the page context framework in the SDK to route host events to a specific UI layer and align user experience with the product UI behavior in multi-modal contexts. + +For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. + +--- + +[discrete] +==== JWT-based ABAC implementation +The legacy JWT-based approach that uses `filter_rules` and `parameter_values` to implement Attribute-Based Access Control (ABAC) is deprecated. + +As part of this deprecation, the following changes have been introduced to the custom authentication token API workflow and REST API Playground: + +* The `filter_rules` parameter on the custom token authentication page in the REST API Playground is no longer available for new configurations. This change does not affect your existing implementation. + +* The `parameter_values` property is not deprecated in version 26.3.0.cl and remains supported until further notice. However, using parameter values for row-level security use cases will ultimately be deprecated in an upcoming release. + +Existing ABAC implementations that use `filter_rules` will continue to function until further notice. However, we strongly recommend migrating your legacy ABAC implementation to the ABAC via RLS method that uses custom variables. For migration steps, refer to the xref:abac-migration-guide.adoc[ABAC migration guide]. + +For new deployments, use ABAC via RLS with custom variables and pass data security attributes through the `variable_values` property in the custom access token, and define your RLS rules based on those variables. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS]. + +--- + +[discrete] +==== Spotter coaching access across published Orgs +Starting with the 26.3.0.cl release, ThoughtSpot supports publishing Spotter coaching information to other Orgs. Coaching changes from the primary Org are synchronized with the data models published in secondary Orgs. + +Administrators and users with edit access to data models can programmatically control user access to Spotter coaching information using the object privilege REST API endpoint, `/api/rest/2.0/security/metadata/manage-object-privilege`. They can assign `SPOTTER_COACHING_PRIVILEGE` to other users and user groups, allowing access to the coaching information without requiring data model editing or administration privileges. + +Users and groups with `SPOTTER_COACHING_PRIVILEGE` can import and export coaching TML on data models in the source and destination Orgs where the model is published, and can also share these objects with other users and groups. + +For more information, see xref:spotter-nl-instructions.adoc#_allowing_access_to_spotter_data_model_instructions[Allowing access to Spotter data model instructions]. + +--- + +[discrete] +==== Full application embedding +The height and aspect ratio of the logo in the top-left corner of the ThoughtSpot application interface have been updated for visual alignment and consistency across pages. This enhancement is available only in the V3 navigation and home page experience. + +If you have embedded the full application with the V3 navigation experience, you may notice that the logo appears smaller in the top navigation. This is a design update and does not require any configuration changes to your current embedding implementation. However, we recommend that you review the logo size and appearance, and adjust your custom logo if necessary. + +For information about adding a custom logo image, see xref:customize-style.adoc#logo-change[Customize application logo and favicon]. + +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.46.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|=== + +== February 2026 +**Release version**: ThoughtSpot Cloud 26.2.0.cl + +*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Recommended SDK versions*: Visual Embed SDK v1.45.0 and later + + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.2.0.cl* + +a| +[discrete] +==== SpotterCode extension for IDEs [earlyAccess eaBackground]#Early Access# + +ThoughtSpot introduces SpotterCode, an AI-powered Model Context Protocol (MCP) extension for Integrated Development Environments (IDEs) such as Cursor, Visual Studio Code, and Claude Code. When integrated, SpotterCode enables the AI agent in the IDE to access ThoughtSpot SDKs and API documentation resources and provide in-context coding assistance to developers embedding ThoughtSpot content within their applications. + +SpotterCode is available as an Early Access feature and can be integrated with development environments that support MCP servers and tools. For more information, see xref:spottercode.adoc[SpotterCode], xref:spottercode-integration.adoc[Integrating SpotterCode in IDEs], and xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. + +--- + +[discrete] +==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# +You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. + +For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. + +--- + +[discrete] +==== Rate limits for REST APIs +To prevent excessive requests from reaching application servers and ensure API stability and service quality for REST API users, ThoughtSpot enforces rate limits on public API requests per client IP. These limits are applied globally at the cluster level for all public API requests, including calls to both REST API v1 and v2 endpoints. +//Administrators can adjust these limits for their ThoughtSpot deployments as needed. + +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for REST APIs]. + +--- + +[discrete] +==== Security settings via REST APIs +Security settings that ensure data security and a seamless embedded user experience can now be configured through REST APIs v2. Administrators and developers can configure allowlists for: + +* Content Security Policy (CSP) +* Cross-origin Resource Sharing (CORS) +* Authentication attributes +* Access control settings + +For more information, see xref:security-settings.adoc[Security Settings]. + +--- + +[discrete] +==== WebSocket support for external tools +ThoughtSpot supports secure WebSocket (`wss://`) endpoints for external tool script integrations, for example, tools that open WebSocket connections from the browser. + +To allow a WebSocket host, add the corresponding `wss://` URL to both your CSP allowlists. Only hosts explicitly listed with the `wss://` protocol are permitted. Existing `https://` entries in the allowlists remain unchanged and continue to function as expected. + +For more information, see xref:3rd-party-script.adoc#_allow_websocket_endpoints[External tools and script integration]. + +--- + + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.45.0, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- +|=== + + +== January 2026 + +**Release version**: ThoughtSpot Cloud 10.15.0.cl + +*Upgrade notes*: No breaking changes. + +*Recommended SDK versions*: Visual Embed SDK v1.44.0 and later + + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 10.15.0.cl* + +a| +[discrete] +==== Theme Builder +Theme Builder is now generally available (GA) and will be rolled out to all ThoughtSpot instances in customer deployments over the next few weeks. + +When this feature is enabled on your instance, you can access it from the *Develop* page in ThoughtSpot and use it to customize styles and UX themes directly within the product. + +For more information, see xref:theme-builder.adoc[Theme Builder]. + +--- + +[discrete] +==== V3 navigation and home page experience + +The new V3 navigation and home page experience is now generally available (GA) and can be enabled on ThoughtSpot embedded instances. + +The default UI experience in full application embedding remains the classic (V1) experience until further notice. Developers embedding the full ThoughtSpot application can enable the V3 experience in their applications by setting the appropriate configuration options in their embed code. + +For more information, see xref:full-app-customize.adoc[Customizing full application embedding]. + +--- + +[discrete] +==== Formula variables in RLS rules + +You can now create formula variables using the Variable REST API and use these variables in RLS rules for a specific data context and in ABAC token requests to dynamically assign security attributes to users. + +For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. + +--- + +[discrete] +==== Spotter APIs + +ThoughtSpot introduces new REST APIs for the following Spotter workflows: + +* To send queries to a conversation session with the Spotter agent +* To set data model instructions on a model to coach the Spotter system +* To fetch data model instructions configured on a model + +For more information, see xref:spotter-apis.adoc[Spotter APIs]. + +--- + +[discrete] +==== Embed events and parameters to intercept API calls +You can now intercept API calls from the embedded ThoughtSpot application using the `interceptUrls` attribute in the Visual Embed SDK. This feature lets you control API requests in your embedding application and use embed events to modify, block, or handle requests before they are sent to the backend. For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. + +--- + +[discrete] +==== Icon customization enhancements + +You can now replace or customize the chart switcher toggle and icons in the Charts drawer on an Answer or visualization page using SVG sprites. Previously, these icons were fixed to ThoughtSpot defaults and were not configurable. In the new version, these icons are available as SVG components and can be replaced by developers through the xref:customize-icons.adoc[icon customization framework] as needed. + +--- + +[discrete] +==== Mobile Embed SDK +The SDKs for embedding ThoughtSpot components in mobile apps are now Generally Available (GA). For more information about the SDKs and how to embed a ThoughtSpot component in a mobile app, see xref:mobile-embed.adoc[Mobile embed documentation]. + +--- + +[discrete] +==== Visual Embed SDK +For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API +For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|=== \ No newline at end of file From ecc1718421648b3bdf7c6d9d2fc71338d796702e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:59:27 +0530 Subject: [PATCH 046/169] docs: restore full What's New and add complete November 2026 section incl. Usage Data APIs From 39ff3a8c2eacf6c5bcb121ded1e03937989ae063 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:59:52 +0530 Subject: [PATCH 047/169] docs: restore full SDK changelog and add November 2026 (v1.54.0) entry --- modules/ROOT/pages/api-changelog.adoc | 2207 ++++++++++++++++++++++++- 1 file changed, 2189 insertions(+), 18 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 2d30d769c..d83c4c987 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1,15 +1,14 @@ ---- CITABLE SOURCE --- -File: modules/ROOT/pages/api-changelog.adoc -Branch: docs/scal-26-11-0-cl-doc-updates -URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc -To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number} ---- - -{ - "path": "modules/ROOT/pages/api-changelog.adoc", - "name": "api-changelog.adoc", - "size": 9615, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/api-changelog.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/api-changelog.adoc\",\n \"name\": \"api-changelog.adoc\",\n \"size\": 9615,\n \"content\": \"--- CITABLE SOURCE ---\\nFile: modules/ROOT/pages/api-changelog.adoc\\nBranch: docs/scal-26-11-0-cl-doc-updates\\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\\n---\\n\\n{\\n \\\"path\\\": \\\"modules/ROOT/pages/api-changelog.adoc\\\",\\n \\\"name\\\": \\\"api-changelog.adoc\\\",\\n \\\"size\\\": 9616,\\n \\\"content\\\": \\\"--- CITABLE SOURCE ---\\\\nFile: modules/ROOT/pages/api-changelog.adoc\\\\nBranch: docs/scal-26-11-0-cl-doc-updates\\\\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc\\\\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/api-changelog.adoc#L{line_number}\\\\n---\\\\n\\\\n{\\\\n \\\\\\\"path\\\\\\\": \\\\\\\"modules/ROOT/pages/api-changelog.adoc\\\\\\\",\\\\n \\\\\\\"name\\\\\\\": \\\\\\\"api-changelog.adoc\\\\\\\",\\\\n \\\\\\\"size\\\\\\\": 106492,\\\\n \\\\\\\"content\\\\\\\": \\\\\\\"= Visual Embed SDK changelog\\\\\\\\n:toc: true\\\\\\\\n:toclevels: 2\\\\\\\\n\\\\\\\\n:page-title: Visual Embed SDK changelog\\\\\\\\n:page-pageid: embed-sdk-changelog\\\\\\\\n:page-description: Changelog for the Visual Embed SDK\\\\\\\\n\\\\\\\\nThis 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].\\\\\\\\n\\\\\\\\n== Version 1.54.0, November 2026\\\\n\\\\n [width=\\\\\\\"100%\\\\\\\", cols=\\\\\\\"1,4\\\\\\\"]\\\\n |====\\\\n |[tag greenBackground]#NEW#\\\\n a|\\\\n [discrete]\\\\n ===== SpotterX embed support\\\\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\\\\n\\\\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\\\\n\\\\n |[tag greenBackground]#NEW#\\\\n a|\\\\n [discrete]\\\\n ===== Host-controlled tooltip rendering\\\\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\\\\n\\\\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\\\\n\\\\n |[tag greenBackground]#NEW#\\\\n a|\\\\n [discrete]\\\\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\\\\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\\\\n\\\\n |====\\\\n\\\\n == Version 1.54.0, November 2026\\n\\n [width=\\\"100%\\\", cols=\\\"1,4\\\"]\\n |====\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== SpotterX embed support\\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\\n\\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Host-controlled tooltip rendering\\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\\n\\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\\n\\n |[tag greenBackground]#NEW#\\n a|\\n [discrete]\\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\\n\\n |====\\n\\n == Version 1.54.0, November 2026\n\n [width=\"100%\", cols=\"1,4\"]\n |====\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== SpotterX embed support\n You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts.\n\n For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Host-controlled tooltip rendering\n The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely.\n\n For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views].\n\n |[tag greenBackground]#NEW#\n a|\n [discrete]\n ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^\n You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction.\n\n |====\n\n == Version 1.54.0, November 2026 += Visual Embed SDK changelog +:toc: true +:toclevels: 2 + +:page-title: Visual Embed SDK changelog +:page-pageid: embed-sdk-changelog +:page-description: Changelog for the Visual Embed SDK + +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]. + +== Version 1.54.0, November 2026 [width="100%", cols="1,4"] |==== @@ -27,16 +26,2188 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs ===== Host-controlled tooltip rendering The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely. - For more information, see xref:customize-spotter-embed.adoc[Customizing charts in embedded views]. - |[tag greenBackground]#NEW# a| [discrete] - ===== Programmatic Liveboard filter overrides [beta betaBackground]^Beta^ - You can now apply filter overrides to Liveboard visualizations programmatically through URL parameters. This allows host applications to set persistent filter states on embedded Liveboards without requiring user interaction. + ===== Programmatic Liveboard filter overrides [Beta] + You can now programmatically update Liveboard filter values at runtime using URL-based filter overrides, without re-rendering the entire component. |==== - == Version 1.53.0, October 2026\\\\\\\\n\\\\\\\\n[width=\\\\\\\\\\\\\\\"100%\\\\\\\\\\\\\\\", cols=\\\\\\\\\\\\\\\"1,4\\\\\\\\\\\\\\\"]\\\\\\\\n|====\\\\\\\\n|[tag greenBackground]#NEW#\\\\\\\\na|\\\\\\\\n[discrete]\\\\\\\\n===== Spotter Analyst embed\\\\\\\\nYou can now e + == Version 1.53.0, October 2026 + +[width="100%", cols="1,4"] +|==== +|[tag greenBackground]#NEW# +a| +[discrete] +===== Spotter Analyst embed +You can now embed a single, pinned Spotter Analyst in `SpotterEmbed` by using `spotterAnalystConfig.analystId`. +For more information, see xref:embed-spotter-analyst.adoc[Embed Spotter Analyst]. + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Spotter embedding + +`spotterChatPinConfig`:: +You can now let users pin conversations in the chat history sidebar. Use the `spotterChatPinConfig` object in `spotterSidebarConfig` to turn pinning on (`enabled`) and to customize the labels of the *Pin* and *Unpin* options (`pinLabel` and `unpinLabel`). For more information, see xref:customize-spotter-sidebar.adoc#pinning-conversations[Pinning conversations]. + +`starterPrompts`:: +You can now customize the starter prompt pills in the embedded Spotter interface by using the `starterPrompts` object in `spotterChatConfig`. The object supports the `enable`, `quick`, `research`, `previewData`, and `liveboard` keys. To show or hide individual pills, use `Action.QuickSearchPill`, `Action.DeepAnalysisPill`, and `Action.DataLiteracyPill`. For more information, see xref:embed-spotter-analyst.adoc#_customizing_starter_prompt_pills[Customizing starter prompt pills]. + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Liveboards in embedded view +The SDK includes the following enhancements for the Liveboards in your embedded app. + +* `isScopedLiveboardFilteringEnabled` + +Enables scoping filters and parameters to a group of visualizations on a Liveboard, in addition to the Liveboard and tab levels. Supported in `AppEmbed` and `LiveboardEmbed`. +* `openSpotterOnLiveboardByDefault` + +Opens the Spotter chat panel automatically when a Liveboard loads. Set this property in `spotterChatConfig`. The default value is `true`. Supported in `AppEmbed` and `LiveboardEmbed`. +* `starterPrompts.liveboard` + +Starter prompts for the Spotter chat panel on a Liveboard. + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Action IDs for embedded Spotter and Liveboard interfaces + +The following `Action` enum members are added in this release: + +* `Action.SpotterChatPin` + +Controls the visibility and enabled state of the pin and unpin action in the Spotter conversation edit menu. +* `Action.SpotterAnalystList` + +Controls the visibility and enabled state of the *Show all* Analysts entry in the Analyst interface. +* `Action.SpotterDefaultAnalyst` + +Controls the visibility and enabled state of the default Spotter entry in the Analyst interface. +* `Action.SpotterOnLiveboard` + +Controls the visibility and enabled state of the *Spotter* button in the Liveboard header. +* `Action.AllLiveboardFilters` + +Shows, hides, or greys out all filter surfaces on a Liveboard: filter chips, parameter chips, and cross-filter chips at the Liveboard, tab, and group levels. Parameter and cross-filter chips can only be hidden. +* `Action.EditInputTable` + +Controls the *Edit input table* action, which lets users edit an input table used by an Answer directly from the Liveboard. +* `Action.QuickSearchPill` + +Controls the *Basic Search* starter prompt pill in the Spotter interface. +* `Action.DeepAnalysisPill` + +Controls the *Deep Analysis* starter prompt pill in the Spotter interface. +* `Action.DataLiteracyPill` + +Controls the *Data Literacy* starter prompt pill in the Spotter interface. + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Events + +Embed events:: +* `EmbedEvent.SpotterConversationPinned` + +Emitted when a user pins a Spotter conversation. The event payload includes the `conversationId` and `pinnedAt` values. +* `EmbedEvent.SpotterConversationUnpinned` + +Emitted when a user unpins a Spotter conversation. The event payload includes the `conversationId` and `unpinnedAt` values. + +Host events:: +* `HostEvent.PinSpotterConversation` + +Pins a saved Spotter conversation. Accepts `{ conversationId }`. +* `HostEvent.UnpinSpotterConversation` + +Unpins a previously pinned Spotter conversation. Accepts `{ conversationId }`. +* `HostEvent.GetGroups` + +Returns filter and parameter group details for the current Liveboard. The response includes `orderedGroupIds`, `numberOfGroups`, and `Groups`. +* `HostEvent.OpenParameter` + +Opens the parameter panel for a specific parameter on the Liveboard. Accepts an optional `applicability` object to scope the action to a tab or group. + +The pin and unpin events require `spotterChatPinConfig.enabled: true` and `enablePastConversationsSidebar: true` in the embed configuration. The host events also require chat history to be enabled on your ThoughtSpot instance. + +Updated events:: +The following existing events now include or accept an optional `applicability` attribute, which scopes filters and parameters to a Liveboard tab or group: + +* `EmbedEvent.FilterChanged` +* `EmbedEvent.ParameterChanged` +* `HostEvent.OpenFilter` +* `HostEvent.GetFilters` +* `HostEvent.UpdateFilters` +* `HostEvent.GetParameters` +* `HostEvent.UpdateParameters` + +Deprecated events:: +* `HostEvent.UpdatePersonalizedView` is deprecated. Use `HostEvent.SelectPersonalizedView` instead. `HostEvent.SelectPersonalizedView` additionally accepts an optional `viewName` to select a view by name, resets to the original view when the payload is empty, and reports an error when the named view isn't found. +|==== + +== Version 1.52.x, September 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# +a| +[discrete] +===== Spotter conversation sharing in embedded views +Embedding application users can now share a saved Spotter conversation with other users and groups directly from the embedded interface. Recipients can view the shared conversation in a read-only view. +Conversation sharing is turned off by default in embedded views. To enable it, set `enableShareConversation` to `true` in the `spotterShareConversationConfig` object. + +Interface customization settings:: +The SDK also provides the following controls for conversation sharing: + +* `SpotterShareConversationConfig` + +Includes object properties for enabling conversation sharing, label and text overrides for the share button, share modal, recipient picker, and the read-only shared view. For more information, see xref:customize-spotter-sharing.adoc[Customize conversation sharing experience]. +* `sharedConversationId` + +Allows passing conversation ID to the SpotterEmbed when the sharing link is generated for the recipient users in the embedded app. For more information, see xref:customize-spotter-sharing.adoc#_customizing_conversation_sharing_link[Conversation sharing link] + +New action IDs:: +* `Action.SpotterShareConversationButtonHeader` for **Share** button in the Spotter conversation header. +* `Action.SpotterShareConversationMenuItemSidebar` for **Share** menu action in the chat history panel in the sidebar. +* `Action.SpotterShareIncludeNewMessagesCheckbox` for the `include new messages since last shared version` checkbox in the share modal. +* `SpotterSharedConversationBannerDismissButton` for the dismiss button of the data access banner displayed in the shared conversation view. +* `Action.SpotterShareUpToCurrentInfo` for the share modal footer note. +* `Action.SpotterSharedConversationBanner` for the data access banner shown when a recipient opens a shared conversation. +* `Action.SpotterShareStaleInfoBannerDismissButton` for the banner that shows the message, "This data may have changed since the last time you had a chat." +* `Action.SpotterSharedConversationExitButton` for *Exit* button in the read-only view of the shared conversation. + +New host events:: +* `HostEvent.ShareSpotterConversation` + +Opens the Spotter share conversation modal for the given conversation ID. +* `HostEvent.ExitSpotterSharedConversation` + +Exits the read-only view of the shared conversation. +* `HostEvent.CloseSpotterShareConversation` + +Closes the Spotter share conversation modal. + +New embed events:: +* `EmbedEvent.SpotterConversationShared` + +Emitted when a Spotter conversation is shared with the intended recipients. +* `EmbedEvent.SpotterConversationShareRevoked` + +Emitted when access to a shared Spotter conversation is revoked. +* `EmbedEvent.SpotterSharedConversationViewed` + +Emitted when a recipient opens a shared Spotter conversation. +* `EmbedEvent.SpotterShareConversationButtonHeaderClicked` + +Emitted when the Share button in the conversation header is clicked. +* `EmbedEvent.SpotterShareConversationMenuItemSidebarClicked` + +Emitted when the Share action in the menu displayed for a chat in the chat history sidebar. +* `SpotterShareIncludeNewMessagesCheckboxToggled` + +Emitted when the user toggles the "include new messages since last shared version" checkbox in the share modal. +* `EmbedEvent.SpotterShareModalCancelButtonClicked` + +Emitted when the Cancel button in the share conversation modal is clicked. +* `EmbedEvent.SpotterShareStaleInfoBannerDismissed`+ +Emitted when the user dismisses the banner that shows the text, "This data may have changed since the last time you had a chat." +* `EmbedEvent.SpotterSharedConversationExitButtonClicked` + +Emitted when a user exits the shared conversation read-only view. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Browser history management in embedded application +To override the browser history behavior for embedding application users, you can now set `overrideHistoryState` in the Visual Embed SDK. Use this setting in your embed when the in-app navigation between objects pushes multiple entries onto the host application's browser history stack. When set to `true`, this feature prevents users from getting trapped in back-button loops inside the embedded iframe. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Customization controls for Collections in full application embedding +The `HomeLeftNavItem.Collections` enum value is now available in the Visual Embed SDK. Embed developers can include *Collections* as a selectable navigation option in the embedded left navigation panel for full application embeds. When enabled, end users of the embedded application can navigate to *Collections* from the left navigation panel. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +|[tag greenBackground]#MODIFIED# a| + +[discrete] +===== Lazy loading defaults for Liveboards +When `fullHeight` is enabled on `LiveboardEmbed` or `AppEmbed`, the following lazy-loading parameters now default to `true`: + +* `lazyLoadingForFullHeight` + +Enables lazy loading of visualizations when fullHeight is enabled. +* `enableScrollableContainerLazyLoading` + +Enables lazy loading for scrollable container elements. +* `lazyLoadingMargin` + +Sets the margin for lazy loading to `'500px 0px'`. + +These defaults apply automatically. Any value you set explicitly, including `false`, overrides the default. If `fullHeight` is disabled or not specified, the behavior is not affected. + +For more information, see xref:lazy-loading-fullheight.adoc[Full height and lazy loading options for Liveboards]. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Pre-render configuration object +The SDK introduces the `PreRenderConfig` interface, which bundles the existing prerender settings such as `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` into a single object. + +The existing individual `preRenderId`, `preRenderContainer`, and `doNotTrackPreRenderSize` properties at the top-level are deprecated in this version. Update your integration to use the new `preRenderConfig` property on `BaseViewConfig` instead of the individual top-level properties. + +For more information, see xref:prerender.adoc[Pre-rendering ThoughtSpot embed components]. + +|[tag greenBackground]#NEW# +a| + +[discrete] +===== CSS customization + +CSS variable for unsaved filter indicator:: +A new CSS variable `--ts-var-unsaved-filter-indicator-color` is available to customize the color of the "unsaved changes" indicator dot shown on filter and parameter chips. + +Insight tile CSS variables:: +New CSS variables are available to customize the Liveboard insight tile appearance: + +* `--ts-var-liveboard-insight-tile-background` + +Background color of the insight tile. +* `--ts-var-liveboard-insight-tile-icon-color` + +Color of the insight tile icon. +* `--ts-var-liveboard-insight-tile-success-color` + +Color used for positive/success indicators. +* `--ts-var-liveboard-insight-tile-failure-color` + +Color used for negative/failure indicators. + +For more information, see xref:css-customization.adoc[CSS customization framework]. + +|| +|==== + +//// +|[tag greenBackground]#NEW# a| + + +[discrete] +===== Exported host-event contract types +The SDK now publicly exports host-event contract types that were previously internal-only. This allows TypeScript consumers to strongly type `embed.trigger(HostEvent.X, payload)` calls without importing internal modules. + +Newly exported types include: + +* `UIPassthroughContractBase`, `UIPassthroughRequest`, `UIPassthroughResponse`, `UIPassthroughArrayResponse` +* `HostEventRequest`, `HostEventResponse` +* `TriggerPayload`, `TriggerResponse` +* `LiveboardTab`, `LiveboardGroup` +* `Applicability`, `ApplicabilityLevel` +* `FilterUpdate`, `LiveboardFilter`, `LiveboardParameter` +* `SpotterAnalystConfig` +* `StarterPromptsConfig`, `StarterPromptCategory`, `StarterPreviewDataCategory`, `StarterPromptQuestion` +//// + +== Version 1.51.x, August 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| + +[discrete] +===== Liveboard embedding +The SDK includes the following new features and enhancements in Liveboard embedding. + +`liveboardGutter` embed config property:: +A new `liveboardGutter` property is available on `LiveboardViewConfig`. Use this property to set the gutter spacing between tiles on an embedded Liveboard. +For more information, see xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter] + +12-column layout for Liveboard tile positioning:: +A new embed config property is available on `LiveboardViewConfig` to always use a 12-column grid layout for Liveboard tile positioning. When enabled, tile placement and sizing follow a fixed 12-column grid regardless of the Liveboard's default layout settings. +For more information, see xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards] + +New host events for the Liveboard edit page:: +* `HostEvent.OpenAddFilterModal` + +Opens the Add Filter modal in the Liveboard edit view. Trigger this event to let users add a filter without navigating the UI manually. +* `HostEvent.OpenAddParameterModal` + +Opens the Add Parameter modal in the Liveboard edit view. Trigger this event to let users add a parameter from a host application control. + +For more information, see xref:events-hostEvents.adoc#open-add-filter-parameter-modal[Host events]. + +CSS customization variables for Liveboard:: +These new CSS variables are available for Liveboard layout and header customization: + +* `--ts-var-liveboard-header-horizontal-margin` + +Sets the left and right margins of the Liveboard header. Set this to the same pixel value as `liveboardGutter` in `LiveboardViewConfig` to align the header with the tile grid. + +* `--ts-var-liveboard-dual-column-breakpoint` + +Sets the container width threshold at which the Liveboard layout collapses from 12 columns to 2 columns. + + +* `--ts-var-liveboard-single-column-breakpoint` + +Sets the container width threshold at which the Liveboard layout collapses from 2 columns to a single column. + + +For more information, see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables] and xref:customize-css-styles.adoc#_liveboard[Liveboard CSS variables]. + + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Spotter embedding + +Spotter Analysts:: +The Visual Embed SDK 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. For more information, see xref:customize-spotter-analysts.adoc#_spotter_analysts[Spotter Analysts in embed view]. + +Starter prompts:: +If quick starter prompts are enabled and configured for data models on a ThoughtSpot instance, you can display these prompts in the embed using the `enableStarterPrompts` parameter. For more information, see xref:customize-spotter-chat-experience.adoc#_spotter_starter_prompts[Spotter quick starter prompts]. + +|[tag greenBackground]#MODIFIED# a| + +[discrete] +===== Liveboard embedding +The following Liveboard embedding settings are set to `true` by default on all ThoughtSpot embedded instances: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filters that are not relevant to the displayed visualization. +* `isLiveboardCompactHeaderEnabled` + +Enables compact header layout in embedded Liveboards. +* `coverAndFilterOptionInPDF` + +Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. +* `isLiveboardMasterpiecesEnabled` + +Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. +* `isEnhancedFilterInteractivityEnabled` + +Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. + +For more information, see xref:embed-pinboard.adoc#common-customizations[Common customization options in Liveboard embedding]. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Object format support in HostEvent.Navigate +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. + +|==== + +== Version 1.50.x, July 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| + +[discrete] +===== SpotterViz embed customization +The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. + +A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Home page customization in full application embedding +For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +|==== + +== Version 1.49.x, June 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| +[discrete] +===== Visual overrides for charts and tables +The SDK introduces the `visualOverrides` object in `SearchViewConfig` and +`AppViewConfig`, enabling embed developers to apply chart and table display +customizations to the new answers from an embedded Search data interface at initialization time. + +The `visualOverrides` object provides the following customization controls to modify the chart and table display: + +* `legend` to control legend visibility, position, and color palette of charts. +* `dataLabel` attribute for data labels and per-column label filters. +* `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 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# a| + +[discrete] +===== Liveboard browser cache refresh +For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. + +The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. + +* `EmbedEvent.RefreshLiveboardBrowserCache` + +Emitted when the Liveboard browser cache is refreshed. +* `HostEvent.RefreshLiveboardBrowserCache` + +Trigger a manual cache refresh from the host application. +* `Action.RefreshLiveboardBrowserCache` + +Action ID to show or hide the cache refresh button. + +For more information, see xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh]. + +|[tag greenBackground]#NEW# a| +[discrete] +===== Spotter file upload +The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. + +* `spotterFileUploadEnabled` + +When set to `true`, enables the file upload feature in the Spotter chat panel. + +* `spotterFileUploadFileTypes` + +Restricts the file types allowed for upload in the Spotter chat panel. + +For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. + +|==== + +== Version 1.48.x, May 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| +[discrete] +===== Liveboard embedding +The SDK includes the following new features and enhancements in Liveboard embedding. + +Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: + +When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. + +New events and action IDs;; + +* `EmbedEvent.DownloadLiveboardAsContinuousPDF` + +Emits when the download action is triggered. +* `HostEvent.DownloadLiveboardAsContinuousPDF` + +Programmatically triggers the download action to export the PDF with a continuous Liveboard layout. +* `Action.DownloadLiveboardAsContinuousPDF` + +Action ID to control the visibility of download action that exports continuous PDFs. + +Liveboard download actions:: + +The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: + +* `Action.DownloadLiveboard` + +* `Action.DownloadLiveboardAsXlsx` + +* `Action.DownloadLiveboardAsCsv` + +Test email for Liveboard scheduled jobs:: + +The SDK introduces the `isSendNowLiveboardSchedulingEnabled` to enable the **Send now** option for the Liveboard scheduled jobs. This option allows Liveboard users to send a test email notification to either themselves or the intended recipients of the Liveboard scheduled alerts. + +New events and action IDs;; + +* `EmbedEvent.SendTestScheduleEmail` + +Emits when *Send now* button is clicked. +* `HostEvent.SendTestScheduleEmail` + +Programmatically triggers the Send now action to send a test email notification for a Liveboard scheduled job. +* `Action.SendTestScheduleEmail` + +Action ID to disable, show, or hide the **Send now** button on the Liveboard schedule page. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Spotter embedding + +The SDK introduces the following action IDs to control the visibility of specific UI components in chat panel of the embedded Spotter interface: + +* `Action.SpotterChatConnectorResources` + +For the connector resources section in the Spotter chat interface. +* `Action.SpotterChatConnectors` + +For the connectors panel section in the Spotter chat interface. +* `Action.SpotterChatModeSwitcher` + +For the mode switcher in the Spotter chat interface. + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Event handling +Note the following changes: + +EmbedEvent:: + +* `EmbedEvent.Subscribed` + +The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. +* `EmbedEvent.Error` + +The `EmbedEvent.Error` now fires on HostEvent payload validation failures. + +HostEvent:: +* `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + +The response payload of the `GetExportRequestForCurrentPinboard` passthrough +host event has been updated to include a `type` discriminator field, making it +consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. + + +|[tag greenBackground]#NEW# a| + +[discrete] +===== Personalized View selection via host event + +* `EmbedEvent.ChangePersonalizedView` + +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]. + +* `HostEvent.SelectPersonalizedView` + +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]. + +⚠️Deprecated events and action IDs️:: +The following events are deprecated and replaced with new event IDs. + +* `EmbedEvent.UpdatePersonalisedView`. Use `EmbedEvent.UpdatePersonalizedView`. +* `EmbedEvent.SavePersonalisedView`. Use `EmbedEvent.SavePersonalizedView`. +* `EmbedEvent.DeletePersonalisedView`. Use `EmbedEvent.DeletePersonalizedView`. +* `HostEvent.ResetLiveboardPersonalisedView`. Use `HostEvent.ResetLiveboardPersonalizedView`. +* `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. +* `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. + +|==== + + +== Version 1.47.x, April 2026 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| **Spotter chat history sidebar customization** + +The SDK introduces the `SpotterSidebarViewConfig` interface and the `spotterSidebarConfig` object with configuration controls to customize the appearance and contents of the chat history panel. Developers can use the following properties in the `spotterSidebarConfig` object to enable or disable chat history panel and customize the contents of the sidebar when enabled: + +* `enablePastConversationsSidebar` + +Controls the visibility of the past conversations sidebar panel. The chat history panel is disabled by default in embed view. When this property in `spotterSidebarConfig` is specified, it takes precedence over the standalone `enablePastConversationsSidebar` setting, which is deprecated from v1.47.0. + +* `spotterSidebarTitle` + +Allows adding custom title text for the sidebar header. + +* `spotterSidebarDefaultExpanded` + +Sets the default state of the sidebar to expanded or collapsed view. + +* `spotterChatRenameLabel` + +Allows setting a custom label for the **Rename** action in the conversation edit menu. + +* `spotterChatDeleteLabel` + +Allows setting a custom label for the **Delete** action in the conversation edit menu. + +* `spotterDeleteConversationModalTitle` + +Allows editing the title text of the chat delete confirmation modal. + +* `spotterPastConversationAlertMessage` + +Sets a custom message text for the past conversation banner alert. Defaults to the translated alert message. + +* `spotterBestPracticesLabel` + +Allows customizing the label for the best practices button in the sidebar footer. + +* `spotterDocumentationUrl` + +The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. + +* `spotterConversationsBatchSize` + +Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. + +* `spotterNewChatButtonTitle` + +Allows customizing the title text for the **New chat** button in the sidebar. + +|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** + +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. + +Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. + +[source,javascript] +---- +// Deprecated +enablePastConversationsSidebar: false, + +// Recommended +spotterSidebarConfig: { + enablePastConversationsSidebar: true, + //... other config properties +} +---- + +|[tag greenBackground]#NEW# a| **Spotter chat UI branding** + +The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. + +* `hideToolResponseCardBranding` + +When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. + +* `toolResponseCardBrandingLabel` + +Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. + +[NOTE] +==== +These settings do not affect the external MCP tool branding. +==== + +|[tag greenBackground]#NEW# a|**Liveboard embed enhancements** + +Personalized Liveboard view:: + +The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. + +Centralized Liveboard filter setting:: + +When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. + +|[tag greenBackground]#NEW# a|**Option to include current period in rolling date filters** + +If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. +To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. +|==== + + +== Version 1.46.x, March 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| **Host events with page context framework** + +The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. + +* To enable this feature, set `useHostEventsV2` to `true`. +* To retrieve the current context, use `getCurrentContext()`. +* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. + +For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. + +|[tag redBackground]#DEPRECATED# a| **dataPanelV2** + +The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. + +|[tag greenBackground]#NEW# a| **Spotter experience** +The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. + +Chat history sidebar customization:: + +//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. +//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. +* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: +** `Action.DataModelInstructions` for the data model instructions icon. +** `Action.SpotterSidebarHeader` for the chat history sidebar header +** `Action.SpotterSidebarFooter` for the chat history sidebar footer +** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. +** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. +** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. +** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. +** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. +** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. +//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. + +Events:: +* `HostEvent.DataModelInstructions` + +Opens the Data Model instructions modal. +* `EmbedEvent.DataModelInstructions` + +Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. +* `EmbedEvent.SpotterConversationRenamed` + +Is emitted when a user renames a saved chat. +* `EmbedEvent.SpotterConversationDeleted` + +Is emitted when a saved chat is deleted. +* `EmbedEvent.SpotterConversationSelected` + +Is emitted when a saved chat is selected in the chat history sidebar. + +|[tag greenBackground]#NEW# | `enableLinkOverridesV2` + + +Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. + +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** + +* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. +* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. +|==== + +== Version 1.45.0, February 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| **Spotter enhancements** + +You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. + +* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. +* To use Auto mode, set the `worksheetId` to `auto_mode`. +* To enable Chat history, set `enablePastConversationsSidebar` to `true`. + +For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. + +Events:: + +* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session +* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. +* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. + +[NOTE] +==== +On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. +==== + +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** + + +Styling and grouping:: + +* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. +* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: +** `Action.MoveToGroup` for the **Move to Group** menu action. +** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. +** `Action.CreateGroup` for the *Create Group* menu action. +** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. + +Filter chip masking:: +The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. ++ +For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. ++ +The `showMaskedFilterChip` setting is also available in full application embedding. + +|[tag greenBackground]#NEW# a| **Publishing objects** + +The following action IDs are available for the data publishing menu actions in the *Data workspace* page: + +* `Action.Publish` for *Publish* +* `Action.ManagePublishing` for *Manage publishing* +* `Action.Unpublish` for *Unpublish* +* `Action.Parameterize` for *Parameterize* +|[tag greenBackground]#NEW# a| **Error handling improvements** + +To handle errors in the embedding workflows, the SDK includes the following features: + +* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. +* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. +* `EmbedErrorDetailsEvent` interface for structured error event handling. + +For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. +|==== + +== Version 1.44.x, January 2026 + +[width="100%" cols="1,4"] +|==== + +|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + + +The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. +To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. + +|[tag greenBackground]#NEW# a| *Intercepting API calls* + +The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: + +//* `enableApiIntercept` + +//When set to true, enables the feature on your ThoughtSpot embed. +* `interceptUrls` + +Allows configuring which API calls to intercept. +* `interceptTimeout` + +Sets the timeout duration for handling interception. +* `isOnBeforeGetVizDataInterceptEnabled` + +When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. +* `EmbedEvent.ApiIntercept` + +Emits when an API call matching the conditions defined in `interceptUrls` is detected. + +For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +|==== + + +== Version 1.43.0, November 2025 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| *Code-based custom actions* + +The following enumerations are available for code-based custom actions: + +* `CustomActionTarget` + +To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. +* `CustomActionsPosition` + +To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. +|[tag greenBackground]#NEW# | *Attribute to set Parameter chip visibility during overrides* + +The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. +|==== + +== Version 1.42.0, October 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|*Runtime overrides in Spotter embed* + +The Visual Embed SDK now supports runtime overrides in Spotter embed. + +* To apply runtime filters, use the `runtimeFilters` object +* To apply runtime Parameters, use the `runtimeParameters` object. + +|[tag greenBackground]#NEW# a|*PNG images in Liveboard schedule notifications* + +To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. + +The SDK also provides the following action IDs: + +* `Action.PngScreenshotInEmail` + +Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. +* `Action.RemoveAttachment` + +Allows the user to remove an attachment from the email configuration in the schedule email dialog. +|[tag greenBackground]#NEW# a|*Spotter embed* + +Action IDs:: +The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: + +* `Action.SpotterWarningsBanner` + +Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. +* `Action.SpotterWarningsOnTokens` + +Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. +* `Action.SpotterTokenQuickEdit` + +Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. +|==== + +== Version 1.41.0, September 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|*React component for Spotter Agent embed* + +The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. + +For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. + +|[tag greenBackground]#NEW# a|*Event handlers for Spotter embed* + +The following event handlers are now available for Spotter embed: + +* `EmbedEvent.SpotterInit` + +Fires when Spotter embed component rendering is initialized. +* `EmbedEvent.QueryChanged` + +Fires when the Spotter query is updated by the user. +* `HostEvent.AskSpotter` + +Triggers *Ask Spotter* action for visualizations. +* `HostEvent.GetParameters` + +Triggers the action to fetch runtime Parameters applied on a visualization. +* `HostEvent.UpdateParameters` + +Triggers the action to update runtime Parameters for a Spotter-generated Answer. +* `HostEvent.GetTML` + +Triggers the action to get TML representation of a Spotter-generated Answer. + +For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW# a|*Event handlers for Spotter Agent embed* + +You can now use the following host events in Spotter Agent embedding: + +- `HostEvent.DownloadAsCsv` + +Triggers the action to download a Spotter-generated Answer in CSV format. +- `HostEvent.DownloadAsPng` + +Triggers the action to download a Spotter-generated Answer in PNG format. +- `HostEvent.DownloadAsXlsx` + +Triggers the action to download a Spotter-generated Answer in XLSX format. +- `HostEvent.DownloadAsPdf` + +Triggers the action to download the PDF version of a Spotter-generated Answer. +- `HostEvent.Pin` + +Triggers the action to add a Spotter-generated Answer to a Liveboard. +- `HostEvent.Save` + +Triggers the *Save* action for a Spotter-generated Answer. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW# a| *Lazy loading of visualizations on an embedded Liveboard* + +You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +You can also set the margin property for lazy loading to define when the visualization should load. + +For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. + +|[tag greenBackground]#NEW# a| *Full application embed* + + +You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. + +When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. +|==== + +== Version 1.40.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + +Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. +|[tag greenBackground]#NEW# a| *PDF download settings* + +Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. + +|[tag greenBackground]#NEW# a| *Parameter for overriding a default primary action* + + +If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. + +For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. + +|[tag greenBackground]#NEW# a| *Full application embed experience enhancements* + + +The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. + +|[tag greenBackground]#NEW# a| *Host events* + + +In this version, the SDK introduces the following host event handlers: + +- `HostEvent.ExitPresentMode` + +Triggers the exit action that allows users to exit the Liveboard or visualization present mode. +- `HostEvent.SpotterSearch` + +Triggers a search operation for the specified query string in Spotter embed. +- `HostEvent.PreviewSpotterData` + +Triggers the *Preview data* action that shows the data used for Spotter conversations. +- `HostEvent.ResetSpotterConversation` + +Triggers the *Reset* action to reset a Spotter conversation. +- `HostEvent.EditLastPrompt` + +Triggers the edit prompt action. +- `HostEvent.DeleteLastPrompt` + +Triggers the delete prompt action. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW# a|*Events support for Spotter embed* + +You can now use the following host events in Spotter embed: + +- `HostEvent.DownloadAsCsv` +- `HostEvent.DownloadAsPng` +- `HostEvent.DownloadAsXlsx` +- `HostEvent.Edit` +//- `HostEvent.GetParameters` +//- `HostEvent.GetTML` +- `HostEvent.MakeACopy` +- `HostEvent.Pin` +- `HostEvent.Save` + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW# a| *Lazy loading with full height* + +The SDK introduces `lazyLoadingForFullHeight` parameter, which enables progressive loading of visualizations on an embedded Liveboard. +This parameter works in conjunction with the `fullHeight` attribute. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +[NOTE] +==== +To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. +==== +|==== + + +== Version 1.39.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| *Spotter embed components with new names* + +The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: + +* `ConversationEmbed` + +Replaced with `SpotterEmbed` +* `ConversationViewConfig` + +Replaced with `SpotterEmbedViewConfig` +* `BodylessConversation` + +Replaced with `SpotterAgentEmbed` +* `BodylessConversationViewConfig` + +Replaced with `SpotterAgentEmbedViewConfig` + +The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. + +|[tag greenBackground]#NEW# a| *Action ID for Spotter in-conversation training* + +For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. + +[NOTE] +The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. + +|[tag greenBackground]#NEW# a|*Events support for Spotter embed* + +New embed events:: + +- `EmbedEvent.ExitPresentMode` + +Emits when a user exits the Liveboard or visualization presentation mode. +- `EmbedEvent.LastPromptDeleted` + +Emits when a query prompt in Spotter embed is deleted. +- `EmbedEvent.LastPromptEdited` + +Emits when a query prompt in Spotter embed is edited. +- `EmbedEvent.ResetSpotterConversation` + +Emits when a Spotter query is reset. +- `EmbedEvent.PreviewSpotterData` + +Emits when a user clicks the Preview data button in the Spotter conversation panel. +- `EmbedEvent.SpotterQueryTriggered` +Emits when a Spotter query is triggered. + +The following embed events are also supported in Spotter embed: + +- `EmbedEvent.AddRemoveColumns` +- `EmbedEvent.AnswerChartSwitcher` +- `EmbedEvent.AuthExpire` +- `EmbedEvent.AuthInit` +- `EmbedEvent.CopyToClipboard` +- `EmbedEvent.CustomAction` +- `EmbedEvent.Data` +- `EmbedEvent.DataSourceSelected` +- `EmbedEvent.DialogClose` +- `EmbedEvent.DialogOpen` +- `EmbedEvent.Download` +- `EmbedEvent.DownloadAsCsv` +- `EmbedEvent.DownloadAsPng` +- `EmbedEvent.DownloadAsXlsx` +- `EmbedEvent.DrillDown` +- `EmbedEvent.DrillExclude` +- `EmbedEvent.DrillInclude` +- `EmbedEvent.Edit` +- `EmbedEvent.Error` +- `EmbedEvent.Load` +- `EmbedEvent.Pin` +- `EmbedEvent.Save` +- `EmbedEvent.TableVizRendered` +- `EmbedEvent.VizPointClick` +- `EmbedEvent.VizPointDoubleClick` +- `EmbedEvent.VizPointRightClick` + +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +|==== + +== Version 1.38.0, June 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| *String IDs for text customization* + +Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. + +To locate the string IDs, SDK provides the `exposeTranslationIds` attribute. By setting `exposeTranslationIds` to `true` in the Playground, you can find the string ID of the UI text and use it in your customization code. + +Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSON file with string IDs and custom strings to override the visible text in the UI. + +For more information, see xref:customize-text-strings.adoc[Customize text strings]. + +|[tag greenBackground]#NEW# a| *Hide columns on list pages* + + +In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: + +* *Author* + +`hiddenListColumns: [ListPageColumns.Author]` +* *Favorite* + +`hiddenListColumns: [ListPageColumns.Favourite]` +* *Last modified* + +`hiddenListColumns: [ListPageColumns.DateSort]` +* *Tags* + +`hiddenListColumns: [ListPageColumns.Tags]` +* *Share* + +`hiddenListColumns: [ListPageColumns.Share]` + + +For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. +|==== + +== Version 1.37.0, April 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| +The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. +This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. + +For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. + +|[tag greenBackground]#NEW# a| +You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. + +|[tag greenBackground]#NEW# a| This version of the SDK supports the following embed and host events: + +Embed Events:: + +* `EmbedEvent.TableVizRendered` + +Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. + +* `EmbedEvent.CreateLiveboard` + +Emits when a Liveboard is created. + +Host Events:: + +* `HostEvent.TransformTableVizData` + +Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. + +* `HostEvent.Remove` + +Triggers the *Delete* action on a Liveboard. +|==== + +== Version 1.36.0, February 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| +The following HostEvents now allow custom parameters to set object properties programmatically: + +* `HostEvent.SaveAnswer` + +Allows adding `name` and `description` text strings. When these parameters are defined, the event triggers the Save action to save the Answer with the predefined properties without opening the *Describe your Answer* modal. +* `HostEvent.Pin` + +Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. + +For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. + +|[tag greenBackground]#NEW# a| + +New configuration attributes:: + +* `disableSourceSelection` + +Disables data source selection panel for embed users when set to `true`. +* `hideSourceSelection` + +Hides data source selection panel when set to `true` +* `locale` + +Sets the xref:locale-setting.adoc[locale and regional settings] for the Spotter interface. +* `showSpotterLimitations` + +Shows functional limitations of Spotter when set to `true` +* `hideSampleQuestions` + +Hides sample questions that appear on the default Spotter page. + +Action IDs for menu customization:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions and elements in the embedded Spotter interface: + +* `Action.PreviewDataSpotter` + +The *Preview data* button on the Spotter conversation panel. +* `Action.ResetSpotterChat` + +The *Reset* button on the Spotter conversation panel. +* `Action.SpotterFeedback` + +The feedback widget on Spotter-generated charts. +* `Action.EditPreviousPrompt` + +The edit icon on the prompt panel. +The Prompt panel appears after Spotter generates a response to a user query. +* `Action.DeletePreviousPrompt` + +The delete icon on the prompt panel. + +//// +* `Action.EditTokens` + +The option to edit tokens on a Spotter-generated chart or table. +//// +CSS variables:: + +The following new CSS variables are available for Spotter interface customization: + +* `--ts-var-spotter-input-background` +* `--ts-var-spotter-prompt-background` + +For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. +|[tag greenBackground]#NEW# a| + + +Configuration attributes:: + +* `hideIrrelevantChipsInLiveboardTabs` + +Hides filter chips on a Liveboard when set to `true`. + +* `isLiveboardCompactHeaderEnabled` + +Enables the compact Liveboard header feature when set to `true`. + +Action IDs:: +Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: + +* `Action.DisableChipReorder` + +ID for the action that disables filter chip reordering. +* `Action.ChangeFilterVisibilityInTab` + +|==== + +== Version 1.35.0, December 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| +The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: + +* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface +* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. + +For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. + +|[tag greenBackground]#NEW# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. +|==== + +== Version 1.34.0, November 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| You can now embed the following ThoughtSpot Spotter components in your app: + +* `SpotterEmbed` + +Embeds Spotter conversation interface in your app +* `SpotterAgentEmbed` + +Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. + +For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. + +|[tag greenBackground]#NEW# a|The following parameters and enumerations are available for customizing Liveboard experience: + +* `showLiveboardVerifiedBadge` + +Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. +* `showLiveboardReverifyBanner` + +Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. +* `Action.KPIAnalysisCTA` + +Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. + +|[tag greenBackground]#NEW# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. + +|[tag greenBackground]#NEW# a|The following parameters are available for customizing Search experience: + +* `collapseDataPanel` +Minimizes the data panel view. Users can click the data panel header any time to expand the panel. +* `collapseSearchBar` +Sets the initial state of the search bar when embedding a saved Answer. + +|[tag greenBackground]#NEW# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: + +* `HomeLeftNavItem.LiveboardSchedules` + +The Liveboard schedules menu on the left navigation panel. + +Action enumerations:: + +* `Action.EditScheduleHomepage` + +To show, disable, or hide the *Edit* action on the *Liveboard schedules* page +* `Action.PauseScheduleHomepage` + +To show, disable, or hide the *Pause* action on the *Liveboard schedules* page +* `Action.ViewScheduleRunHomepage` + +To show, disable, or hide the *View run history* action on the *Liveboard schedules* page +* `Action.DeleteScheduleHomepage` + +To show, disable, or hide the *Delete* action on the *Liveboard schedules* page +* `Action.UnsubscribeScheduleHomepage` + +To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page +|==== + +== Version 1.33.x, October 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. + +You can set the `homePageSearchBarMode` property to one of the following options: + +** `aiAnswer` + +Displays the search bar for Natural Language Search. +** `none` +Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +** `objectSearch` (default) + +Displays Object Search bar on the **Home** page. +|[tag greenBackground]#NEW# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. +|[tag greenBackground]#NEW# a| The SDK includes the following Event and Action enumeration members: + +Events:: + +* `EmbedEvent.OnBeforeGetVizDataIntercept` + +Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. + +* `EmbedEvent.ParameterChanged` + +Emitted when a Parameter is changed on a saved Answer or Liveboard. + +Actions:: + +* `Action.ManageTags` + +Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. +|==== + +== Version 1.32.x, August 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The following new action enumerations are available in this version: + + +* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + +* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. +* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. +* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. +* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. +* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. +* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) +For more information, see xref:Action.adoc[Actions]. +|[tag greenBackground]#NEW#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. +|[tag greenBackground]#NEW# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. +|| +|==== + +== Version 1.31.x, July 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| Runtime filters + + +* `NOT_IN` operator for Runtime filters. +For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. +* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. +|[tag greenBackground]#NEW# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. +|==== + +== Version 1.30.0, June 2024 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| **CSS variables for new homepage experience** + +* `--ts-var-home-watchlist-selected-text-color` + +* `--ts-var-home-card-color` + +* `--ts-var-home-favorite-suggestion-card-text-color` + +* `--ts-var-home-favorite-suggestion-card-background` + +* `--ts-var-home-favorite-suggestion-card-icon-color` + +For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. +|==== + +== Version 1.29.0, May 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| **Ask Sage** + +With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. + +Action enumeration:: +To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, ++ +[source,JavaScript] +---- +hiddenActions: [Action.AskAi] +---- + +Events:: +* `HostEvent.AskSage` + +Triggers the **Ask Sage** action on a Liveboard visualization. +* `EmbedEvent.AskSageInit` + +Emits when the **Ask Sage** action is initialized. +* `HostEvent.GetParameters` + +Triggers a fetch action to get runtime Parameters. +* `HostEvent.UpdateParameters` + +Updates runtime Parameters +* `HostEvent.ResetLiveboardPersonalisedView` + +Resets a personalized Liveboard view. +* `HostEvent.UpdateCrossFilter` + +Updates cross filters applied on a Liveboard. +|==== + +== Version 1.28.x, April 2024 + +[width="100%" cols="1,4"] +|===== +|[tag greenBackground]#NEW# a| The SDK includes the following new enumeration members in v1.28.0: + +** `Action.VerifiedLiveboard` + +Can be used to show or hide the *Verified Liveboard* banner. +|[tag greenBackground]#NEW# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: + +* `hiddenhomeleftnavitems` +* `hiddenhomepagemodules` +* `hideapplicationswitcher` +* `hidehomepageleftnav` +* `hideorgswitcher` +* `reorderedhomepagemodules` +* `HomeLeftNavItem` + +For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. +|[tag greenBackground]#NEW# a| The following embed event is available from the v1.28.0 onwards: + +`EmbedEvent.Rename` + +Emits when an embedded Liveboard or visualization is renamed. +|[tag greenBackground]#NEW# a| TML actions + +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 +* Update TML + +To show, hide, or disable these actions in the embedded mode, use the following format: + +[source,JavaScript] +---- + // to show the TML menu and its sub-menu options +visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] +---- + +[source,JavaScript] +---- + // to hide all TML actions +hiddenActions: [Action.TML] +---- + +[source,JavaScript] +---- + // to disable all TML actions +disabledActions: [Action.TML] +---- +|[tag greenBackground]#NEW# | You can now reset authentication token and fetch a new token for new authentication requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. + +|[tag greenBackground]#NEW#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: + +* `numberFormatLocale` + +* `dateFormatLocale` + +* `currencyFormat` + +For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. + +|[tag greenBackground]#NEW# |Tokenized fetch + +The SDK now provides a fetch wrapper that adds the authentication token to the API requests. +For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. +|===== + +== Version 1.27.x, March 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The following action enumeration members are available from v1.27.9 and v1.27.10: + +* `Action.AIHighlights` +* `Action.AddToWatchlist` +* `Action.RemoveFromWatchlist` +* `Action.CopyKpiLink` + +For more information, see xref:Action.adoc[Action]. +| [tag greenBackground]#NEW# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. +|==== + +== Version 1.27.0, January 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. + +//For a complete list of methods, functions, interface objects, and properties, see the following pages: + +// +//* xref:SageEmbed.adoc[SageEmbed] +//* xref:SageViewConfig.adoc[SageViewConfig] + +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following new enumeration members: + +* Host Events +** `HostEvent.UpdateSageQuery` + +Updates the search query string for Natural Language Search operations. +* Embed Events +** `EmbedEvent.CreateConnection` + +Emitted when a user creates a new data connection on the **Data** page. +** `EmbedEvent.CreateWorksheet` + +Emitted when a user creates a new Worksheet. +|==== + +== Version 1.26.0, November 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. +You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. + +|[tag greenBackground]#NEW# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: + +* `showLiveboardDescription` + +Shows the Liveboard description text when set to `true` +* `showLiveboardTitle` + +Shows the Liveboard title when set to `true` +* `isLiveboardHeaderSticky` + +Sets Liveboard header bar as a fixed element when set to `true` +* `hideLiveboardHeader` + +Hides the Liveboard header when set to `true` +* `hiddenTabs` + +Hides the specified tabs from the Liveboard page +* `visibleTabs` + +Displays the specified tabs on the Liveboard page + +|[tag greenBackground]#NEW# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. + +|[tag greenBackground]#NEW# a|The new version of the SDK supports the following events: + +Embed events:: +* `EmbedEvent.hiddenTabs` +* `EmbedEvent.visibleTabs` +* `EmbedEvent.UpdatePersonalisedView` +* `EmbedEvent.SavePersonalisedView` +* `EmbedEvent.ResetLiveboard` +* `EmbedEvent.DeletePersonalisedView` +* `EmbedEvent.SageWorksheetUpdated` +* `EmbedEvent.SageEmbedQuery` ++ +For more information, see xref:EmbedEvent.adoc[EmbedEvent]. + +Host events:: + +* `HostEvent.GetTabs` +* `HostEvent.SetVisibleTabs` +* `HostEvent.SetHiddenTabs` +* `HostEvent.GetAnswerSession` +* `HostEvent.UpdateSageQuery` ++ +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: + +* `Action.AddTab` + +Show, disable, or hide the **Add Tab** action on a Liveboard. +* `Action.PersonalisedViewsDropdown` + +Show, disable, or hide the Liveboard views saved by a user. +* `Action.LiveboardUsers` + +Show, disable, or hide Liveboard users. +* `Action.SageAnswerFeedback` +Show, disable, or hide the feedback widget on AI-generated Answer page. +* `Action.EditSageAnswer` +Show, disable, or hide the **Edit** action on the AI-generated Answer page. + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.25.0, October 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. +For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. + +|[tag greenBackground]#NEW# a| The SDK introduces the following action enumeration members: + +* `Action.RenameModalTitleDescription` +* `Action.EnableContextualChangeAnalysis` +* `Action.RequestVerification` +* `Action.AddTab` + +For more information, see xref:Action.adoc[Actions]. +|==== + +== Version 1.24.0, September 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. +|[tag greenBackground]#NEW# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. +|==== + +== Version 1.23.0, August 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +|==== + +//// +|[tag greenBackground]#NEW# a| New events for Liveboard filters + + +* `EmbedEvent.FilterChanged` + +* `HostEvent.GetFilters` + +* `HostEvent.UpdateFilters` +//// + +== Version 1.22.0, June 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. + +For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. + +|[tag greenBackground]#NEW# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. + +For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. + +|==== + +//// +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + + +* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. +* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. +//// + +== Version 1.21.0, May 2023 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following action enumeration members: + +* `Action.AxisMenuAggregate` +* `Action.AxisMenuConditionalFormat` +* `Action.AxisMenuEdit` +* `Action.AxisMenuFilter` +* `Action.AxisMenuGroup` +* `Action.AxisMenuNumberFormat` +* `Action.AxisMenuPosition` +* `Action.AxisMenuRemove` +* `Action.AxisMenuRename` +* `Action.AxisMenuSort` +* `Action.AxisMenuTextWrapping` +* `Action.AxisMenuTimeBucket` +* `Action.CrossFilter` +* `Action.RemoveCrossFilter` + +For more information, see xref:embed-action-ref.adoc[Action reference]. + +|[tag greenBackground]#NEW# a| The SDK introduces the following events: + +* `HostEvent.AddColumns` +* `HostEvent.OpenFilter` +* `HostEvent.RemoveColumn` +* `HostEvent.ResetSearch` +* `EmbedEvent.CrossFilterChanged` +* `EmbedEvent.DownloadAsPng` +* `EmbedEvent.VizPointRightClick` + +For more information, see xref:embed-events.adoc[Events]. + +|[tag redBackground]#DEPRECATED# a| + +The following events are deprecated from version 1.21.0 onwards. + +* `HostEvent.Download` + +* `EmbedEvent.Download` + +You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. + +For more information, see xref:embed-events.adoc[Events reference]. +|[tag orangeBackground]#MODIFIED# a| + +Events:: +The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. +Actions:: +Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: ++ +* `Action.DownloadAsCsv` +* `Action.DownloadAsPdf` +* `Action.DownloadAsXlsx` +* `Action.DownloadAsPng` + +To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` + +|[tag greenBackground]#NEW# a| The SDK includes new attributes to customize the experience for embedded app users: + +* `linkOverride` ++ +Allows overriding the *Open in new tab* link on embedded pages. + +* `contextMenuTrigger` ++ +Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. + +* `hideSearchBar` ++ +Allows hiding the Search bar on the embedded Search page. +|[tag greenBackground]#NEW# | The SDK now allows setting the loading preference for embedded iFrames. +For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. +|==== + +== Version 1.20.0, April 2023 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. +|[tag greenBackground]#NEW# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. +|==== + +== Version 1.19.0, February 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: + +[source,JavaScript] +---- +liveboardEmbed.on(EmbedEvent.CustomAction, payload => { + if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { + console.log('Custom Action event:', payload.data); + } +}) +---- + +You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. + +|[tag greenBackground]#NEW# a|The new version of the SDK introduces the following Host events: + +* `HostEvent.Delete` +* `HostEvent.Download` +* `HostEvent.DownloadAsCsv` +* `HostEvent.DownloadAsXlsx` +* `HostEvent.ManagePipelines` +* `HostEvent.Save` +* `HostEvent.Share` +* `HostEvent.ShowUnderlyingData` +* `HostEvent.SpotIQAnalyze` +* `HostEvent.SyncToOtherApps` +* `HostEvent.SyncToSheets` + +For more information, see xref:events-hostEvents.adoc[Host events]. + +|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. + +For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. +|==== + +== Version 1.18.0, January 2023 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + + +For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. + +|[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|[tag greenBackground]#NEW# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + + +For more information, see xref:HostEvent.adoc#_gettml[GetTML]. + +|[tag greenBackground]#NEW# a| The new version of the SDK introduces the following enums in the `Action` object: + +* `Action.SyncToOtherApps` + +* `Action.SyncToSheets` + +* `Action.ManagePipelines` + + +You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. + +For more information, see xref:embed-action-ref.adoc[Actions]. +|==== + +== Version 1.17.1, December 2022 + +Bug fixes to the trusted authentication feature. + +== Version 1.17.0, November 2022 + +The new version of the SDK introduces several new features and enhancements. +[width="100%" cols="1,4"] +|==== +|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + + +* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + +* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + +* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + +This enhancement does not introduce any breaking changes to your current implementation. +|[tag greenBackground]#NEW# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + +For more information, see xref:embed-authentication.adoc[Authentication]. +|[tag greenBackground]#NEW#| +The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + +For more information, see xref:css-customization.adoc[Customize CSS]. +|==== + +== Version 1.16.0, October 2022 + +The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. + +== Version 1.15.1, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| +The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. +|==== + +== Version 1.15.0, September 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| +For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. + +For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]. + +|[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: + +* CopyLink +* CreateMonitor +* DownloadAsPdf +* Edit +* EditTML +* Explore +* ExportTML +* LiveboardInfo +* MakeACopy +* ManageMonitor +* Pin +* Present +* Remove +* Schedule +* SchedulesList +* UpdateTML + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.14.0, August 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| +The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. +|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. +The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. +|==== + +== Version 1.13.0, July 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| +This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. +|[tag greenBackground]#NEW#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + +For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. +|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + +This change does not impact your current embed implementation with `AuthType.SSO`. +|[tag greenBackground]#NEW#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.12.0, June 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| +This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. + +For more information, see xref:events-hostEvents.adoc[Events reference]. +|[tag greenBackground]#NEW# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. +|==== + +== Version 1.11.2, June 2022 + +Bug fix for Typescript builds that affect Angular project configurations. + +== Version 1.11.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. +|==== + +== Version 1.11.0, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The new version of SDK includes the following new events: + +* `ALL` +* `AnswerChartSwitcher` +* `AnswerDelete` +* `CopyAEdit` +* `CopyToClipboard` +* `Download` +* `DownloadAsPdf` +* `DownloadAsCsv` +* `DownloadAsXlsx` +* `DrillExclude` +* `DrillInclude` +* `EditTML` +* `ExportTML` +* `Monitor` +* `Pin` +* `Save` +* `SaveAsView` +* `Share` +* `ShowUnderlyingData` +* `SpotIQAnalyze` +* `UpdateTML` +* `VizPointClick` + +For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. +|[tag greenBackground]#NEW# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. + +|[tag greenBackground]#NEW# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. +|==== + +== Version 1.10.4, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. +|==== +== Version 1.10.3, May 2022 + +Bug fix and improvements to the `logout` method. + +== Version 1.10.2, May 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. +|==== + +== Version 1.10.1, May 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#|You can now use the `logout` method to log out embed users. +|[tag orangeBackground]#MODIFIED# a| Note the following changes: + + +* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. +* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. +|==== + +== Version 1.10.0, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.8, April 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. + +For more information, see xref:full-embed.adoc[Embed full application]. +|==== + +== Version 1.9.6 and 1.9.7, April 2022 + +Bug fixes and improvements + +== Version 1.9.5, April 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. +For more information, see xref:locale-setting.adoc[Set locale and display language]. +|==== + +== Version 1.9.4, April 2022 + +Bug fixes and improvements to React components. + +== Version 1.9.3, March 2022 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + +You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + +This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. + +For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. +|==== + +== Version 1.9.2, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| You can now trigger events on React components using the `useEmbedRef` hook. + +For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. +|==== + +== Version 1.9.1, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. + +For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. + +|[tag greenBackground]#NEW# a| The following events are now available in the SDK: + + +* `LiveboardRendered` (EmbedEvent) + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.9.0, March 2022 +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a| The SDK now includes the following new enumerations for UI actions: + +* `Action.AnswerDelete` + +* `Action.AnswerChartSwitcher` + +* `Action.AddToFavorites` + +* `Action.EditDetails` + + +For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. + +|[tag greenBackground]#NEW# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. +|==== + +== Version 1.8.x, February 2022 + +[width="100%" cols="1,4"] +|==== +|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. +|[tag greenBackground]#NEW# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. +|==== + + +== Version 1.7.0, January 2022 + +[width="100%" cols="1,4"] +|==== +| +[tag greenBackground]#NEW# |+++
OIDC AuthType
+++ + +The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. + +For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. +|[tag greenBackground]#NEW# a|+++
Embed events
+++ + +The SDK includes the following new event: + +* `RouteChange` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.6.x, November 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|+++
Visible actions
+++ + +You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. + +For more information, see xref:embed-actions.adoc[Show or hide UI actions]. + +|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ + +The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. + +|[tag greenBackground]#NEW# a|+++
Embed events
+++ + +The SDK supports the following new events: + +* `DialogOpen` +* `DialogClose` + +For more information, see xref:event-embedEvents.adoc[Events reference]. +|==== + +== Version 1.5.0, October 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW# | +++
Render embedded objects in queue
+++ + +The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. + +|[tag greenBackground]#NEW# a|+++
Liveboard embed
+++ + +The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. + +For more information, see xref:embed-search.adoc[Embed a pinboard]. + +|[tag greenBackground]#NEW# a|+++
Embed events
+++ + +The SDK EmbedEvent library includes the following new events: + +* `VizPointDoubleClick` +* `Drilldown` +* `SetVisibleVizs` + +For more information, see xref:event-embedEvents.adoc[Events reference]. + +|==== + +== Version 1.4.0, September 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW# a|+++
+++Prefetch API+++
+++ + +The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. + +For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. + +|[tag greenBackground]#NEW# a|+++
+++In-app page navigation+++
+++ + +The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. + +For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. + +|[tag greenBackground]#NEW# a|+++
+++Full application embedding+++
+++ + +The `appEmbed` SDK package includes the following new attributes: + +* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. + +* The `hideObjects` attribute to hide specific objects from a user's page view. + +For more information, see xref:full-embed.adoc[Embed full application]. + +|[tag greenBackground]#NEW# |+++
+++Search embed +++
+++ + +The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. + +For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. + +|[tag redBackground]#REMOVED# | + +The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. +|[tag greenBackground]#NEW# a|+++
+++Embed events +++
+++ +The SDK EmbedEvent library includes the following events: + +* `QueryChanged` +* `AuthExpire` + +For more information, see xref:embed-events.adoc[Events and app integration]. +|==== + +== Version 1.3.0, August 2021 + +[width="100%" cols="1,4"] +|==== +|| +|[tag greenBackground]#NEW# a| +++
searchOptions
+++ + +The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: + +* `searchTokenString` ++ +A TML query string to define search tokens. + +* `executeSearch` ++ +When set to `true`, it executes search and shows the search results. + +For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ + +The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. + +For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. + +|[tag greenBackground]#NEW# a| +++
autoLogin
+++ + +The SDK now supports logging in users automatically after a user session has expired. + +For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. + +|[tag greenBackground]#NEW# a| +++
shouldEncodeUrlQueryParams
+++ + +You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. +|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ + +* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. + +* The Answer payload for custom actions includes the following metadata: + +** `reportBookmetadata` ++ +Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. + +** user data ++ +Includes user information such as username, GUID of the user, and email address. + +To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. + +|[tag greenBackground]#NEW# a| +++
preventPinboardFilterRemoval
+++ + +The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. + +For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. +|[tag greenBackground]#NEW# a| +++
suppressNoCookieAccessAlert
+++ + +You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. + +|[tag greenBackground]#NEW# a| +++
Support for fetching callback custom action payload in batches
+++ + +The Visual Embed SDK now supports processing data in batches for callback custom action responses. +The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. + +For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. +|==== + +== Version 1.2.0, June 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|+++
SAML authentication
+++ + +The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. + +For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. + +|[tag greenBackground]#NEW# a|+++
Pinboard actions
+++ +The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. + +Pinboard:: +* Save +* Make a copy +* Add filters +* Configure filters +* Present +* Download as PDF +* Pinboard info +* Manage schedules + + +[NOTE] +Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. +|[tag greenBackground]#NEW# a|+++
Visualization actions
+++ + +Visualizations on a pinboard: + +* Pin +* Download +* Edit +* Present +* Download as CSV +* Download as XLSX +* Download as PDF + +[NOTE] +Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. + +|==== + +== Version 1.1.0, May 2021 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW# a|+++
NoCookieAccess event
+++ -... [truncated, 10,859 chars total] \ No newline at end of file +When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. +To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. +|==== From 5bcff1fa25dd1fc8c9b0ed178a06f78b4e82490e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 08:59:54 +0530 Subject: [PATCH 048/169] docs: restore full SDK changelog and add November 2026 (v1.54.0) entry From e89b40d7fe56dc18629c020f7c05def78c7980fc Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:00:36 +0530 Subject: [PATCH 049/169] docs: restore full embed-spotter.adoc and add SpotterX code sample --- modules/ROOT/pages/embed-spotter.adoc | 317 +++++++++++++++++++++++--- 1 file changed, 288 insertions(+), 29 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index 88cb53786..2c626bf0f 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -1,19 +1,283 @@ ---- CITABLE SOURCE --- -File: modules/ROOT/pages/embed-spotter.adoc -Branch: docs/scal-26-11-0-cl-doc-updates -URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc -To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc#L{line_number} ---- += Embed Spotter experience +:toc: true +:toclevels: 2 -{ - "path": "modules/ROOT/pages/embed-spotter.adoc", - "name": "embed-spotter.adoc", - "size": 9266, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/embed-spotter.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/embed-spotter.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/embed-spotter.adoc\",\n \"name\": \"embed-spotter.adoc\",\n \"size\": 11010,\n \"content\": \"= Embed Spotter experience\\n:toc: true\\n:toclevels: 2\\n\\n:page-title: Embed Spotter\\n:page-pageid: embed-spotter\\n:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application.\\n\\nYou can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application.\\n\\n== Before you begin\\n\\nTo embed Spotter, you need the following access and setup:\\n\\n* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance.\\n* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists].\\n* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK].\\n\\n[NOTE]\\n====\\nFor Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the `refreshAuthTokenOnNearExpiry` parameter to `true`. +\\nSpotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes.\\n====\\n\\n== Import the SDK package\\nImport the `SpotterEmbed` SDK library to your application environment:\\n\\n**npm**\\n[source,JavaScript]\\n----\\nimport {\\n SpotterEmbed,\\n AuthType,\\n init,\\n prefetch,\\n EmbedEvent,\\n HostEvent\\n} from '@thoughtspot/visual-embed-sdk';\\n----\\n\\n**ES6**\\n[source,JavaScript]\\n----\\n\\n----\\n\\n== Initialize the SDK\\n\\nTo initialize the SDK, the following information is required:\\n\\n* `thoughtSpotHost` +\\nThe xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance.\\n* `authType` +\\nAuthentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication].\\n\\n[source,JavaScript]\\n----\\ninit({\\n thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL\\n authType: AuthType.None, // Use the appropriate AuthType for your setup\\n});\\n----\\n\\n== Create an instance of the SpotterEmbed object\\n\\nCreate an instance of the `SpotterEmbed` object.\\n\\nIf you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources.\\n\\n[IMPORTANT]\\n====\\nAuto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.\\n====\\n\\n[source,JavaScript]\\n----\\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\\n frameParams: {\\n width: '100%',\\n height: '100%',\\n },\\n worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode',\\n //... other attributes\\n});\\n----\\n\\n=== Customize your embed (Optional)\\nThe SDK provides configuration settings to customize the embedded Spotter interface.\\nFor example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters.\\n\\n[source,JavaScript]\\n----\\nconst conversation = new SpotterEmbed(document.getElementById('ts-embed'), {\\n //...other embed configuration attributes\\n hideSampleQuestions: true,\\n disableSourceSelection: true\\n});\\n----\\nFor more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface].\\n\\n=== Register event listeners\\n\\nTo listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers.\\n\\nThe following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners.\\n\\n[source,JavaScript]\\n----\\n// Register event listeners\\nspotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts\\nspotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded\\n----\\n\\n\\n[source,JavaScript]\\n----\\n// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load\\nspotterEmbed.on(EmbedEvent.Subscribed, (eventData) => {\\n if (eventData.data.hostEventType === 'ResetSpotterConversation') {\\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\\n }\\n});\\n----\\n\\nTo trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events].\\n\\nThe following example shows the host event to reset a Spotter conversation session:\\n\\n[source,JavaScript]\\n----\\n// Example: Add a host event to reset the Spotter conversation\\ndocument.getElementById('resetBtn').addEventListener('click', () => {\\n spotterEmbed.trigger(HostEvent.ResetSpotterConversation);\\n});\\n----\\n\\n=== Render the embedded object\\n\\n[source,JavaScript]\\n----\\nspotterEmbed.render();\\n----\\n\\n=== Verify your embed\\n\\n* Load the embedded object.\\n** If the embedding is successful, you'll see the Spotter page.\\n** Initiate a chat session, ask a question, and view the results.\\n** If you see a blank screen:\\n*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible.\\n*** Verify whether the authentication credentials used in your code are valid.\\n* Verify whether the customization settings are applied.\\n\\n[#configControls]\\n== Customizing the embedded Spotter interface\\nWhen 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].\\n\\n== Code samples\\n\\n**Code sample for embedding Spotter Classic and Spotter 2 experience**\\n\\n[source,JavaScript]\\n----\\nimport {\\n SpotterEmbed,\\n SpotterEmbedViewCo +:page-title: Embed Spotter +:page-pageid: embed-spotter +:page-description: You can use the SpotterEmbed SDK library to embed conversational analytics experience in your application. -... [truncated, 10,248 chars total] +You can embed the full Spotter experience in your applications using the `SpotterEmbed` component in the Visual Embed SDK. Using the customization settings available in the SDK for each Spotter version, you can configure the Spotter interface to suit the needs of your embedding application. -**Code sample for embedding SpotterX experience** +== Before you begin + +To embed Spotter, you need the following access and setup: + +* Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance. +* Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists]. +* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK]. + +[NOTE] +==== +For Spotter embedding that uses cookieless authentication, use Visual Embed SDK version 1.45.0 or later with ThoughtSpot Cloud version 26.2.0.cl or later. To enable proactive token refresh, set the `refreshAuthTokenOnNearExpiry` parameter to `true`. + +Spotter workflows may run longer at times. To prevent authorization errors, set the authentication token expiration to at least 10 minutes. +==== + +== Import the SDK package +Import the `SpotterEmbed` SDK library to your application environment: + +**npm** +[source,JavaScript] +---- +import { + SpotterEmbed, + AuthType, + init, + prefetch, + EmbedEvent, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; +---- + +**ES6** +[source,JavaScript] +---- + +---- + +== Initialize the SDK + +To initialize the SDK, the following information is required: + +* `thoughtSpotHost` + +The xref:faqs.adoc#tsHostName[hostname] of your ThoughtSpot application instance. +* `authType` + +Authentication type. For testing purposes, you can use `AuthType.None`. For information about other authentication options, see xref:embed-authentication.adoc[Authentication]. + +[source,JavaScript] +---- +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL + authType: AuthType.None, // Use the appropriate AuthType for your setup +}); +---- + +== Create an instance of the SpotterEmbed object + +Create an instance of the `SpotterEmbed` object. + +If you are embedding the Spotter Classic or Spotter 2 experience, the data source ID is required. If Spotter 3 experience is enabled on your instance, you can either specify the data source ID or enable the *Auto mode* to allow Spotter to automatically discover and select data sources. + +[IMPORTANT] +==== +Auto mode is disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + worksheetId: '<%=datasourceGUID%>', // ID of the data source object. To use the Auto mode, set the ID to 'auto_mode', + //... other attributes +}); +---- + +=== Customize your embed (Optional) +The SDK provides configuration settings to customize the embedded Spotter interface. +For example, you can hide sample questions or disable data source selection using the `hideSampleQuestions` and `disableSourceSelection` parameters. + +[source,JavaScript] +---- +const conversation = new SpotterEmbed(document.getElementById('ts-embed'), { + //...other embed configuration attributes + hideSampleQuestions: true, + disableSourceSelection: true +}); +---- +For more information and examples, see xref:embed-spotter.adoc#configControls[Customizing the embedded Spotter interface]. + +=== Register event listeners + +To listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers. + +The following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners. + +[source,JavaScript] +---- +// Register event listeners +spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts +spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded +---- + + +[source,JavaScript] +---- +// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load +spotterEmbed.on(EmbedEvent.Subscribed, (eventData) => { + if (eventData.data.hostEventType === 'ResetSpotterConversation') { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); + } +}); +---- + +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: + +[source,JavaScript] +---- +// Example: Add a host event to reset the Spotter conversation +document.getElementById('resetBtn').addEventListener('click', () => { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); +}); +---- + +=== Render the embedded object + +[source,JavaScript] +---- +spotterEmbed.render(); +---- + +=== Verify your embed + +* Load the embedded object. +** If the embedding is successful, you'll see the Spotter page. +** Initiate a chat session, ask a question, and view the results. +** If you see a blank screen: +*** Verify that your embed code has the correct ThoughtSpot host URL. Ensure that your ThoughtSpot instance is accessible. +*** Verify whether the authentication credentials used in your code are valid. +* Verify whether the customization settings are applied. + +[#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. 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 + +**Code sample for embedding Spotter Classic and Spotter 2 experience** + +[source,JavaScript] +---- +import { + SpotterEmbed, + SpotterEmbedViewConfig, + SpotterChatViewConfig, + AuthType, + init, + prefetch, + EmbedEvent, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; + +// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL + authType: AuthType.None, // Use the appropriate AuthType for your setup +}); + +//Define event handler to show a loading indicator when the embed is initializing. +function showLoader() { + // Show loading indicator +} + +// Define event handler to hide the loading indicator when the embed has loaded. +function hideLoader() { + // Hide loading indicator +} + +// Find the container element in your HTML where the SpotterEmbed will be rendered. +const container = document.getElementById('ts-embed'); +if (container) { + // Create and configure the SpotterEmbed + const spotterEmbed = new SpotterEmbed(container, { + frameParams: { + height: '100%', // Set the height of the embedded frame + width: '100%', // Set the width of the embedded frame + }, + worksheetId: 'your-worksheet-id', // ID of the data source object to query data from + //... other configuration attributes + }); + + // Register event listeners + spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts + spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded + + // Render the SpotterEmbed in the container. + spotterEmbed.render(); + // Example: Add a host event to reset the Spotter conversation + document.getElementById('resetBtn').addEventListener('click', () => { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); + }); +} +---- + +**Code sample for embedding Spotter 3 experience** + +[source,JavaScript] +---- +import { + SpotterEmbed, + AuthType, + init, + EmbedEvent, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; +// Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL + authType: AuthType.None, // Use the appropriate AuthType for your setup +}); + +//Define event handler to show a loading indicator when the embed is initializing. +function showLoader() { + // Show loading indicator +} + +// Define event handler to hide the loading indicator when the embed has loaded. +function hideLoader() { + // Hide loading indicator +} + +// Find the container element in your HTML where the SpotterEmbed will be rendered. +const container = document.getElementById('ts-embed'); +if (container) { + // Create and configure the SpotterEmbed + const spotterEmbed = new SpotterEmbed(container, { + frameParams: { + height: '100%', // Set the height of the embedded frame + width: '100%', // Set the width of the embedded frame + }, + worksheetId: 'your-worksheet-id', // ID of the data source object to query data from. For automatic model discovery and selection (Auto mode), specify 'auto_mode' + updatedSpotterChatPrompt: true, // Enable new chat interface + enablePastConversationsSidebar: true, // Enable chat history + //... other configuration attributes + }); + + // Register event listeners + spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization starts + spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded + + // Render the SpotterEmbed in the container. + spotterEmbed.render(); + // Example: Add a host event to reset the Spotter conversation + document.getElementById('resetBtn').addEventListener('click', () => { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); + }); +} +---- + **Code sample for embedding SpotterX experience** [source,JavaScript] ---- @@ -25,20 +289,11 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs HostEvent } from '@thoughtspot/visual-embed-sdk'; - // Initialize the ThoughtSpot Visual Embed SDK init({ thoughtSpotHost: 'https://your-thoughtspot-host', authType: AuthType.None, }); - function showLoader() { - // Show loading indicator - } - - function hideLoader() { - // Hide loading indicator - } - const container = document.getElementById('ts-embed'); if (container) { const spotterEmbed = new SpotterEmbed(container, { @@ -46,18 +301,22 @@ To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs height: '100%', width: '100%', }, - worksheetId: 'your-worksheet-id', // For Auto mode, specify 'auto_mode' - spotterVersion: SpotterVersion.SpotterX, // Enable SpotterX - //... other configuration attributes + worksheetId: 'your-worksheet-id', + spotterVersion: SpotterVersion.SpotterX, + // ... other configuration attributes }); - // Register event listeners spotterEmbed.on(EmbedEvent.Init, showLoader); spotterEmbed.on(EmbedEvent.Load, hideLoader); - - // Render the SpotterEmbed spotterEmbed.render(); } ---- - \ No newline at end of file + + +== Additional resources +* xref:embed-ai-analytics.adoc[Spotter features and embedding options] +* link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods] +* link:https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig[Configuration options for Spotter interface customization] +* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed[Developer examples, window=_blank] +* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Product Documentation] From 0f33bd2cf83ba4981fb9b28da0c0434affcc8ac2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:00:38 +0530 Subject: [PATCH 050/169] docs: restore full embed-spotter.adoc and add SpotterX code sample From 001c0a6bb1d55cc9c49332159f6b119cf985b220 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:00:57 +0530 Subject: [PATCH 051/169] docs: restore full locale-setting.adoc and add 4 new locales (pl, ro, tr, uk) --- modules/ROOT/pages/locale-setting.adoc | 128 ++++++++++++++++++++++++- 1 file changed, 127 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/locale-setting.adoc b/modules/ROOT/pages/locale-setting.adoc index ec6077f68..cca8039b4 100644 --- a/modules/ROOT/pages/locale-setting.adoc +++ b/modules/ROOT/pages/locale-setting.adoc @@ -1 +1,127 @@ -Unknown tool: github_get_file \ No newline at end of file += Customize locale +:toc: true +:toclevels: 1 + +:page-title: Set locale +:page-pageid: set-locale +:page-description: You can change the locale settings of your embedded app to display the UI elements in your preferred language and use the Manual translation REST APIs to supply custom translations for ThoughtSpot UI strings. + +The display language of the embedded ThoughtSpot UI is determined by the user's system locale. +If your browser locale matches one of the locale options supported by ThoughtSpot, the ThoughtSpot UI automatically changes to that locale. If your browser locale is not supported by ThoughtSpot, the embedded UI is displayed in US English by default. For example, if your browser locale is an unsupported Central American locale, such as Spanish (Mexico) (es-MX), ThoughtSpot launches in en-US. If your browser doesn't allow you to change the locale, ThoughtSpot launches in the OS locale. + +If your organization manages your browser settings, and your administrator or developer has already set your browser locale, ThoughtSpot automatically defaults to that locale. + +You can set locale via ThoughtSpot UI, API, and Visual Embed SDK. + +=== Set Locale in the SDK + +If you want to set your embedded app view to a specific locale for your application users, you can configure the `locale` property in the SDK. + +==== Supported locale IDs + +[width="60%", cols="1,2"] +[options="header"] +| `pl-PL` | Polski + | `ro-RO` | Română + | `tr-TR` | Türkçe + | `uk-UA` | Українська + |==================== +| Locale | Language +| `da-DK` | Dansk +| `de-DE` | Deutsch +| `de-CH` | Deutsch (Switzerland) +| `en-AU` | English (Australia) +| `en-CA` | English (Canada) +| `en-DE` | English (Germany) +| `en-IN` | English (India) +| `en-NZ` | English (New Zealand) +| `en-GB` | English (United Kingdom) +| `en-US` | English (United States) +| `es-ES` | Español +| `es-US` | Español (Latinoamérica) +| `es-MX` | Español (Mexico) +| `fr-CA` | Français (Canada) +| `fr-FR` | Français (France) +| `ja-JP` | 日本語 +| `ko-KR` | 한국어 +| `it-IT` | Italiano +| `nb-NO` | Norsk +| `nl-NL` | Nederland +| `pt-BR` | Português (Brasil) +| `pt-PT` | Português (Portugal) +| `ru-RU` | Pусский (ограниченный выпуск) +| `fi-FI` | Suomi +| `sv-SE` | Svenska +| `zh-CN` | 中文(简体) +| `zh-HANT`| 中文 (繁體) +|==================== + +This example sets the locale of the embedded Liveboard to `Español`. + +[source,Javascript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '<%=liveboardGUID%>', + locale: 'es-ES', +}); +---- + +The `locale` property defines the overall language of the app, and the default formats for numbers, dates, and currencies. To override the default number, date, and currency format set by the `locale` parameter, define the following attributes in the `init` code as shown in this example: + +[source,Javascript] +---- +init({ + //... + numberFormatLocale: 'en-US', + dateFormatLocale: 'en-IN', + currencyFormat: 'USD', +}); +---- + +* `numberFormatLocale` __String__ + +Specify your preferred locale identifier. The numbers on the embedded visualizations will be displayed as per the defined format. For example, if you specify `en-US`, large numbers on the visualizations will be displayed with the comma thousands separator and a period decimals separator as shown here: ++ +`xxx,xxx.xx` + +* `dateFormatLocale` __String__ + +Specify your preferred locale identifier. For example, setting `en_US` shows the date format as `MM/dd/yyyy`. + +* `currencyFormat` __String__ + +Specify a three-digit currency ISO code. For example, to set currency format to United States dollar, specify `USD`. + +== Locale settings in the UI + +//// +If you have embedded the full ThoughtSpot app, your application users can set the locale on their profile settings page. The profile settings page will be visible to your users only when the `disableProfileAndHelp` attribute is set to `false` and `showPrimaryNavbar` set to `true` in the SDK. + +//// + +ThoughtSpot application users can set their locale preference on the Profile settings page. To open the profile settings page, click the user icon on the top navigation bar and then edit your locale preference. + +For more information, see link:https://docs.thoughtspot.com/cloud/latest/locale[ThoughtSpot Product Documentation, window=_blank]. + +== Set locale via REST API +To configure locale settings for a user via REST API, ThoughtSpot administrator can use the `"use_browser_language": true` or `"preferred_locale": "en-US"` settings when creating, importing, or updating user using the following API endpoints: + +* +++ POST /api/rest/2.0/users/create+++ (user creation) +* +++POST /api/rest/2.0/users/{user_identifier}/update +++ (User update) +* +++ POST /api/rest/2.0/users/import+++ (User import) + +The `preferred_locale` parameter allows assigning a specific locale to the user, whereas the `use_browser_language` parameter determines whether the user's language preference should be set based on their browser's language settings. When both parameters are defined, the user's current locale preference is overridden and the browser's language takes precedence. + +To get details of the browser language settings for a given user, administrators can use the following API endpoints: + +* `POST /api/rest/2.0/users/search` + +* `POST /api/rest/2.0/users/activate` + +* `GET /api/rest/2.0/auth/session/user` + + +== Limitations + +* By default, ThoughtSpot does not automatically translate column names, object titles, description text, formulas, or metadata entered by the user. For example, if you name a visualization *Sales performance* in any variant of English and subsequently change the locale to Español, the name of the visualization remains *Sales performance*. + +To supply custom translations for ThoughtSpot UI strings programmatically, use the xref:manual-translation-api.adoc[Manual Translation REST APIs]. +* If you specify a currency when uploading data, that currency format does not change when the locale changes. +* ThoughtSpot translates keywords, operators, and error messages. See link:https://docs.thoughtspot.com/cloud/latest/keywords[Keyword reference, window=_blank] for all supported languages. \ No newline at end of file From 29579f832a2c47f13af4bbfe26f2ee93f2875444 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:00:59 +0530 Subject: [PATCH 052/169] docs: restore full locale-setting.adoc and add 4 new locales (pl, ro, tr, uk) From 6d6d1bb595418c6df71ea4fb8e9f7e2ddc0b276e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:01:00 +0530 Subject: [PATCH 053/169] docs: restore full locale-setting.adoc and add 4 new locales (pl, ro, tr, uk) From 1949ca42f940bc770f07b55539823f0340dd121c Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Mon, 12 Oct 2026 09:01:01 +0530 Subject: [PATCH 054/169] docs: restore full locale-setting.adoc and add 4 new locales (pl, ro, tr, uk) From 7191ba6347a532aa5235544fff75e7a7f5573679 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 09:41:10 +0530 Subject: [PATCH 055/169] obj id updtes --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 14 +- modules/ROOT/pages/object-id.adoc | 214 +++++++++--------- 2 files changed, 114 insertions(+), 114 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index ad5b32f96..d68abe02a 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -19,22 +19,22 @@ image::./images/object_model_hierarchy.png[Object Model Hierarchy] == Object identifiers [#object-identifiers] -Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID. +Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. ##Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID.## [#_supported_object_types] Supported objects also have an Object ID (`obj_id`) property that is *user-settable* and *unique per Org*. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID. The `obj_id` appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. [#_obj_id_format_and_constraints] -Because you choose the `obj_id`, related copies of an object in different Orgs and instances can share the same value. This allows ThoughtSpot to match objects during TML import without manual GUID mapping, and allows you to reference objects in REST API requests and ThoughtSpot URLs with the same identifier in every environment. +Because you choose the `obj_id`, related copies of an object in different Orgs and instances can share the same value. This allows ThoughtSpot to match objects during TML import without manual GUID mapping, ##and allows you to reference objects in REST API requests and ThoughtSpot URLs with the same identifier in every environment.## [#_obj_id_resolution] -For more information, see the following pages: +##For more information, see the following pages:## [#_setting_and_updating_obj_id] * xref:object-id.adoc[Object ID (obj_id)] + -Supported object types, `obj_id` format and constraints, how identifiers are resolved, and how to set or update an `obj_id`. +##Supported object types, `obj_id` format and constraints, how identifiers are resolved, and how to set or update an `obj_id`.## * xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs] + -Use an `obj_id` instead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs. +##Use an `obj_id` instead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs.## == Data modeling A data model requires at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. @@ -110,7 +110,7 @@ The `POST /api/rest/2.0/metadata/search` REST API v2.0 endpoint returns the foll * `metadata_id` + GUID of the object. Unique within a given ThoughtSpot instance. * `metadata_obj_id` + -User-defined string identifier for the object (`obj_id`). Unique within a given Org. For more information, see xref:object-id.adoc[Object ID (obj_id)]. +User-defined string identifier for the object (`obj_id`). Unique within a given Org. ##For more information, see xref:object-id.adoc[Object ID (obj_id)].## * `metadata_name` + Name of the object. * `metadata_type` + @@ -148,7 +148,7 @@ Object type names in ThoughtSpot REST API v2.0 differ from the names shown in th * *Tags*: `TAG` * *Users*: `USER` * *Groups*: `USER_GROUP` -* *Collections*: `COLLECTION` +* ##*Collections*: `COLLECTION`## For the `LOGICAL_TABLE` type, you can also specify the following values in the `subtypes` attribute to filter the results: diff --git a/modules/ROOT/pages/object-id.adoc b/modules/ROOT/pages/object-id.adoc index 576aeca31..6639c3e3e 100644 --- a/modules/ROOT/pages/object-id.adoc +++ b/modules/ROOT/pages/object-id.adoc @@ -6,24 +6,24 @@ :page-pageid: object-id :page-description: Use Object ID (obj_id) to reference ThoughtSpot objects by a stable, user-defined identifier across Orgs and instances -Every object in ThoughtSpot has a system-generated GUID. GUIDs are minted per instance, so the same Liveboard promoted from a development environment to a production environment has a different GUID in each one. +##Every object in ThoughtSpot has a system-generated GUID. GUIDs are minted per instance, so the same Liveboard promoted from a development environment to a production environment has a different GUID in each one.## -An Object ID (`obj_id`) is a customer-defined, human-readable identifier that you assign to an object in addition to its GUID. An `obj_id` survives renames, TML export and import, and moves between Orgs and instances. Because you choose the value, related copies of an object in different Orgs can share the same `obj_id`, and your deployment scripts, Git-based CI/CD pipelines, and host application can reference the object without maintaining a GUID mapping for each environment. +An Object ID (`obj_id`) is a customer-defined, human-readable identifier that you assign to an object in addition to its GUID. ##An `obj_id` survives renames, TML export and import, and moves between Orgs and instances.## Because you choose the value, related copies of an object in different Orgs can share the same `obj_id`, ##and your deployment scripts, Git-based CI/CD pipelines, and host application can reference the object without maintaining a GUID mapping for each environment.## -Object ID is generally available from ThoughtSpot Cloud 26.9.0.cl. +##Object ID is generally available from ThoughtSpot Cloud 26.9.0.cl.## == Key concepts * `obj_id` is *user-settable* and *unique per Org*. Each Org can have only one object with a particular `obj_id`. -* The combination of Org ID and `obj_id` is the uniqueness key, so the same `obj_id` in two Orgs refers to two different objects. This is by design. +* The combination of Org ID and `obj_id` is the uniqueness key, ##so the same `obj_id` in two Orgs refers to two different objects. This is by design.## * The `obj_id` of an object is returned as `metadata_obj_id` in the `POST /api/rest/2.0/metadata/search` API response, and as `obj_id` in TML. -* Object ID is the key that TML-based deployment, xref:publishing-overview.adoc[publishing], and xref:git-provider-integration.adoc[Git provider integration] build on. +* ##Object ID is the key that TML-based deployment, xref:publishing-overview.adoc[publishing], and xref:git-provider-integration.adoc[Git provider integration] build on.## == Enable Object ID -Object ID must be enabled on your ThoughtSpot instance before `obj_id` participates in TML export, TML import, and metadata search. Until it is enabled, ThoughtSpot continues to resolve objects by GUID and name. +Object ID must be enabled on your ThoughtSpot instance ##before `obj_id` participates in TML export, TML import, and metadata search. Until it is enabled, ThoughtSpot continues to resolve objects by GUID and name.## -To use `obj_id` in ThoughtSpot URLs, an additional setting is required. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. +##To use `obj_id` in ThoughtSpot URLs, an additional setting is required. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs].## == Supported object types @@ -31,81 +31,81 @@ The following object types support `obj_id`: [cols="2,2,4", options="header"] |=== -|Object type |TML kind |Notes - -|Liveboard |`liveboard` |Exported in TML and resolved first on import. -|Answer |`answer` | -|Model |`model` |Includes Worksheets. -|Table |`table` | -|SQL View |`sql_view` | -|Column |None |Supported on columns within Tables and Models. -|Connection |`connection` | -|Collection |None | -|Custom action |None |Supported for custom actions managed through the API or the server. -|Personalized View |None |For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import]. -|Variable |None |Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl. -|Memory |None |Carries an Object ID through the Model it is tagged to. -|Group |None | -|Role |None | +|Object type |##TML kind## |##Notes## + +|Liveboard |##`liveboard`## |##Exported in TML and resolved first on import.## +|Answer |##`answer`## | +|Model |##`model`## |##Includes Worksheets.## +|Table |##`table`## | +|##SQL View## |##`sql_view`## | +|##Column## |##None## |##Supported on columns within Tables and Models.## +|##Connection## |##`connection`## | +|Collection |##None## | +|##Custom action## |##None## |##Supported for custom actions managed through the API or the server.## +|Personalized View |##None## |##For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import].## +|Variable |##None## |##Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl.## +|##Memory## |##None## |##Carries an Object ID through the Model it is tagged to.## +|##Group## |##None## | +|Role |##None## | |=== [IMPORTANT] ==== -The `obj_id` field appears in the TML of every object kind, but TML import honors it only for the supported object types. The presence of `obj_id` in a TML file does not mean that the object type supports Object ID. +##The `obj_id` field appears in the TML of every object kind, but TML import honors it only for the supported object types. The presence of `obj_id` in a TML file does not mean that the object type supports Object ID.## ==== -=== Objects that do not support obj_id +=== ##Objects that do not support obj_id## -The following objects do not have an `obj_id`: +##The following objects do not have an `obj_id`:## [cols="2,5", options="header"] |=== -|Object |Behavior +|##Object## |##Behavior## -|Visualization on a Liveboard -|In TML, a visualization is identified only by `viz_guid`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, depend on a GUID that differs between Orgs. +|##Visualization on a Liveboard## +|##In TML, a visualization is identified only by `viz_guid`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, depend on a GUID that differs between Orgs.## -|Liveboard tab -|A tab is identified only by its `id`, which is a GUID. +|##Liveboard tab## +|##A tab is identified only by its `id`, which is a GUID.## -|Monitor alert (KPI alert) -|The alert has no `obj_id` of its own. Its TML includes `pinboard_obj_id` and `answer_obj_id`, which resolve on import, but the visualization reference is a GUID that must already exist in the target environment. +|##Monitor alert (KPI alert)## +|##The alert has no `obj_id` of its own. Its TML includes `pinboard_obj_id` and `answer_obj_id`, which resolve on import, but the visualization reference is a GUID that must already exist in the target environment.## -|Schedule -|Liveboard schedules reference visualizations through `included_viz_id`, which is a GUID. +|##Schedule## +|##Liveboard schedules reference visualizations through `included_viz_id`, which is a GUID.## -|Webhook -|The `obj_id` field is present in webhook TML but is ignored on import. +|##Webhook## +|##The `obj_id` field is present in webhook TML but is ignored on import.## -|Parameter -|Parameters have no `obj_id` and do not migrate by name. +|##Parameter## +|##Parameters have no `obj_id` and do not migrate by name.## -|Semantic integration -|Semantic integrations have no `obj_id` and do not migrate by name. +|##Semantic integration## +|##Semantic integrations have no `obj_id` and do not migrate by name.## -|User -|Users are identified by name in TML and migrate without an `obj_id`. +|##User## +|##Users are identified by name in TML and migrate without an `obj_id`.## -|Tag -|Tags are identified by name in TML and migrate without an `obj_id`. +|##Tag## +|##Tags are identified by name in TML and migrate without an `obj_id`.## -|Org -|Orgs are part of the uniqueness key (Org ID + `obj_id`), so they do not have an `obj_id` themselves. +|##Org## +|##Orgs are part of the uniqueness key (Org ID + `obj_id`), so they do not have an `obj_id` themselves.## |=== -=== TML kinds that ignore obj_id on import +=== ##TML kinds that ignore obj_id on import## -The `obj_id` field is present in the following TML kinds but is ignored during import: +##The `obj_id` field is present in the following TML kinds but is ignored during import:## -* `Join` -* `user_object` -* `webhook` -* `column_security_rules` -* `nl_instruction` -* `column_alias` -* `nls_feedback` -* `cohort` -* `monitor_alert` +* ##`Join`## +* ##`user_object`## +* ##`webhook`## +* ##`column_security_rules`## +* ##`nl_instruction`## +* ##`column_alias`## +* ##`nls_feedback`## +* ##`cohort`## +* ##`monitor_alert`## == obj_id format and constraints @@ -115,31 +115,31 @@ An `obj_id` value must meet the following requirements: |=== |Constraint |Requirement -|Length |1 to 64 characters -|Allowed characters |Letters, digits, and the special characters hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`). Spaces are not allowed. +|Length |##1 to## 64 characters +|Allowed characters |##Letters, digits, and the special characters hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`). Spaces are not allowed.## |Uniqueness |Unique within an Org |=== -*Valid examples:* `sales-weekly-performance`, `finance_ledger.prod`, `retail~kpis-v2` +*Valid examples:* ##`sales-weekly-performance`, `finance_ledger.prod`, `retail~kpis-v2`## [TIP] ==== -Do not use a value that has the same format as a GUID. When ThoughtSpot resolves an identifier in a URL, a GUID-shaped value is always tried as a GUID first, so a GUID-shaped `obj_id` might not resolve as expected. +##Do not use a value that has the same format as a GUID. When ThoughtSpot resolves an identifier in a URL, a GUID-shaped value is always tried as a GUID first, so a GUID-shaped `obj_id` might not resolve as expected.## ==== -== How objects get an obj_id +== ##How objects get an obj_id## -* New objects are assigned an `obj_id` when they are created. -* Objects that existed before Object ID was enabled are not assigned an `obj_id` retroactively. They receive an automatically generated `obj_id` the first time the object is updated or imported through TML. -* You can assign or change the `obj_id` of any supported object at any time. For more information, see <<_setting_and_updating_obj_id,Setting and updating obj_id>>. +* ##New objects are assigned an `obj_id` when they are created.## +* ##Objects that existed before Object ID was enabled are not assigned an `obj_id` retroactively.## They receive an automatically generated `obj_id` the first time the object is updated ##or imported through TML##. +* ##You can assign or change the `obj_id` of any supported object at any time. For more information, see <<_setting_and_updating_obj_id,Setting and updating obj_id>>.## An automatically generated `obj_id` appends the first segment of the object's GUID to the object name. For example, `RetailSalesRAD-KPIs-c1e4043a`. If the `metadata_obj_id` property in the `/metadata/search` API response is `null`, the object has not been updated since Object ID was enabled. == obj_id resolution -How ThoughtSpot resolves an identifier depends on where you use it. +##How ThoughtSpot resolves an identifier depends on where you use it.## -=== REST API endpoints +=== ##REST API endpoints## When an identifier is passed to a REST API v2.0 endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: @@ -149,33 +149,33 @@ When an identifier is passed to a REST API v2.0 endpoint that accepts an `object This allows `obj_id` to be used anywhere a GUID or name is accepted in those fields. Existing integrations that use GUIDs or names continue to work. -The `POST /api/rest/2.0/metadata/search` endpoint and the metadata update endpoints also accept an `obj_identifier` field. When you use `obj_identifier`, ThoughtSpot resolves the value strictly as an `obj_id`, without falling back to the object name. +##The `POST /api/rest/2.0/metadata/search` endpoint and the metadata update endpoints also accept an `obj_identifier` field. When you use `obj_identifier`, ThoughtSpot resolves the value strictly as an `obj_id`, without falling back to the object name.## -In the `/metadata/search` API, `obj_identifier` is supported for the following object types: +##In the `/metadata/search` API, `obj_identifier` is supported for the following object types:## -* `LIVEBOARD` -* `ANSWER` -* `LOGICAL_TABLE` -* `LOGICAL_COLUMN` -* `CONNECTION` -* `USER_GROUP` -* `COLLECTION` +* ##`LIVEBOARD`## +* ##`ANSWER`## +* ##`LOGICAL_TABLE`## +* ##`LOGICAL_COLUMN`## +* ##`CONNECTION`## +* ##`USER_GROUP`## +* ##`COLLECTION`## -Other object types, such as Roles and Personalized Views, can have an `obj_id`, but you cannot search for them by `obj_identifier`. To find these objects, search by GUID or name and read the `metadata_obj_id` value in the response. +##Other object types, such as Roles and Personalized Views, can have an `obj_id`, but you cannot search for them by `obj_identifier`. To find these objects, search by GUID or name and read the `metadata_obj_id` value in the response.## -=== TML import +=== ##TML import## -During TML import, ThoughtSpot matches the TML to an existing object in the following order: +##During TML import, ThoughtSpot matches the TML to an existing object in the following order:## -. `obj_id` -. GUID -. Name +. ##`obj_id`## +. ##GUID## +. ##Name## -If the `obj_id` in the TML does not match any object in the target Org, ThoughtSpot falls back to the GUID in the TML and updates that object. The import returns a `WARNING` status in this case. It does not create a duplicate object or fail the import. +##If the `obj_id` in the TML does not match any object in the target Org, ThoughtSpot falls back to the GUID in the TML and updates that object. The import returns a `WARNING` status in this case. It does not create a duplicate object or fail the import.## -=== ThoughtSpot URLs +=== ##ThoughtSpot URLs## -In ThoughtSpot URLs, a GUID is always tried first, and object names are never resolved. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. +##In ThoughtSpot URLs, a GUID is always tried first, and object names are never resolved. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs].## [NOTE] ==== @@ -184,25 +184,25 @@ In ThoughtSpot URLs, a GUID is always tried first, and object names are never re == Setting and updating obj_id -You can set or change the `obj_id` of an object by using the REST API or by editing the object's TML. +You can set or change the `obj_id` of an object by using the REST API ##or by editing the object's TML##. === Using the update-obj-id API -The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. The endpoint uses the metadata header update mechanism to apply the change. +The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. ##The endpoint uses the metadata header update mechanism to apply the change.## -Required privileges:: -`DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*). If Role-Based Access Control (RBAC) is enabled, the `ORG_ADMINISTRATION` (*Can manage Orgs*) privilege is also required. +##Required privileges##:: +##`DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*). If Role-Based Access Control (RBAC) is enabled, the `ORG_ADMINISTRATION` (*Can manage Orgs*) privilege is also required.## -Request parameters:: -For each object in the `metadata` array: +##Request parameters##:: +##For each object in the `metadata` array:## + -* Identify the object by using either `current_obj_id` alone, or `metadata_identifier`. -* `metadata_identifier` accepts the object's GUID or name. If you use the name, you must also specify the object `type`, for example, `ANSWER` or `LOGICAL_TABLE`. -* `new_obj_id` is always required. The value must follow the xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format] and be unique within the Org. +* ##Identify the object by using either `current_obj_id` alone, or `metadata_identifier`.## +* ##`metadata_identifier` accepts the object's GUID or name. If you use the name, you must also specify the object `type`, for example, `ANSWER` or `LOGICAL_TABLE`.## +* ##`new_obj_id` is always required. The value must follow the## xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format] ##and be unique within the Org.## [TIP] ==== -Before updating Object IDs, export the TML of the objects as a backup. +##Before updating Object IDs, export the TML of the objects as a backup.## ==== Using the GUID: @@ -233,7 +233,7 @@ Using the current `obj_id`: } ---- -Using the object name and type: +##Using the object name and type:## [,json] ---- @@ -248,7 +248,7 @@ Using the object name and type: } ---- -The request accepts an array, so you can update multiple objects in a single API call. Each object in the array can use a different identification method: +The request accepts an array, so you can update multiple objects in a single API call. ##Each object in the array can use a different identification method:## [,json] ---- @@ -267,24 +267,24 @@ The request accepts an array, so you can update multiple objects in a single API } ---- -=== Using the metadata headers update API +=== ##Using the metadata headers update API## -The `POST /api/rest/2.0/metadata/headers/update` endpoint also sets the `obj_id` in an object's header. From 26.10.0.cl, this endpoint and the `update-obj-id` endpoint support the `ROLE` and `TEMPLATE_VARIABLE` types. +##The `POST /api/rest/2.0/metadata/headers/update` endpoint also sets the `obj_id` in an object's header.## From 26.10.0.cl, this endpoint and the `update-obj-id` endpoint support the `ROLE` and `TEMPLATE_VARIABLE` types. === Using TML Set the `obj_id` property in the object's TML and import the TML. For examples, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs]. -== Behavior and limitations +== ##Behavior and limitations## -Renaming an obj_id:: -After you change an object's `obj_id`, the previous value no longer resolves. Integrations, scripts, and URLs that use the old value must be updated to use the new value. +##Renaming an obj_id##:: +##After you change an object's `obj_id`, the previous value no longer resolves. Integrations, scripts, and URLs that use the old value must be updated to use the new value.## -Org scope:: -The same `obj_id` in two Orgs resolves to two different objects. Make sure requests are made in the context of the Org where the `obj_id` is set. +##Org scope##:: +##The same `obj_id` in two Orgs resolves to two different objects. Make sure requests are made in the context of the Org where the `obj_id` is set.## -Delete operations:: -The `POST /api/rest/2.0/metadata/delete` endpoint does not accept `obj_identifier`. Use GUIDs when deleting objects in automation scripts. +##Delete operations##:: +##The `POST /api/rest/2.0/metadata/delete` endpoint does not accept `obj_identifier`. Use GUIDs when deleting objects in automation scripts.## == Related resources From 892282bee7565e0dd1f2a4a48f483405e78a8507 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 12 Oct 2026 09:52:56 +0530 Subject: [PATCH 056/169] changelog and other edits --- modules/ROOT/pages/api-changelog.adoc | 273 +++++++--- .../pages/common/nav-in-product-help.adoc | 3 + modules/ROOT/pages/common/nav-rest-api.adoc | 5 +- modules/ROOT/pages/input-table-api.adoc | 438 ++++++++++------ .../ROOT/pages/link-customization-api.adoc | 280 ++++++----- modules/ROOT/pages/rest-api-v2-reference.adoc | 167 +++--- modules/ROOT/pages/rest-apiv2-changelog.adoc | 111 ++-- .../ROOT/pages/spotter-usage-data-api.adoc | 476 +++++++++--------- 8 files changed, 1014 insertions(+), 739 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index d83c4c987..dbe642cdc 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -10,31 +10,147 @@ This page documents the changes introduced in each release of the Visual Embed S == Version 1.54.0, November 2026 - [width="100%", cols="1,4"] - |==== - |[tag greenBackground]#NEW# - a| - [discrete] - ===== SpotterX embed support - You can now embed the SpotterX experience using the `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` components. Set `spotterVersion` to `SpotterVersion.SpotterX` to enable the next-generation Spotter interface with improved chat layout, enhanced branding controls, and consistent configuration across all embed contexts. +[width="100%", cols="1,4"] +|==== +|[tag greenBackground]#NEW# +a| +[discrete] +===== Spotter experience version +You can now load the updated Spotter experience introduced in ThoughtSpot 26.11.0.cl in embedded views. Set `spotterExperienceVersion` to `SpotterExperienceVersion.SPOTTER_2026_11` in the view configuration of `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed`. When this property is set, the embed loads the updated Spotter surface instead of the default conversation surface. + +This property is available in SDK 1.53.0 and later and requires ThoughtSpot Cloud 26.11.0.cl or later. + +[source,javascript] +---- +const embed = new SpotterEmbed('#tsEmbed', { + ... // other embed view config + spotterExperienceVersion: SpotterExperienceVersion.SPOTTER_2026_11, +}); +---- + +For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Filter and Parameter overrides on Liveboard load +`LiveboardEmbed` now supports the `liveboardOverride` property to apply filter and Parameter values when a Liveboard loads. Specify the overrides for each data source (Model) in the `dataSourceOverride` array. Each entry can include the following arrays: + +* `filterQuery` + +Filters to apply. Each item includes a `filterQueryToken` in search sentence form, such as `color = red`. +* `parameterQuery` + +Parameter values to apply. Each item includes a `parameterQueryToken`, such as `discount = 10`. + +To scope a filter or Parameter to a Liveboard tab or group, add `tabName` and `groupName` to the item. Clauses without a query token are dropped. + +In an embedded Liveboard, `liveboardOverride` is the only way to set these overrides at load time. The `filter` and `parameter` URL query parameters are ignored. + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + ... // other embed view config + liveboardOverride: { + dataSourceOverride: [{ + dataSourceIdentifier: '', + filterQuery: [{ + tabName: 'Sales', + groupName: 'Region', + filterQueryToken: 'color = red', + }], + parameterQuery: [{ + parameterQueryToken: 'discount = 10', + }], + }], + }, +}); +---- + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Separate Edit actions and events for Liveboards and visualizations +The SDK now distinguishes the *Edit* action on the Liveboard page from the *Edit* action in the visualization menu. The existing `Action.Edit` and `EmbedEvent.Edit` continue to work and apply to both. + +* `Action.EditLiveboard` + +Controls the *Edit* action on the Liveboard page only. +* `Action.EditVisualization` + +Controls the *Edit* action in the visualization menu only. +* `EmbedEvent.EditLiveboard` + +Emitted when a user clicks *Edit* on a Liveboard. It is emitted along with `EmbedEvent.Edit`. +* `EmbedEvent.EditVisualization` + +Emitted when a user clicks *Edit* on a visualization in a Liveboard. It is emitted along with `EmbedEvent.Edit`. +* `HostEvent.EditLiveboard` + +Triggers the *Edit* action on the Liveboard. +* `HostEvent.EditVisualization` + +Triggers the *Edit* action on a specific visualization in a Liveboard. Requires `vizId` in the payload. + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Action IDs for Chart Settings V2 +The following `Action` enum members control the visibility and disabled state of the menu items in Chart Settings V2: + +* `Action.ChartTypeSettings` + +*Chart Type* +* `Action.LayoutSettings` + +*Layout* +* `Action.ColumnSettings` + +*Column* +* `Action.AxisSettings` + +*Axis* +* `Action.DataLabelSettings` + +*Data Label* +* `Action.TooltipSettings` + +*Tooltip* +* `Action.LegendSettings` + +*Legend* +* `Action.DisplaySettings` + +*Display* +* `Action.QuerySettings` + +*Query Details* +* `Action.CustomSettings` + +*Custom Action* +* `Action.MuzeAiSettings` + +*Muze AI* +* `Action.RAnalysisSettings` + +*R Analysis* - For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. +|[tag greenBackground]#NEW# +a| +[discrete] +===== Answer edit panel visibility +The `hideAnswerEditPanel` property hides the answer edit panel when set to `true`. Supported in `AppEmbed` and `SearchEmbed`. - |[tag greenBackground]#NEW# - a| - [discrete] - ===== Host-controlled tooltip rendering - The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely. +|[tag greenBackground]#NEW# +a| +[discrete] +===== SpotterViz file upload controls +The `SpotterVizConfig` object supports the following properties to control file uploads in the SpotterViz chat input on embedded Liveboards and full application embeds: - |[tag greenBackground]#NEW# - a| - [discrete] - ===== Programmatic Liveboard filter overrides [Beta] - You can now programmatically update Liveboard filter values at runtime using URL-based filter overrides, without re-rendering the entire component. +* `fileUploadEnabled` + +Set to `false` to hide the file upload option. The default value is `true`. +* `fileUploadFileTypes` + +Restricts the file types allowed for upload to a subset of the types SpotterViz supports, for example, `['csv', 'pdf']`. Specify file extensions with or without the leading dot. Unsupported types and empty lists are ignored. - |==== +|[tag greenBackground]#MODIFIED# +a| +[discrete] +===== Stricter payload type checking for host events in TypeScript +From SDK 1.52.0, unknown fields in the payload of a known `HostEvent` fail to compile when you call `embed.trigger()`. From SDK 1.54.0, the payload is checked strictly against the event contract, and required fields are enforced. Update your `trigger()` calls to match the payload for each event. +|==== - == Version 1.53.0, October 2026 +//// +Removed pending confirmation from the SDK team: no `onTooltipShow` callback exists in the +visual-embed-sdk repository (main at v1.53.1, including all remote branches). + +|[tag greenBackground]#NEW# +a| +[discrete] +===== Host-controlled tooltip rendering +The SDK now supports host-controlled tooltip rendering for embedded charts. Use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. The callback receives the tooltip data (column names, values, and point metadata), and you can return custom HTML content or suppress the tooltip entirely. +//// + +== Version 1.53.0, October 2026 [width="100%", cols="1,4"] |==== @@ -185,7 +301,7 @@ Emitted when the Share action in the menu displayed for a chat in the chat histo Emitted when the user toggles the "include new messages since last shared version" checkbox in the share modal. * `EmbedEvent.SpotterShareModalCancelButtonClicked` + Emitted when the Cancel button in the share conversation modal is clicked. -* `EmbedEvent.SpotterShareStaleInfoBannerDismissed`+ +* `EmbedEvent.SpotterShareStaleInfoBannerDismissed` + Emitted when the user dismisses the banner that shows the text, "This data may have changed since the last time you had a chat." * `EmbedEvent.SpotterSharedConversationExitButtonClicked` + Emitted when a user exits the shared conversation read-only view. @@ -254,7 +370,6 @@ Color used for negative/failure indicators. For more information, see xref:css-customization.adoc[CSS customization framework]. -|| |==== //// @@ -310,10 +425,10 @@ These new CSS variables are available for Liveboard layout and header customizat Sets the left and right margins of the Liveboard header. Set this to the same pixel value as `liveboardGutter` in `LiveboardViewConfig` to align the header with the tile grid. * `--ts-var-liveboard-dual-column-breakpoint` + -Sets the container width threshold at which the Liveboard layout collapses from 12 columns to 2 columns. + +Sets the container width threshold at which the Liveboard layout collapses from 12 columns to 2 columns. * `--ts-var-liveboard-single-column-breakpoint` + -Sets the container width threshold at which the Liveboard layout collapses from 2 columns to a single column. + +Sets the container width threshold at which the Liveboard layout collapses from 2 columns to a single column. For more information, see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables] and xref:customize-css-styles.adoc#_liveboard[Liveboard CSS variables]. @@ -339,7 +454,7 @@ The following Liveboard embedding settings are set to `true` by default on all T Hides filters that are not relevant to the displayed visualization. * `isLiveboardCompactHeaderEnabled` + Enables compact header layout in embedded Liveboards. -* `coverAndFilterOptionInPDF` + +* `coverAndFilterOptionInPDF` + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * `isLiveboardMasterpiecesEnabled` + Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. @@ -455,8 +570,8 @@ Liveboard download actions:: The following action IDs are introduced in the SDK for the download buttons at the Liveboard level: -* `Action.DownloadLiveboard` + -* `Action.DownloadLiveboardAsXlsx` + +* `Action.DownloadLiveboard` +* `Action.DownloadLiveboardAsXlsx` * `Action.DownloadLiveboardAsCsv` Test email for Liveboard scheduled jobs:: @@ -669,7 +784,7 @@ Is emitted when a saved chat is deleted. * `EmbedEvent.SpotterConversationSelected` + Is emitted when a saved chat is selected in the chat history sidebar. -|[tag greenBackground]#NEW# | `enableLinkOverridesV2` + +|[tag greenBackground]#NEW# | `enableLinkOverridesV2` Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. @@ -704,7 +819,7 @@ Events:: On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. ==== -|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** + +|[tag greenBackground]#NEW# a| **Liveboard experience enhancements** Styling and grouping:: @@ -730,6 +845,7 @@ The following action IDs are available for the data publishing menu actions in t * `Action.ManagePublishing` for *Manage publishing* * `Action.Unpublish` for *Unpublish* * `Action.Parameterize` for *Parameterize* + |[tag greenBackground]#NEW# a| **Error handling improvements** To handle errors in the embedding workflows, the SDK includes the following features: @@ -746,7 +862,7 @@ For more information, see link:https://developers.thoughtspot.com/docs/Enumerati [width="100%" cols="1,4"] |==== -|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + +|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. @@ -873,7 +989,7 @@ You can also set the margin property for lazy loading to define when the visuali For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. -|[tag greenBackground]#NEW# a| *Full application embed* + +|[tag greenBackground]#NEW# a| *Full application embed* You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. @@ -889,17 +1005,17 @@ Developers can now control whether a visualization or Liveboard can be presented |[tag greenBackground]#NEW# a| *PDF download settings* + Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. -|[tag greenBackground]#NEW# a| *Parameter for overriding a default primary action* + +|[tag greenBackground]#NEW# a| *Parameter for overriding a default primary action* If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. -|[tag greenBackground]#NEW# a| *Full application embed experience enhancements* + +|[tag greenBackground]#NEW# a| *Full application embed experience enhancements* The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. -|[tag greenBackground]#NEW# a| *Host events* + +|[tag greenBackground]#NEW# a| *Host events* In this version, the SDK introduces the following host event handlers: @@ -984,7 +1100,7 @@ Emits when a query prompt in Spotter embed is edited. Emits when a Spotter query is reset. - `EmbedEvent.PreviewSpotterData` + Emits when a user clicks the Preview data button in the Spotter conversation panel. -- `EmbedEvent.SpotterQueryTriggered` +- `EmbedEvent.SpotterQueryTriggered` + Emits when a Spotter query is triggered. The following embed events are also supported in Spotter embed: @@ -1033,7 +1149,7 @@ Additionally, the SDK provides the `StringIDsUrl` attribute to allow using a JSO For more information, see xref:customize-text-strings.adoc[Customize text strings]. -|[tag greenBackground]#NEW# a| *Hide columns on list pages* + +|[tag greenBackground]#NEW# a| *Hide columns on list pages* In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: @@ -1046,7 +1162,7 @@ In full app embedding, you can now hide the following columns on the *Liveboards * *Tags* + `hiddenListColumns: [ListPageColumns.Tags]` * *Share* + -`hiddenListColumns: [ListPageColumns.Share]` + +`hiddenListColumns: [ListPageColumns.Share]` For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. |==== @@ -1200,9 +1316,9 @@ Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. |[tag greenBackground]#NEW# a|The following parameters are available for customizing Search experience: -* `collapseDataPanel` +* `collapseDataPanel` + Minimizes the data panel view. Users can click the data panel header any time to expand the panel. -* `collapseSearchBar` +* `collapseSearchBar` + Sets the initial state of the search bar when embedding a saved Answer. |[tag greenBackground]#NEW# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: @@ -1234,7 +1350,7 @@ You can set the `homePageSearchBarMode` property to one of the following options ** `aiAnswer` + Displays the search bar for Natural Language Search. -** `none` +** `none` + Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. ** `objectSearch` (default) + Displays Object Search bar on the **Home** page. @@ -1259,25 +1375,25 @@ Use this action enumeration to disable, show, or hide the **Manage tags** button [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW# a| The following new action enumerations are available in this version: + +|[tag greenBackground]#NEW# a| The following new action enumerations are available in this version: -* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + +* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. * `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. * `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. * `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. * `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. * `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. * `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) + For more information, see xref:Action.adoc[Actions]. |[tag greenBackground]#NEW#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. |[tag greenBackground]#NEW# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. -|| |==== == Version 1.31.x, July 2024 [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW# a| Runtime filters + +|[tag greenBackground]#NEW# a| Runtime filters * `NOT_IN` operator for Runtime filters. For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. @@ -1290,10 +1406,10 @@ For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filt |==== |[tag greenBackground]#NEW# a| **CSS variables for new homepage experience** -* `--ts-var-home-watchlist-selected-text-color` + -* `--ts-var-home-card-color` + -* `--ts-var-home-favorite-suggestion-card-text-color` + -* `--ts-var-home-favorite-suggestion-card-background` + +* `--ts-var-home-watchlist-selected-text-color` +* `--ts-var-home-card-color` +* `--ts-var-home-favorite-suggestion-card-text-color` +* `--ts-var-home-favorite-suggestion-card-background` * `--ts-var-home-favorite-suggestion-card-icon-color` For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. @@ -1385,8 +1501,8 @@ For more information, see link:https://developers.thoughtspot.com/docs/Function_ |[tag greenBackground]#NEW#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: -* `numberFormatLocale` + -* `dateFormatLocale` + +* `numberFormatLocale` +* `dateFormatLocale` * `currencyFormat` For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. @@ -1492,9 +1608,9 @@ Show, disable, or hide the **Add Tab** action on a Liveboard. Show, disable, or hide the Liveboard views saved by a user. * `Action.LiveboardUsers` + Show, disable, or hide Liveboard users. -* `Action.SageAnswerFeedback` +* `Action.SageAnswerFeedback` + Show, disable, or hide the feedback widget on AI-generated Answer page. -* `Action.EditSageAnswer` +* `Action.EditSageAnswer` + Show, disable, or hide the **Edit** action on the AI-generated Answer page. For more information, see xref:Action.adoc[Actions]. @@ -1529,17 +1645,17 @@ For more information, see xref:Action.adoc[Actions]. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: * Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. * Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. |==== //// -|[tag greenBackground]#NEW# a| New events for Liveboard filters + +|[tag greenBackground]#NEW# a| New events for Liveboard filters -* `EmbedEvent.FilterChanged` + -* `HostEvent.GetFilters` + +* `EmbedEvent.FilterChanged` +* `HostEvent.GetFilters` * `HostEvent.UpdateFilters` //// @@ -1558,7 +1674,7 @@ For more information, see xref:security-settings.adoc#_block_access_to_non_embed |==== //// -|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: + +|[tag greenBackground]#NEW# a| The SDK supports the following performance optimization enhancements: * Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. * Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. @@ -1602,7 +1718,7 @@ For more information, see xref:embed-events.adoc[Events]. The following events are deprecated from version 1.21.0 onwards. -* `HostEvent.Download` + +* `HostEvent.Download` * `EmbedEvent.Download` You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. @@ -1620,11 +1736,11 @@ 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: + +To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: -** `Action.DownloadAsCsv` + -** `Action.DownloadAsPdf` + -** `Action.DownloadAsXlsx` + +** `Action.DownloadAsCsv` +** `Action.DownloadAsPdf` +** `Action.DownloadAsXlsx` ** `Action.DownloadAsPng` |[tag greenBackground]#NEW# a| The SDK includes new attributes to customize the experience for embedded app users: @@ -1696,21 +1812,21 @@ For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + +|[tag greenBackground]#NEW# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. |[tag greenBackground]#NEW# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + +|[tag greenBackground]#NEW# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. For more information, see xref:HostEvent.adoc#_gettml[GetTML]. |[tag greenBackground]#NEW# a| The new version of the SDK introduces the following enums in the `Action` object: -* `Action.SyncToOtherApps` + -* `Action.SyncToSheets` + -* `Action.ManagePipelines` + +* `Action.SyncToOtherApps` +* `Action.SyncToSheets` +* `Action.ManagePipelines` You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. @@ -1724,12 +1840,13 @@ Bug fixes to the trusted authentication feature. == Version 1.17.0, November 2022 The new version of the SDK introduces several new features and enhancements. + [width="100%" cols="1,4"] |==== -|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + +|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. -* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + -* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + +* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` +* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` * `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + This enhancement does not introduce any breaking changes to your current implementation. |[tag greenBackground]#NEW# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + @@ -1867,6 +1984,7 @@ For more information, see xref:embed-actions.adoc[Show or hide UI actions]. |==== |[tag greenBackground]#NEW#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. |==== + == Version 1.10.3, May 2022 Bug fix and improvements to the `logout` method. @@ -1882,7 +2000,7 @@ Bug fix and improvements to the `logout` method. [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW#|You can now use the `logout` method to log out embed users. -|[tag orangeBackground]#MODIFIED# a| Note the following changes: + +|[tag orangeBackground]#MODIFIED# a| Note the following changes: * You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. * The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. @@ -1945,7 +2063,7 @@ For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a Re For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag greenBackground]#NEW# a| The following events are now available in the SDK: + +|[tag greenBackground]#NEW# a| The following events are now available in the SDK: * `LiveboardRendered` (EmbedEvent) @@ -1957,10 +2075,10 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. |==== |[tag greenBackground]#NEW# a| The SDK now includes the following new enumerations for UI actions: -* `Action.AnswerDelete` + -* `Action.AnswerChartSwitcher` + -* `Action.AddToFavorites` + -* `Action.EditDetails` + +* `Action.AnswerDelete` +* `Action.AnswerChartSwitcher` +* `Action.AddToFavorites` +* `Action.EditDetails` For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. @@ -2024,7 +2142,6 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== -|| |[tag greenBackground]#NEW# | +++
Render embedded objects in queue
+++ The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. @@ -2051,7 +2168,6 @@ For more information, see xref:event-embedEvents.adoc[Events reference]. [width="100%" cols="1,4"] |==== -|| |[tag greenBackground]#NEW# a|+++
+++Prefetch API+++
+++ The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. @@ -2096,7 +2212,6 @@ For more information, see xref:embed-events.adoc[Events and app integration]. [width="100%" cols="1,4"] |==== -|| |[tag greenBackground]#NEW# a| +++
searchOptions
+++ The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 86cc82b95..3685d11f8 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -242,9 +242,11 @@ REST APIs *** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] *** link:{{navprefix}}/spotter-analyst-api[Spotter Analyst APIs] *** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] +*** link:{{navprefix}}/spotter-usage-data-api[Spotter usage data APIs] *** 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}}/link-customization-api[Link customization APIs] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] *** link:{{navprefix}}/tml-import[Import TML] @@ -253,6 +255,7 @@ REST APIs ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] ** link:{{navprefix}}/runtime-sort[Runtime sorting] +** link:{{navprefix}}/input-table-api[Input tables] * link:{{navprefix}}/manual-translation-api[Manual translations] * link:{{navprefix}}/webhooks-rest-api[Webhook APIs] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 60d009d8a..c2d1efc59 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -40,6 +40,7 @@ REST API endpoints ** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] ** link:{{navprefix}}/spotter-analyst-api[Spotter Analyst APIs] ** link:{{navprefix}}/spotter-memory-migration[Spotter memory migration API] +** link:{{navprefix}}/spotter-usage-data-api[Spotter usage data APIs] ** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic)] ** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs] ** link:{{navprefix}}/process-conversation-output[Export answers generated from a Spotter conversation] @@ -58,6 +59,7 @@ REST API endpoints ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] ** link:{{navprefix}}/manual-translation-api[Manual translations] +** link:{{navprefix}}/input-table-api[Input tables] * TML APIs ** link:{{navprefix}}/tml[TML] @@ -65,9 +67,10 @@ REST API endpoints *** link:{{navprefix}}/tml-export[Export TML] -* Style and email customization APIs +* Style, email, and link customization APIs ** link:{{navprefix}}/style-customization-apis[Style customization APIs] ** link:{{navprefix}}/customize-email-apis[Customize email template] +** link:{{navprefix}}/link-customization-api[Link customization APIs] * link:{{navprefix}}/collections[Collections] * link:{{navprefix}}/webhooks-rest-api[Webhook APIs] diff --git a/modules/ROOT/pages/input-table-api.adoc b/modules/ROOT/pages/input-table-api.adoc index 051efac6a..5ea3a1ca0 100644 --- a/modules/ROOT/pages/input-table-api.adoc +++ b/modules/ROOT/pages/input-table-api.adoc @@ -4,19 +4,35 @@ :page-title: Input Table APIs :page-pageid: input-table-api -:page-description: Use Input Table APIs to create, manage, and write data to input tables linked to ThoughtSpot models. +:page-description: Use the Input Table REST API v2 endpoints to create input tables, add or remove columns, and write data to input tables linked to ThoughtSpot models. +:keywords: input table, input tables, writeback, Cloud Data Warehouse, model, REST API -Input tables are user-editable tables stored in an external Cloud Data Warehouse (CDW) and linked to a ThoughtSpot model (worksheet). They allow analysts to enter or import data directly from the ThoughtSpot UI without requiring access to the underlying warehouse. +Input tables are user-editable tables stored in an external Cloud Data Warehouse (CDW) and linked to a ThoughtSpot model. They allow analysts to enter or import data directly from the ThoughtSpot UI without requiring access to the underlying warehouse. -The Input Table REST API v2.0 endpoints allow you to create and manage input tables, add or remove columns, and write data programmatically. +ThoughtSpot provides public REST API v2 endpoints to manage input tables programmatically for the following purposes: + +* To create an input table and link it to a model as part of an automated deployment workflow. +* To add or remove editable columns as your data requirements change. +* To write data, such as forecasts, targets, or other planning inputs, from an external application or pipeline to an input table. [NOTE] ==== The Input Table APIs are available on ThoughtSpot Cloud 26.11.0.cl and later. ==== -== Required privileges +== Input table workflow +To create an input table and populate it with data: + +. <> + +Call `POST /api/rest/2.0/input-tables/create` with the model to link, the model columns to reference as key columns, and the new editable columns. The response returns the `input_table_id` and the ID of each column. +. <> (optional) + +Call `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` to add more editable columns later. +. <> + +Call `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` to insert or update rows. +. <> or <> (optional) + +Call the delete endpoints to remove a column or the entire table when it is no longer required. +=== Required privileges All Input Table API endpoints require one of the following privileges: * `DATAMANAGEMENT` (**Can manage data**) @@ -24,63 +40,37 @@ All Input Table API endpoints require one of the following privileges: If link:https://developers.thoughtspot.com/docs/rbac[Role-Based Access Control (RBAC), window=_blank] is enabled on your instance, the `CAN_MANAGE_INPUT_TABLES` (**Can manage input tables**) privilege is required. -The caller must also have `MODIFY` permission on the input table or model object, depending on the operation. - -[#create-input-table] -== Create an input table - -Creates an input table and links it to a ThoughtSpot model. The physical table is created in the external CDW using the connection, database, and schema derived from the model's metadata. - -=== Endpoint +The caller must also have `MODIFY` permission on the following objects: ----- -POST /api/rest/2.0/input-tables/create ----- +* The model specified in `model_identifier`, to create an input table. +* The input table, to add or delete columns, write rows, or delete the table. -=== Request body parameters - -[width="100%" cols="2,1,1,4"] -[options='header'] -|=== -|Parameter |Type |Required |Description - -|`table_name` -|String -|Yes -|Physical name of the table in the external warehouse. Must start with a letter or underscore, contain only letters, digits, and underscores, and be at most 128 characters. - -|`model_identifier` -|String -|Yes -|GUID or name of the model (worksheet) to link the input table to. - -|`table_definition` -|Object -|Yes -|Describes the table schema. See the table definition parameters below. -|=== - -==== Table definition +[#create-input-table] +== Creating an input table +The `/api/rest/2.0/input-tables/create` API endpoint creates an input table and links it to a ThoughtSpot model. The physical table is created in the same connection, database, and schema as the linked model. Ensure that the connection user has `CREATE TABLE` permission in the target schema. -[width="100%" cols="2,1,1,4"] -[options='header'] +=== Request parameters +[cols="2,4", options="header"] |=== -|Parameter |Type |Required |Description - -|`referenced_columns` -|Array of Strings -|Yes -|Names of columns on the linked model to include as read-only reference (key) columns. At least one is required. Each name must match exactly one visible model column and resolve to exactly one physical base column. Formula, cohort, or constant columns cannot be referenced. - -|`new_columns` -|Array of Objects -|Yes -|List of new editable columns. Each column requires `name`, `data_type` (for example, `VARCHAR`, `DOUBLE`, `DATE`), and `type` (`ATTRIBUTE` or `MEASURE`). Optionally include `allowed_values` (at most 500 values) to create a fixed-choice column. - -|`referenced_column_time_dimensions` -|Array of Objects -|No -|Locks selected date columns to a specific time dimension (grain) at creation. Each entry has a `column_identifier` and a `time_dimension`. Accepted values: `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY`. +|Parameter | Description +| `table_name` +|__String__. Physical name of the table to create in the external warehouse. The name must start with a letter or underscore, contain only letters, digits, and underscores, and be at most 128 characters. +| `model_identifier` +|__String__. GUID or name of the model (worksheet) to link the input table to. ThoughtSpot derives the connection, database, and schema for the physical table from this model. +| `table_definition` +a|__Object__. Defines the table schema. Specify the following attributes: + +* `referenced_columns` + +__Array of strings__. Names of the model columns to include as read-only reference columns, as they appear on the model. These columns become the key columns of the input table. The input table is joined to the model on these columns, and rows are matched on them when you write data. At least one column is required. Each name must match exactly one visible model column and resolve to exactly one physical base column. You cannot reference formula, cohort, or constant columns. +* `new_columns` + +__Array of objects__. The new editable columns to create. For each column, specify the following attributes: + +** `name`. __String__. Display name of the column. +** `data_type`. __String__. Data type of the column in the warehouse, for example, `VARCHAR`, `DOUBLE`, or `DATE`. The supported values depend on the underlying CDW. +** `type`. __String__. Semantic role of the column: `ATTRIBUTE` for dimension columns or `MEASURE` for numeric columns. +** `allowed_values`. __Array of strings__. Optional. Up to 500 permitted values, which turn the column into a fixed-choice column. Each value must be non-empty, at most 8192 characters, and valid for the column's `data_type`: a number for numeric types, `true` or `false` for `BOOL`, and an epoch integer for `DATE`, `DATE_TIME`, and `TIME`. Writes that contain any other non-empty value are rejected. +* `referenced_column_time_dimensions` + +__Array of objects__. Optional. Locks the referenced date columns to a specific time dimension (grain) at creation. Each entry includes the `column_identifier`, which is the name of the referenced model column exactly as specified in `referenced_columns`, and the `time_dimension`. Supported values for `time_dimension` are `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, and `YEARLY`. If you omit a column, ThoughtSpot applies no bucketing to it. The time dimension applies only to `DATE` and `DATE_TIME` columns. `HOURLY` requires a `DATE_TIME` column. On a `DATE` column, it is ignored. Date-part grains, such as day of the week, and grains on `TIME` columns are not supported. |=== === Example request @@ -88,13 +78,13 @@ POST /api/rest/2.0/input-tables/create [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/create' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/create' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access_token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "table_name": "forecast_data", - "model_identifier": "model-guid-here", + "model_identifier": "{model-guid}", "table_definition": { "referenced_columns": ["Region", "Quarter"], "new_columns": [ @@ -114,33 +104,109 @@ curl -X POST \ }' ---- -[#create-input-table-column] -== Add columns to an input table - -Adds one or more new editable columns to an existing input table. This widens the physical table in the CDW and refreshes the ThoughtSpot metadata. - -=== Endpoint +=== Example response +If the API request is successful, the API returns the following response: +[source,JSON] ---- -POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create +{ + "input_table_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "input_columns": [ + { + "name": "Region", + "id": "b1c2d3e4-0000-1111-2222-333344445555", + "mapped_column_id": "c7d8e9f0-1234-5678-abcd-ef0987654321" + }, + { + "name": "Quarter", + "id": "d2e3f4a5-1111-2222-3333-444455556666", + "mapped_column_id": "e8f9a0b1-2345-6789-bcde-f01987654322" + }, + { + "name": "forecast_revenue", + "id": "a9b8c7d6-9999-8888-7777-666655554444" + }, + { + "name": "confidence_level", + "id": "f0a1b2c3-3333-4444-5555-666677778888" + } + ] +} ---- -=== Request body parameters +=== Response parameters +[cols="2,4", options="header"] +|=== +| Parameter | Description +| `input_table_id` +| GUID of the new input table. Use this value as the `input_table_identifier` path parameter in the other Input Table API endpoints. +| `input_columns` +a| Every column on the new table. Each entry includes the following attributes: + +* `name`: Display name of the column. +* `id`: GUID of the column. +* `mapped_column_id`: GUID of the model column that the input column is mapped from. Present only for referenced columns. + +Use the column IDs to address specific columns in later calls without a separate lookup. +| `message_info` +| A note that is present only when ThoughtSpot renames a referenced column to keep the column names of the input table unique. If a model column name occurs in more than one base table, ThoughtSpot prefixes it with the base table name. For example, `Region` becomes `sales_Region`. The final name of the renamed column is also available in `input_columns`, and it is the name you must use when you write rows. +|=== -[width="100%" cols="2,1,1,4"] -[options='header'] +=== Response codes +[cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Input table created successfully. +| **400** | Invalid request. For example, the payload is invalid, no columns are selected, or upload is disabled on the connection. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have `MODIFY` permission on the model. +| **404** | Model not found. +| **500** | Unexpected server error. |=== -|Parameter |Type |Required |Description -|`column_definition.columns` -|Array of Objects -|Yes -|List of new editable columns. Each column requires `name`, `data_type`, and `type` (`ATTRIBUTE` or `MEASURE`). Optionally include `allowed_values`. +[#create-input-table-column] +== Adding columns to an input table +The `/api/rest/2.0/input-tables/{input_table_identifier}/columns/create` API endpoint adds one or more editable columns to an existing input table. This operation widens the physical table in the CDW and refreshes the metadata of the input table in ThoughtSpot, so that the new columns are available on the linked model. + +You can add only new editable columns with this endpoint. A column added this way is never a key column and does not have a time dimension. + +=== Request parameters +[cols="2,4", options="header"] |=== +|Parameter | Description +| `input_table_identifier` +|__String__. Path parameter. GUID of the input table to add the columns to. +| `column_definition` +a|__Object__. Defines the columns to add. Specify the following attribute: + +* `columns` + +__Array of objects__. The new editable columns. For each column, specify the `name`, `data_type`, and `type` (`ATTRIBUTE` or `MEASURE`). Optionally, include `allowed_values`. The column name must not collide with an existing column on the table. For more information about these attributes, see <>. +|=== + +=== Example request -=== Response +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/{input_table_identifier}/columns/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "column_definition": { + "columns": [ + { + "name": "forecast_revenue", + "data_type": "DOUBLE", + "type": "MEASURE" + } + ] + } +}' +---- -Returns the added columns with their generated GUIDs. +=== Example response +If the API request is successful, the API returns the added columns with their generated GUIDs. Use these GUIDs as the `column_identifier` to <>. [source,JSON] ---- @@ -154,129 +220,177 @@ Returns the added columns with their generated GUIDs. } ---- -[#delete-input-table] -== Delete an input table - -Deletes an input table, unlinks it from its owner model, removes it from the connection metadata, and drops the physical table from the CDW. This action is irreversible. +=== Response codes +[cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Columns added successfully. +| **400** | Invalid request. For example, the payload is invalid or no columns are specified. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have `MODIFY` permission on the input table. +| **404** | Input table not found. +| **500** | Unexpected server error. +|=== -=== Endpoint +[#update-input-table] +== Writing rows to an input table +The `/api/rest/2.0/input-tables/{input_table_identifier}/update` API endpoint writes rows into an existing input table using a keyed upsert (MERGE) operation. ThoughtSpot matches the rows in the request with the existing rows on the key columns of the input table, which are the columns mapped to the linked model. A matched row is updated in place, and a row whose key is not found is inserted. ----- -POST /api/rest/2.0/input-tables/{input_table_identifier}/delete ----- +=== Request parameters +[cols="2,4", options="header"] +|=== +|Parameter | Description +| `input_table_identifier` +|__String__. Path parameter. GUID of the input table to write to. +| `columns` +|__Array of strings__. Ordered list of the column names to write. The column names must exactly match the names defined when the input table was created. The list must include every key column and at least one non-key column. Key columns identify a row but are never overwritten, so a payload with only key columns is rejected. +| `rows` +|__Array of arrays__. The rows to write. At least one row is required. Each row is an array of string values in the same order as `columns`, with exactly one value per column. Pass all values as strings regardless of the data type of the column. An empty value writes `NULL` to the cell. +|=== -=== Response +=== Date value handling +* For `DATE` columns, pass an ISO calendar date (`yyyy-MM-dd`), for example, `2025-01-01`. ThoughtSpot stores the value exactly as written, without time zone conversion. Epoch numbers are also accepted, but they are resolved in the cluster's local time zone, so a UTC-midnight epoch can land on the previous day on clusters west of UTC. Use the ISO format. +* `DATE_TIME` and `TIME` columns accept epoch numbers only. An ISO value is rejected. +* All rows must use the same format for a given column. A calendar-invalid date, such as `2026-02-30`, is rejected. -Returns `204 No Content` on success. +=== Write semantics +* **Matched rows**: Only the non-key columns in `columns` are overwritten. Columns that you do not include keep their existing values. +* **New rows**: A new row is inserted. Non-key columns that you do not include are set to `NULL`. +* This is not a full-table replace. Existing rows whose keys are not in the request are not changed. +* The operation is idempotent. Retrying the same request is safe. -[NOTE] -==== -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. -==== +The API rejects the request if a column name does not match the table schema, the number of values in a row does not match the number of `columns`, a key column is missing, no non-key column is specified, or a value is not compatible with the data type of its column. -[#delete-input-table-column] -== Delete an input table column +=== Example request -Deletes a single editable column from an input table. This removes the column from the ThoughtSpot metadata and drops the physical column from the CDW. This action is irreversible. +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/{input_table_identifier}/update' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "columns": ["Region", "Quarter", "forecast_revenue"], + "rows": [ + ["West", "Q1 2026", "500000"], + ["East", "Q1 2026", "750000"] + ] +}' +---- -=== Endpoint +=== Example response +If the API request is successful, the API returns the number of rows written, which is the sum of rows updated and rows inserted. The count is the number reported by the warehouse. If the warehouse completes the load but does not report a count, the API returns a `500` error. +[source,JSON] ---- -POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete +{ + "rows_loaded": 2 +} ---- -Only columns added directly to the input table (editable, non-referenced columns) can be deleted. The request is rejected if the column is a referenced (model-projected) column or is still referenced by an existing Answer or Liveboard. +=== Response codes +[cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Rows loaded successfully. +| **400** | Malformed request, unknown column name, missing key column, or incompatible data type. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have `MODIFY` permission on the input table. +| **404** | Input table not found. +| **500** | Unexpected server error. +|=== -Use the `id` field returned by `createInputTableColumn` or `createInputTable` as the `column_identifier`. +[#delete-input-table-column] +== Deleting an input table column +The `/api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` API endpoint deletes a single editable column from an input table. This operation removes the column from the input table metadata in ThoughtSpot and drops the physical column from the CDW. All data stored in the column is permanently deleted. -=== Response +[WARNING] +==== +This operation cannot be undone. +==== -Returns `204 No Content` on success. +You can delete only the columns that were added directly to the input table (editable, non-referenced columns). The API rejects the request if the column is a referenced (model-projected) column or if an existing Answer or Liveboard still references it. -[#update-input-table] -== Write rows to an input table +=== Request parameters +[cols="2,4", options="header"] +|=== +|Parameter | Description +| `input_table_identifier` +|__String__. Path parameter. GUID of the input table that owns the column. +| `column_identifier` +|__String__. Path parameter. GUID of the column to delete. Use the `id` returned for the column in the response of the <> API (`input_columns`) or the <> API (`columns`). +|=== -Writes rows into an existing input table using a keyed upsert (MERGE) operation. Rows are matched on the input table's key columns (the columns mapped to the linked model). Matched rows are updated in place. Unmatched rows are inserted. +This endpoint does not require a request body. -=== Endpoint +=== Example request +[source,cURL] ---- -POST /api/rest/2.0/input-tables/{input_table_identifier}/update +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' ---- -=== Request body parameters - -[width="100%" cols="2,1,1,4"] -[options='header'] +=== Response codes +[cols="1,3", options="header"] |=== -|Parameter |Type |Required |Description - -|`columns` -|Array of Strings -|Yes -|Ordered list of column names to write. Must include every key column and at least one non-key column. - -|`rows` -|Array of Arrays -|Yes -|List of rows. Each row is an array of string values in the same order as `columns`. An empty value writes `NULL`. +| HTTP status code | Description +| **204** | The column is deleted and the physical column is dropped from the CDW. +| **400** | The operation failed. For example, the column is a referenced column or is still referenced by an Answer or Liveboard. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have the required privilege or `MODIFY` permission on the input table. +| **500** | Unexpected server error. |=== -=== Date value handling +[#delete-input-table] +== Deleting an input table +The `/api/rest/2.0/input-tables/{input_table_identifier}/delete` API endpoint deletes an input table. This operation unlinks the input table from its owner model, removes it from the connection metadata, and drops the physical table from the CDW. All data stored in the input table is permanently deleted. -* `DATE` columns accept ISO calendar dates (`yyyy-MM-dd`, for example `2025-01-01`). Epoch numbers are also accepted but resolved in the cluster's local time zone. -* `DATE_TIME` and `TIME` columns accept epoch numbers only. -* All values in a column must use the same format. +[WARNING] +==== +This operation cannot be undone. +==== -=== Write semantics +Deleting an input table does not delete the linked model. However, any Answers or Liveboards that reference columns from the deleted input table lose access to that data and may return errors until you update the affected visualizations. -* **Matched rows**: only the non-key columns present in `columns` are overwritten. Columns not included keep their existing values. -* **New rows**: a new row is inserted. Non-key columns not included are set to `NULL`. -* This is not a full-table replace. Existing rows whose keys are not in the payload are untouched. +=== Request parameters +[cols="2,4", options="header"] +|=== +|Parameter | Description +| `input_table_identifier` +|__String__. Path parameter. GUID of the input table to delete. ThoughtSpot derives the owner model from the metadata of the input table. +|=== + +This endpoint does not require a request body. === Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/{input_table_identifier}/update' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access_token}' \ - --data-raw '{ - "columns": ["Region", "Quarter", "forecast_revenue"], - "rows": [ - ["West", "Q1 2026", "500000"], - ["East", "Q1 2026", "750000"] - ] -}' + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/input-tables/{input_table_identifier}/delete' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' ---- -=== Response - -Returns `rows_loaded`, the number of rows written (updated + inserted). - -== Error codes - -[width="80%" cols="1,3"] -[options='header'] +=== Response codes +[cols="1,3", options="header"] |=== -|HTTP status |Description - -|`400` -|Invalid request. For example, a mismatched column name, missing key column, or incompatible data type. - -|`401` -|Unauthorized. The caller is not authenticated. - -|`403` -|Forbidden. The caller does not have the required privilege or permission. - -|`500` -|Unexpected server error. +| HTTP status code | Description +| **204** | The input table is deleted and the physical table is dropped from the CDW. +| **400** | The operation failed. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have the required privilege or `MODIFY` permission on the input table. +| **500** | Unexpected server error. |=== -== Related information +== Additional resources -* xref:rest-api-v2-reference.adoc[REST API v2.0 Reference] +* xref:rest-api-v2-reference.adoc#_input_tables[REST API v2.0 Reference] * xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* +++REST API Playground - Create input table endpoint+++ +* +++REST API Playground - Create input table column endpoint+++ +* +++REST API Playground - Update input table endpoint+++ +* +++REST API Playground - Delete input table column endpoint+++ +* +++REST API Playground - Delete input table endpoint+++ diff --git a/modules/ROOT/pages/link-customization-api.adoc b/modules/ROOT/pages/link-customization-api.adoc index ac3ebe20f..c6db2c73d 100644 --- a/modules/ROOT/pages/link-customization-api.adoc +++ b/modules/ROOT/pages/link-customization-api.adoc @@ -4,121 +4,103 @@ :page-title: Link Customization APIs :page-pageid: link-customization-api -:page-description: Use Link Customization APIs to programmatically manage the URL templates ThoughtSpot uses when generating shareable links. +:page-description: Use the Link Customization REST API v2 endpoints to manage the URL templates ThoughtSpot uses when generating shareable links. +:keywords: link customization, shareable links, URL templates, share link, embedded application, REST API ThoughtSpot generates shareable links for Liveboards, Answers, visualizations, SpotIQ insights, Spotter conversations, and other objects. These links appear in scheduled emails, the Share dialog, and alert notifications. -By default, shareable links point to your ThoughtSpot instance. If you embed ThoughtSpot in your own application, you can redirect these links to your application using the Link Customization APIs. When a user clicks a shared link, they are directed to your embedding application instead of the ThoughtSpot application. +By default, shareable links point to your ThoughtSpot instance. If you embed ThoughtSpot in your own application, you can use the Link Customization REST API v2 endpoints to redirect these links to your application. When a user clicks a shared link, they are directed to your embedding application instead of the ThoughtSpot application. [NOTE] ==== The Link Customization APIs are available on ThoughtSpot Cloud 26.11.0.cl and later. ==== -== Overview +== Link customization workflow +Each link type has a URL template with placeholders that ThoughtSpot replaces with the object details when it generates a link. To customize the links: -The Link Customization APIs allow you to read and update the URL templates used when ThoughtSpot generates shareable links. Each link type has a URL template with placeholders that ThoughtSpot substitutes at generation time. +. <> + +Call `POST /api/rest/2.0/customization/links/search` to view the templates in effect at the cluster level or for your Org. +. <> + +Call `POST /api/rest/2.0/customization/links/update` with the `REPLACE` operation to set a template, or with the `RESET` operation to clear an override. -Two endpoints are available: +=== Scopes +You can manage the templates at the following scopes: -* **Search** — Retrieves the current URL templates. -* **Update** — Sets or resets URL templates. +* `CLUSTER`: Sets the default templates that all Orgs inherit. Available only to callers in the primary Org. +* `ORG`: Sets the templates for the caller's Org and overrides the cluster default. Requires Orgs to be enabled on your instance. -Templates can be managed at two scopes: - -* `CLUSTER` — Sets the default templates that all Orgs inherit. Available only to callers in the primary Org. -* `ORG` — Sets templates for the caller's Org, overriding the cluster default. Requires Orgs to be enabled. - -== Required privileges - -These endpoints require one of the following privileges: +=== Required privileges +To use the Link Customization APIs, the user requires one of the following privileges: * `ADMINISTRATION` (**Can administer ThoughtSpot**) * `DEVELOPER` (**Has developer privilege**) -== Supported link types and placeholders - -Each link type requires specific placeholders in its URL template. A template missing a required placeholder is rejected. +[#link-types] +=== Supported link types and placeholders +Each link type requires specific placeholders in its URL template. ThoughtSpot rejects a template that does not include the required placeholders. -[width="100%" cols="2,2,3"] -[options='header'] +[cols="2,2,3", options="header"] |=== -|Link type |Required placeholders |Example template - -|`LIVEBOARD_SHARE_URL` -|`{object-id}`, `{ts-query-params}` -|`\https://analytics.acme.com/dashboards/{object-id}?{ts-query-params}` - -|`VISUALIZATION_SHARE_URL` -|`{object-id}`, `{sub-object-id}`, `{ts-query-params}` -|`\https://analytics.acme.com/dashboards/{object-id}/charts/{sub-object-id}?{ts-query-params}` - -|`ANSWER_SHARE_URL` -|`{object-id}`, `{ts-query-params}` -|`\https://analytics.acme.com/answers/{object-id}?{ts-query-params}` - -|`SPOTIQ_ANALYSIS_URL` -|`{object-id}` -|`\https://analytics.acme.com/insights/{object-id}` - -|`UNSUBSCRIBE_URL` -|none -|`\https://analytics.acme.com/account/email-preferences` - -|`GENERIC_URL` -|`{path}` -|`\https://analytics.acme.com/{path}` - -|`CONVERSATION_SHARE_URL` -|`{conversation-id}`, `{ts-query-params}` -|`\https://analytics.acme.com/spotter/{conversation-id}?{ts-query-params}` +|Link type | Required placeholders | Example template +| `LIVEBOARD_SHARE_URL` +| `{object-id}`, `{ts-query-params}` +| `\https://analytics.acme.com/dashboards/{object-id}?{ts-query-params}` +| `VISUALIZATION_SHARE_URL` +| `{object-id}`, `{sub-object-id}`, `{ts-query-params}` +| `\https://analytics.acme.com/dashboards/{object-id}/charts/{sub-object-id}?{ts-query-params}` +| `ANSWER_SHARE_URL` +| `{object-id}`, `{ts-query-params}` +| `\https://analytics.acme.com/answers/{object-id}?{ts-query-params}` +| `SPOTIQ_ANALYSIS_URL` +| `{object-id}` +| `\https://analytics.acme.com/insights/{object-id}` +| `UNSUBSCRIBE_URL` +| None +| `\https://analytics.acme.com/account/email-preferences` +| `GENERIC_URL` +| `{path}` +| `\https://analytics.acme.com/{path}` +| `CONVERSATION_SHARE_URL` +| `{conversation-id}`, `{ts-query-params}` +| `\https://analytics.acme.com/spotter/{conversation-id}?{ts-query-params}` |=== -`{ts-query-params}` is optional on any type that does not require it. ThoughtSpot substitutes it wherever it appears and removes it when there is nothing to substitute. +`{ts-query-params}` is optional for any link type that does not require it. ThoughtSpot substitutes it wherever it appears and removes it when there is nothing to substitute, so it never appears in a generated link. [#search-link-customizations] -== Search link customizations - -Retrieves the URL templates at the cluster level or for the caller's Org. +== Searching link customizations +The `/api/rest/2.0/customization/links/search` API endpoint retrieves the URL templates that ThoughtSpot uses to generate shareable links, at the cluster level or for the Org that the caller is signed in to. Use this endpoint to verify what an Org has customized before you modify it, or to confirm the destination URLs used in scheduled emails and the Share dialog. -=== Endpoint - ----- -POST /api/rest/2.0/customization/links/search ----- +Cluster-level templates are the default that Orgs inherit. Org-level templates override that default. === Request parameters - -[width="100%" cols="2,1,1,4"] -[options='header'] +[cols="2,4", options="header"] |=== -|Parameter |Type |Required |Description - -|`scope` -|String -|No -|`CLUSTER` or `ORG`. Omit to return whichever scope the caller can access. -|=== - -=== Response +|Parameter | Description +| `scope` +a|__String__. Optional. The scope to retrieve: -Returns an array of link preferences. Each entry includes the `scope`, a `templates` array with the `type`, `value`, and `is_overridden` flag for each link type. +* `CLUSTER` returns the cluster templates. Available only to callers in the primary Org. +* `ORG` returns the templates for the Org that the caller is signed in to. Requires Orgs to be enabled. -The `is_overridden` flag is `true` when the scope stores a value that differs from what it would otherwise inherit. +If you omit the parameter, the API returns the scopes that the caller can access. +|=== === Example request [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/search' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/search' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access_token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{}' ---- === Example response +If the API request is successful, the API returns an array of link preferences, one for each scope. The following example shows two of the seven link types for each scope. The API always returns all link types, whether they are customized or not. [source,JSON] ---- @@ -137,59 +119,95 @@ curl -X POST \ "is_overridden": false } ] + }, + { + "scope": "ORG", + "org": { + "id": 1234567890, + "name": "Sales" + }, + "templates": [ + { + "type": "LIVEBOARD_SHARE_URL", + "value": "https://analytics.acme.com/dashboards/{object-id}?{ts-query-params}", + "is_overridden": true + }, + { + "type": "CONVERSATION_SHARE_URL", + "value": "https://acme.thoughtspot.cloud/#/insights/conv-assist/s/{conversation-id}?{ts-query-params}", + "is_overridden": false + } + ] } ] ---- -[#update-link-customizations] -== Update link customizations - -Updates the URL templates at the cluster level or for the caller's Org. +=== Response parameters +[cols="2,4", options="header"] +|=== +| Parameter | Description +| `scope` | The scope that the link templates apply to: `CLUSTER` or `ORG`. +| `org` | The Org that the link templates belong to. Present only when `scope` is `ORG`. Includes the `id` and `name` of the Org. +| `templates` +a| The effective URL template for every link type at this scope. Each entry includes the following attributes: + +* `type`: The link type. For the list of supported types, see <>. +* `value`: The effective URL template at the requested scope. +* `is_overridden`: `true` when the scope stores a value that differs from the value it would otherwise inherit. For `ORG`, the inherited value is the cluster template. For `CLUSTER`, it is the ThoughtSpot default. The value is `false` when they match. +|=== -=== Endpoint +=== Response codes +[cols="1,3", options="header"] +|=== +| HTTP status code | Description +| **200** | Link preferences retrieved successfully. +| **400** | Invalid request. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have the required privilege. +| **500** | Unexpected server error. +|=== ----- -POST /api/rest/2.0/customization/links/update ----- +[#update-link-customizations] +== Updating link customizations +The `/api/rest/2.0/customization/links/update` API endpoint updates the URL templates that ThoughtSpot uses to generate shareable links, at the cluster level or for the Org that the caller is signed in to. Use this endpoint to point shared links to your embedding application, so that a link in a scheduled email or the Share dialog opens your page instead of the ThoughtSpot application. === Request parameters - -[width="100%" cols="2,1,1,4"] -[options='header'] +[cols="2,4", options="header"] |=== -|Parameter |Type |Required |Description - -|`scope` -|String -|No -|`CLUSTER` or `ORG` (default). `CLUSTER` is available only to callers in the primary Org. - -|`operation` -|String -|No -|`REPLACE` (default) sets each listed type to the `value` provided. `RESET` clears each listed type so it falls back to the inherited template. - -|`templates` -|Array -|Yes -|List of template objects. Each object requires a `type`. For `REPLACE`, include a `value` with the URL template. For `RESET`, omit `value`. +|Parameter | Description +| `scope` +a|__String__. The scope to apply the templates at: + +* `ORG` (default) updates the templates for the Org that the caller is signed in to. Requires Orgs to be enabled. +* `CLUSTER` updates the defaults that all Orgs inherit. Available only to callers in the primary Org. +| `operation` +a|__String__. Optional. The operation to perform: + +* `REPLACE` (default) sets each listed link type to the `value` provided in the request. +* `RESET` clears each listed link type, so an Org falls back to the cluster template and the cluster falls back to the ThoughtSpot default. +| `templates` +a|__Array of objects__. The link types to update. At least one entry is required. For each entry, specify the following attributes: + +* `type`. __String__. The link type. For the list of supported types, see <>. +* `value`. __String__. The URL template, including the placeholders that the link type requires. Required for `REPLACE`. Do not specify it for `RESET`. |=== -=== Behavior +=== Update behavior +* This is a partial update. Only the link types listed in `templates` change. All other link types keep their current value, whether it is set at this scope or inherited. +* The API rejects a request that includes the same link type more than once. +* The API rejects a request that includes a `value` with the `RESET` operation. +* To clear every override, list all link types with the `RESET` operation. +* Resetting at the cluster level changes only the cluster default. An Org that has set its own value keeps it. -* This is a partial update. Only the types listed in `templates` change. Unlisted types keep their current value. -* A repeated type in the `templates` array is rejected. -* `RESET` clears the override, so an Org falls back to the cluster template and the cluster falls back to the ThoughtSpot default. -* Supplying a `value` with a `RESET` operation is rejected. - -=== Example request — Replace a template +=== Example request +.Replace a template [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access_token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "scope": "ORG", "operation": "REPLACE", @@ -202,14 +220,13 @@ curl -X POST \ }' ---- -=== Example request — Reset a template - +.Reset a template [source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/links/update' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access_token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "scope": "ORG", "operation": "RESET", @@ -221,31 +238,22 @@ curl -X POST \ }' ---- -=== Response +=== Response codes +If the API request is successful, the API returns `204 No Content` without a response body. -Returns `204 No Content` on success. - -== Error codes - -[width="80%" cols="1,3"] -[options='header'] +[cols="1,3", options="header"] |=== -|HTTP status |Description - -|`400` -|Invalid request. For example, a missing required placeholder, a duplicate type, or a `value` supplied with `RESET`. - -|`401` -|Unauthorized. The caller is not authenticated. - -|`403` -|Forbidden. The caller does not have the required privilege. - -|`500` -|Unexpected server error. +| HTTP status code | Description +| **204** | Link preferences updated successfully. +| **400** | Invalid request. For example, a template is missing a required placeholder, a link type is repeated, or a `value` is supplied with `RESET`. +| **401** | Authentication token is missing, expired, or invalid. +| **403** | The caller does not have the required privilege. +| **500** | Unexpected server error. |=== -== Related information +== Additional resources -* xref:rest-api-v2-reference.adoc[REST API v2.0 Reference] +* xref:rest-api-v2-reference.adoc#_link_customization[REST API v2.0 Reference] * xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* +++REST API Playground - Search link customizations endpoint+++ +* +++REST API Playground - Update link customizations endpoint+++ diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index be5a04d0b..09e04fd9c 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -116,34 +116,34 @@ Exports Spotter 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+++ - a|`GET /api/rest/2.0/ai/usage-data/user` + - Retrieves a user's combined Spotter usage: every pool the user draws from, with usage, warning limits, and limits summed across them. - |ThoughtSpot Cloud: __26.11.0.cl or later__ + - ThoughtSpot Software: __Not available__ a| +++Try it out+++ - - a|`POST /api/rest/2.0/ai/usage-data/search` + - Retrieves Spotter usage pools: the question allowance configured for each user, user group, or Org and how much has been consumed. - |ThoughtSpot Cloud: __26.11.0.cl or later__ + - ThoughtSpot Software: __Not available__ a| +++Try it out+++ - - a|`POST /api/rest/2.0/ai/usage-data/update` + - Creates or updates Spotter usage pools, setting the question allowance for a user, user group, or Org. - |ThoughtSpot Cloud: __26.11.0.cl or later__ + - ThoughtSpot Software: __Not available__ a| +++Try it out+++ - - a|`POST /api/rest/2.0/ai/usage-data/delete` + - Deletes Spotter usage pools. Users who no longer draw from any pool are no longer metered. - |ThoughtSpot Cloud: __26.11.0.cl or later__ + - ThoughtSpot Software: __Not available__ a| +++Try it out+++ - - a|`POST /api/rest/2.0/ai/shareAnalyst` + - Updates share permissions for a Spotter Analyst. Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. - |ThoughtSpot Cloud: __26.11.0.cl or later__ + - ThoughtSpot Software: __Not available__ a| +++Try it out+++ - |===== +a|`GET /api/rest/2.0/ai/usage-data/user` [beta betaBackground]^Beta^ + +Retrieves a user's combined Spotter usage: every pool the user draws from, with usage, warning limits, and limits summed across them. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/usage-data/search` [beta betaBackground]^Beta^ + +Retrieves Spotter usage pools: the question allowance configured for each user, user group, or Org and how much has been consumed. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/usage-data/update` [beta betaBackground]^Beta^ + +Creates or updates Spotter usage pools, setting the question allowance for a user, user group, or Org. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/usage-data/delete` [beta betaBackground]^Beta^ + +Deletes Spotter usage pools. Users who no longer draw from any pool are no longer metered. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share` [beta betaBackground]^Beta^ + +Updates share permissions on a Spotter Analyst for one or more users or groups. Requires ownership of the Analyst, or `ADMINISTRATION` or `CAN_MANAGE_SPOTTER` privilege. +|ThoughtSpot Cloud: __26.10.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ +|===== -- - + == Authentication [div boxAuto] @@ -438,7 +438,7 @@ Updates a custom calendar. |ThoughtSpot Cloud: __10.12.0.cl or later__ + ThoughtSpot Software: __26.3.0.sw or later__ a|+++Try it out+++ -|==== +|===== -- == Data @@ -618,6 +618,41 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| |===== -- +== Input tables + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/input-tables/create` + +Creates an input table in the external Cloud Data Warehouse and links it to a ThoughtSpot model. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` + +Adds one or more editable columns to an existing input table. +|ThoughtSpot Cloud: __26.11.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 into an input table using a keyed upsert (MERGE). +|ThoughtSpot Cloud: __26.11.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 and drops the physical table from the Cloud Data Warehouse. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` + +Deletes an editable column from an input table. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ +|===== +-- + == Jobs @@ -631,7 +666,27 @@ a|`POST /api/rest/2.0/jobs/history/communication-channels/search` + Gets information about the execution and delivery status for scheduled jobs such as webhook delivery. |ThoughtSpot Cloud: __26.4.0.cl or later__ ThoughtSpot Software: __Not available__ - a| +++Try it out+++ +a| +++Try it out+++ +|===== +-- + +== Link customization + +[div boxAuto] +-- +[width="100%" cols="6,6,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link +a|`POST /api/rest/2.0/customization/links/search` + +Retrieves the URL templates ThoughtSpot uses to generate shareable links, at the cluster level or for the caller's Org. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/links/update` + +Sets or resets the URL templates at the cluster level or for the caller's Org. +|ThoughtSpot Cloud: __26.11.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ |===== -- @@ -1434,59 +1489,3 @@ a|ThoughtSpot Cloud: __10.14.0.cl or later__ a| +++Try it out +++ |===== -- - - - [#inputTables] - == Input Tables - [div tableContainer] - -- - [width="100%", cols="2,1,4"] - [options='header'] - |=== - |API endpoint | HTTP verb | Description - - |`/api/rest/2.0/input/tables/create` - |POST - |Creates an input table and links it to a ThoughtSpot model. Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. - - |`/api/rest/2.0/input/tables/{input_table_identifier}/update` - |POST - |Updates the name, description, or both of an input table. Requires `MODIFY` permission on the input table. - - |`/api/rest/2.0/input/tables/{input_table_identifier}/delete` - |POST - |Deletes an input table. Requires `MODIFY` permission on the table's parent model. - - |`/api/rest/2.0/input/tables/columns/create` - |POST - |Adds a column to an existing input table. Requires `MODIFY` permission on the input table. - - |`/api/rest/2.0/input/tables/columns/{column_identifier}/delete` - |POST - |Deletes a column from an input table. Requires `MODIFY` permission on the input table. - |=== - -- - - For more information, see xref:input-table-api.adoc[Input Table APIs]. - - [#linkCustomization] - == Link Customization - [div tableContainer] - -- - [width="100%", cols="2,1,4"] - [options='header'] - |=== - |API endpoint | HTTP verb | Description - - |`/api/rest/2.0/customization/links/search` - |POST - |Returns the URL templates at the `CLUSTER` level or for the caller's Org. Templates define the URLs generated for shareable links, scheduled emails, and alert notifications. - - |`/api/rest/2.0/customization/links/update` - |POST - |Sets or resets URL templates. Use `REPLACE` to set a template or `RESET` to clear an Org-level override and fall back to the cluster default. - |=== - -- - - For more information, see xref:link-customization-api.adoc[Link Customization APIs]. - \ No newline at end of file diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 1700f8f41..078d15795 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -10,63 +10,90 @@ This changelog lists the features and enhancements introduced in REST API v2.0. == Version 26.11.0.cl, November 2026 - === Org-level API rate limiting enforced - The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response. +=== Org-level API rate limiting enforced +The Org-level rate limit of 50 requests per second (RPS) per Org is now enforced for all public REST API endpoints on instances with Orgs enabled. This limit was announced in 26.10.0.cl and operates independently of the existing cluster-level limit of 100 RPS per client IP. Requests exceeding the Org-level limit receive an `HTTP 429: Too Many Requests` response. - For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. - === Link Customization APIs - ThoughtSpot introduces two REST API v2.0 endpoints for managing the URL templates used when ThoughtSpot generates shareable links. +=== Link Customization APIs +ThoughtSpot introduces two REST API v2.0 endpoints for managing the URL templates used when ThoughtSpot generates shareable links. - * `POST /api/rest/2.0/customization/links/search` + - Retrieves the URL templates at the cluster level or for the Org the caller is signed in to. - * `POST /api/rest/2.0/customization/links/update` + - Updates the URL templates at the cluster level or for the caller's Org, using `REPLACE` to set templates or `RESET` to clear overrides. +* `POST /api/rest/2.0/customization/links/search` + +Retrieves the URL templates at the cluster level or for the Org the caller is signed in to. +* `POST /api/rest/2.0/customization/links/update` + +Updates the URL templates at the cluster level or for the caller's Org, using `REPLACE` to set templates or `RESET` to clear overrides. - Supported link types include `LIVEBOARD_SHARE_URL`, `VISUALIZATION_SHARE_URL`, `ANSWER_SHARE_URL`, `SPOTIQ_ANALYSIS_URL`, `UNSUBSCRIBE_URL`, `GENERIC_URL`, and `CONVERSATION_SHARE_URL`. +Supported link types include `LIVEBOARD_SHARE_URL`, `VISUALIZATION_SHARE_URL`, `ANSWER_SHARE_URL`, `SPOTIQ_ANALYSIS_URL`, `UNSUBSCRIBE_URL`, `GENERIC_URL`, and `CONVERSATION_SHARE_URL`. - Requires `ADMINISTRATION` or `DEVELOPER` privilege. +Requires `ADMINISTRATION` or `DEVELOPER` privilege. - For more information, see xref:link-customization-api.adoc[Link Customization APIs]. +For more information, see xref:link-customization-api.adoc[Link Customization APIs]. - === Input Table APIs - ThoughtSpot introduces five REST API v2.0 endpoints for managing input tables — user-editable tables stored in an external Cloud Data Warehouse and linked to a ThoughtSpot model. +=== Input Table APIs +ThoughtSpot introduces five REST API v2.0 endpoints for managing input tables — user-editable tables stored in an external Cloud Data Warehouse and linked to a ThoughtSpot model. - * `POST /api/rest/2.0/input/tables/create` + - Creates an input table. - * `POST /api/rest/2.0/input/tables/{input_table_identifier}/update` + - Updates an input table's name or description. - * `POST /api/rest/2.0/input/tables/{input_table_identifier}/delete` + - Deletes an input table. - * `POST /api/rest/2.0/input/tables/columns/create` + - Adds a column to an input table. - * `POST /api/rest/2.0/input/tables/columns/{column_identifier}/delete` + - Deletes a column from an input table. +* `POST /api/rest/2.0/input-tables/create` + +Creates an input table and links it to a ThoughtSpot model. +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` + +Writes rows to an input table using a keyed upsert (MERGE). +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` + +Deletes an input table. +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` + +Adds one or more editable columns to an input table. +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` + +Deletes an editable column from an input table. - Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. +Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. - For more information, see xref:input-table-api.adoc[Input Table APIs]. +For more information, see xref:input-table-api.adoc[Input Table APIs]. - === Spotter Usage Data APIs [Beta] - ThoughtSpot introduces four REST API v2.0 endpoints for managing Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. +=== Spotter Usage Data APIs [beta betaBackground]^Beta^ +ThoughtSpot introduces four REST API v2.0 endpoints for managing Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. - * `GET /api/rest/2.0/ai/usage-data/user` + - Retrieves a user's combined Spotter usage across all pools. - * `POST /api/rest/2.0/ai/usage-data/search` + - Retrieves usage pools configured for users, user groups, or Orgs. - * `POST /api/rest/2.0/ai/usage-data/update` + - Creates or updates usage pools, setting question allowances. - * `POST /api/rest/2.0/ai/usage-data/delete` + - Deletes usage pools. +* `GET /api/rest/2.0/ai/usage-data/user` + +Retrieves a user's combined Spotter usage across all pools. +* `POST /api/rest/2.0/ai/usage-data/search` + +Retrieves usage pools configured for users, user groups, or Orgs. +* `POST /api/rest/2.0/ai/usage-data/update` + +Creates or updates usage pools, setting question allowances. +* `POST /api/rest/2.0/ai/usage-data/delete` + +Deletes usage pools. - For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data APIs]. +For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data APIs]. - === Share Analyst API - The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. +=== Webhook configuration reset - Requires `DATAMANAGEMENT` or `ADMINISTRATION` privilege. +The `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` endpoint now supports the following parameters: - == Version 26.10.0.cl, October 2026 +* `operation` + +`REPLACE` (default) updates the fields provided in the request. `RESET` clears the sections specified in `reset_options` and accepts no other fields. +* `reset_options` + +The sections to remove from the webhook configuration when `operation` is `RESET`: `AUTHENTICATION`, `SIGNATURE_VERIFICATION`, and `STORAGE_DESTINATION`. + +=== Paging for dependent objects in metadata search + +The `POST /api/rest/2.0/metadata/search` endpoint supports paging through the dependent objects of each metadata object: + +* `dependent_objects_record_offset` + +Request parameter. The number of dependent objects to skip for each metadata object. Use it with `dependent_objects_record_size`, which sets the page size (default: 50). A negative value is rejected. If you omit this parameter, the API returns dependent objects as before. +* `dependent_objects_is_last_batch` + +Response attribute. `true` when the returned page of `dependent_objects` is the last one for the object. A full page returns `false` even when it is the final page, so continue requesting pages until the value is `true`. + +=== Maintenance schedule in system information + +The `GET /api/rest/2.0/system` response includes the `maintenance_schedule` object with details of the next maintenance window scheduled for the cluster. The object is absent when no maintenance is scheduled and includes the following attributes: + +* `start_time_in_millis`: Start time of the maintenance window in milliseconds since epoch. +* `duration_in_seconds`: Expected duration of the maintenance window. +* `status`: `SCHEDULED` or `AD_HOC`. +* `type`: `UPGRADE` or `PATCH`. +* `description`: Description of the maintenance event. + +=== Role identifiers in group import + +The group objects in the `POST /api/rest/2.0/groups/import` request body accept `role_identifiers`, an array of role IDs or names to assign to the group. + +== Version 26.10.0.cl, October 2026 === Spotter AI APIs @@ -79,6 +106,8 @@ Creates a Spotter Analyst with a name, description, data sources, and optional i Returns the Spotter Analysts visible to the caller. * `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/update` + Updates a Spotter Analyst. +* `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/share` [beta betaBackground]^Beta^ + +Updates share permissions on a Spotter Analyst for one or more users or groups. Granting access also shares the Analyst's data sources with the principal. * `POST /api/rest/2.0/ai/agent/analysts/{analyst_identifier}/delete` + Deletes a Spotter Analyst. + diff --git a/modules/ROOT/pages/spotter-usage-data-api.adoc b/modules/ROOT/pages/spotter-usage-data-api.adoc index 2b18c8767..82278ea07 100644 --- a/modules/ROOT/pages/spotter-usage-data-api.adoc +++ b/modules/ROOT/pages/spotter-usage-data-api.adoc @@ -4,221 +4,190 @@ :page-title: Spotter Usage Data APIs :page-pageid: spotter-usage-data-api -:page-description: Use the Spotter Usage Data APIs to manage Spotter question allowances for users, user groups, and Orgs. +:page-description: Use the Spotter usage data REST API v2 endpoints to manage Spotter question allowances for users, user groups, and Orgs. +:keywords: Spotter usage, usage pools, usage limits, question allowance, Spotter limits, REST API -Spotter usage pools let administrators control how many Spotter questions a user, user group, or Org can ask. Each pool tracks a question allowance, a warning threshold, and how many questions have been consumed. +Spotter usage pools let administrators control how many Spotter questions a user, user group, or Org can ask. Each pool tracks a question allowance, a warning threshold, and the number of questions consumed. -The Spotter Usage Data REST API v2.0 endpoints allow you to create, retrieve, update, and delete usage pools programmatically. Use these APIs to provision limits for new users, monitor consumption, raise or lower limits, or reset usage at the start of a billing period. +ThoughtSpot provides public REST API v2 endpoints to create, retrieve, update, and delete usage pools programmatically for the following purposes: + +* To provision limits for new users or groups. +* To monitor consumption and find pools that are close to their limit. +* To raise or lower the limits. +* To reset usage at the start of a billing period. [NOTE] ==== -[.version-badge.new]#Beta# + -The Spotter Usage Data APIs are in Beta in ThoughtSpot Cloud 26.11.0.cl. Breaking changes may be introduced before the endpoints are made Generally Available. +The Spotter usage data APIs are in Beta in ThoughtSpot Cloud 26.11.0.cl. Breaking changes may be introduced before the endpoints are made Generally Available. ==== -== Concepts - -=== Usage pools +== Usage pools and metering +A *usage pool* is a Spotter question allowance assigned to an entity: a user, a user group, or an Org. Each pool tracks the following values: -A *usage pool* is a Spotter question allowance assigned to an entity — a user, a user group, or an Org. Each pool tracks: - -* `usage` — questions consumed from the pool. -* `warning_limit` — usage level at which users start seeing a warning. Optional. -* `limit` — maximum questions the pool allows. Optional; when absent the pool is unlimited. +* `usage` + +The number of questions consumed from the pool. +* `warning_limit` + +The usage level at which users start seeing a warning. Optional. +* `limit` + +The maximum number of questions that the pool allows. Optional. If it is not set, the pool is unlimited. === Metering scope - -A cluster meters Spotter usage at exactly one scope: per user, per user group, or per Org. The first pool created on the cluster sets the scope. Every pool created after that must use the same `entity_type`. To switch scope, delete all existing pools first using the <> endpoint. +A cluster meters Spotter usage at exactly one scope: per user, per user group, or per Org. The first pool created on the cluster sets the scope, and every pool created after that must use the same `entity_type`. To switch the scope, delete all existing pools using the <> API endpoint. === How users draw from pools - -A user draws from every pool that meters them: their own pool (if per-user metering), the pools of the user groups they belong to, including inherited groups (if per-group metering), or their Org's pool (if per-Org metering). Totals in the <> response are sums across those pools. +A user draws from every pool that meters them. Depending on the metering scope of the cluster, these are the user's own pool (per user), the pools of the user groups that the user belongs to, including inherited groups (per user group), or the pool of the user's Org (per Org). The totals in the <> response are sums across these pools. For example, a user in two groups with limits of 100 and 50 has a `total_limit` of 150. A user who draws from no pool is not metered and can use Spotter without a limit. -== Required privileges +=== Required privileges +To use the Spotter usage data APIs, the user requires the following privileges: -* **Get usage data for user** — Any user can retrieve their own usage. Retrieving another user's usage requires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege. -* **Search, Update, Delete** — Require `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege. Users with only `CAN_MANAGE_SPOTTER`, and Org administrators without cluster-level `ADMINISTRATION`, cannot call these endpoints. +* **Get usage data for user**: Any user can retrieve their own usage. To retrieve another user's usage, the user requires `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege. `CAN_MANAGE_SPOTTER` is not sufficient. +* **Search, update, and delete usage data**: These endpoints require `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege. Users with only `CAN_MANAGE_SPOTTER`, and Org administrators without cluster-level `ADMINISTRATION`, cannot call these endpoints. [#get-usage-data-for-user] -== Get usage data for user - -Retrieves a user's combined Spotter usage: every usage pool the user draws from, with usage, warning limits, and limits summed across them. Use this endpoint to show users how many Spotter questions they have left or to check whether a user is blocked by a usage limit. +== Getting usage data for a user [beta betaBackground]^Beta^ +The `GET /api/rest/2.0/ai/usage-data/user` API endpoint retrieves a user's combined Spotter usage: every usage pool that the user draws from, with usage, warning limits, and limits summed across them. Use this endpoint to show users how many Spotter questions they have left, or to check whether a user is blocked by a usage limit. -=== Endpoint - ----- -GET /api/rest/2.0/ai/usage-data/user ----- - -=== Query parameters - -[width="100%", cols="2,1,1,4", options="header"] +=== Request parameters +[cols="2,4", options="header"] |=== -| Parameter | Type | Required | Description - +|Parameter | Description | `user_identifier` -| String -| No -| GUID of the user whose usage to retrieve. Defaults to the authenticated user. Passing another user's GUID requires `ADMINISTRATION` privilege. - +|__String__. Optional. Query parameter. GUID of the user whose usage you want to retrieve. If you omit this parameter, the API returns the usage of the authenticated user. Passing another user's GUID requires `ADMINISTRATION` privilege. |=== -=== Response - -If the request is successful, the API returns a `summary` object with the following properties: +=== Example request -[width="100%", cols="2,1,4", options="header"] -|=== -| Property | Type | Description - -| `pools` -| Array -| The individual pools the user draws from. - -| `total_usage` -| Integer -| Total questions consumed across all pools. - -| `total_warning_limit` -| Integer -| Sum of warning limits across all pools. - -| `total_limit` -| Integer -| Sum of limits across all pools. - -| `total_remaining` -| Integer -| Questions the user can still ask. Absent when `has_unlimited_pool` is `true`. - -| `is_at_warning` -| Boolean -| `true` when usage has reached the combined warning limit. - -| `is_at_limit` -| Boolean -| `true` when usage has reached the combined limit and further Spotter questions are blocked. - -| `has_unlimited_pool` -| Boolean -| `true` when any of the user's pools has no limit, making the user effectively unlimited. - -|=== - -=== Request example - -.cURL -[source, cURL] +.Retrieve the authenticated user's usage +[source,cURL] ---- curl -X GET \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/user' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/user' \ -H 'Accept: application/json' \ - -H 'Authorization: Bearer {access-token}' + -H 'Authorization: Bearer {AUTH_TOKEN}' ---- -.cURL (retrieve another user's usage) -[source, cURL] +.Retrieve another user's usage +[source,cURL] ---- curl -X GET -G \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/user' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/user' \ -H 'Accept: application/json' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-urlencode 'user_identifier={user-guid}' ---- -=== Response codes +=== Example response +If the API request is successful, the API returns the following response: -[width="100%", cols="1,3", options="header"] +[source,JSON] +---- +{ + "summary": { + "pools": [ + { + "key": { + "entity_type": "USER_GROUP", + "entity_identifier": "{group-guid-1}" + }, + "usage": 120, + "warning_limit": 80, + "limit": 100, + "updated_time_in_millis": 1793433600000, + "updated_by": "{admin-user-guid}" + }, + { + "key": { + "entity_type": "USER_GROUP", + "entity_identifier": "{group-guid-2}" + }, + "usage": 0, + "warning_limit": 40, + "limit": 50, + "updated_time_in_millis": 1793433600000, + "updated_by": "{admin-user-guid}" + } + ], + "total_usage": 120, + "total_warning_limit": 120, + "total_limit": 150, + "total_remaining": 30, + "is_at_warning": true, + "is_at_limit": false, + "has_unlimited_pool": false + } +} +---- + +=== Response parameters +[cols="2,4", options="header"] +|=== +| Parameter | Description +| `summary` +a| The user's combined usage across every pool that the user draws from. The object includes the following attributes: + +* `pools`: The individual pools that the user draws from. Each entry has the same attributes as an entry in the `usage_data` array returned by the <> API. The array is empty if the user is not metered. +* `total_usage`: Total questions consumed across all pools. +* `total_warning_limit`: Sum of the warning limits across all pools. +* `total_limit`: Sum of the limits across all pools. +* `total_remaining`: Questions that the user can still ask. Absent when `has_unlimited_pool` is `true`. +* `is_at_warning`: `true` when usage has reached the combined warning limit. +* `is_at_limit`: `true` when usage has reached the combined limit and further Spotter questions are blocked. For a user who is not metered, the value is `false`. +* `has_unlimited_pool`: `true` when any of the user's pools has no limit, which makes the user effectively unlimited. +|=== + +=== Response codes +[cols="1,3", options="header"] |=== | HTTP status code | Description | **200** | Successful operation. | **400** | Invalid request. | **401** | Authentication token is missing, expired, or invalid. | **403** | The caller requested another user's usage without `ADMINISTRATION` privilege. -| **500** | Internal server error. +| **500** | Unexpected server error. |=== [#search-usage-data] -== Search usage data - -Retrieves Spotter usage pools. A usage pool is the Spotter question allowance configured for a user, user group, or Org, together with how many questions have been consumed. Use this endpoint to monitor usage across your users, for example to find pools that are close to their limit. +== Searching usage data [beta betaBackground]^Beta^ +The `/api/rest/2.0/ai/usage-data/search` API endpoint retrieves Spotter usage pools. A usage pool is the Spotter question allowance configured for a user, user group, or Org, together with the number of questions consumed from it. Use this endpoint to monitor usage across your users, for example, to find pools that are close to their limit. -=== Endpoint +To retrieve every pool on the cluster, send an empty request body. To retrieve specific pools, pass `keys`. The API omits keys that match no pool from the response. ----- -POST /api/rest/2.0/ai/usage-data/search ----- +To see the combined usage of a single user across every pool the user draws from, use the <> API endpoint. === Request parameters - -[width="100%", cols="2,1,1,4", options="header"] +[cols="2,4", options="header"] |=== -| Parameter | Type | Required | Description - +|Parameter | Description | `keys` -| Array of objects -| No -| Keys of the pools to retrieve. Each key has an `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and an `entity_identifier` (the GUID of the user or user group, or the ID of the Org). Omit to retrieve every pool on the cluster. - -|=== - -=== Response - -If the request is successful, the API returns `usage_data`, one entry per pool: - -[width="100%", cols="2,1,4", options="header"] -|=== -| Property | Type | Description - -| `key` -| Object -| The entity the pool meters, with `entity_type` and `entity_identifier`. - -| `usage` -| Integer -| Questions consumed from the pool. - -| `warning_limit` -| Integer -| Usage level at which users are warned. Absent when no warning is configured. - -| `limit` -| Integer -| Maximum questions the pool allows. Absent when the pool is unlimited. - -| `updated_time_in_millis` -| Long -| Timestamp of when the pool was last configured. - -| `updated_by` -| String -| User who last configured the pool. +a|__Array of objects__. Optional. The pools to retrieve. If you omit this parameter, the API returns every pool on the cluster. For each key, specify the following attributes: +* `entity_type`. __String__. Type of entity that the pool meters: `USER`, `USER_GROUP`, or `ORG`. It must match the scope that the cluster meters at. +* `entity_identifier`. __String__. GUID of the user or user group, or the ID of the Org. |=== -=== Request example +=== Example request -.cURL (retrieve all pools) -[source, cURL] +.Retrieve all pools +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/search' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/search' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{}' ---- -.cURL (retrieve specific pools) -[source, cURL] +.Retrieve specific pools +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/search' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/search' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "keys": [ { @@ -229,78 +198,83 @@ curl -X POST \ }' ---- -=== Response codes +=== Example response +If the API request is successful, the API returns the following response: -[width="100%", cols="1,3", options="header"] +[source,JSON] +---- +{ + "usage_data": [ + { + "key": { + "entity_type": "USER", + "entity_identifier": "{user-guid}" + }, + "usage": 120, + "warning_limit": 400, + "limit": 500, + "updated_time_in_millis": 1793433600000, + "updated_by": "{admin-user-guid}" + } + ] +} +---- + +=== Response parameters +[cols="2,4", options="header"] +|=== +| Parameter | Description +| `usage_data` +a| One entry for each pool. Each entry includes the following attributes: + +* `key`: The entity that the pool meters, with `entity_type` and `entity_identifier`. +* `usage`: Number of questions consumed from the pool. +* `warning_limit`: Usage level at which users are warned that they are approaching the limit. Absent when no warning is configured. +* `limit`: Maximum number of questions that the pool allows. Absent when the pool is unlimited. +* `updated_time_in_millis`: Time of the last change to the pool configuration, in milliseconds since epoch. +* `updated_by`: ID of the user who last changed the pool configuration. +|=== + +=== Response codes +[cols="1,3", options="header"] |=== | HTTP status code | Description | **200** | Successful operation. | **400** | Invalid request. | **401** | Authentication token is missing, expired, or invalid. | **403** | The caller does not have `ADMINISTRATION` privilege. -| **500** | Internal server error. +| **500** | Unexpected server error. |=== [#update-usage-data] -== Create or update usage data - -Creates or updates Spotter usage pools. Use this endpoint to provision limits for new users or groups, raise or lower an existing limit, or reset usage at the start of a billing period. +== Creating or updating usage data [beta betaBackground]^Beta^ +The `/api/rest/2.0/ai/usage-data/update` API endpoint creates or updates Spotter usage pools. Use this endpoint to provision limits for new users or groups, raise or lower an existing limit, or reset usage at the start of a billing period. -A pool that does not exist is created. Fields omitted from an update keep their current value. - -=== Endpoint - ----- -POST /api/rest/2.0/ai/usage-data/update ----- +A pool that does not exist is created. Fields omitted from an update keep their current value. Every key must use the scope that the cluster meters at. To switch the scope, delete the existing pools first. === Request parameters - -[width="100%", cols="2,1,1,4", options="header"] +[cols="2,4", options="header"] |=== -| Parameter | Type | Required | Description - +|Parameter | Description | `updates` -| Array of objects -| Yes -| At least one entry. Each entry contains the following properties. - -| `updates[].key` -| Object -| Yes -| The pool to create or update, with `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and `entity_identifier` (the GUID of the user or user group, or the ID of the Org). - -| `updates[].limit` -| Integer -| No -| Maximum Spotter questions the pool allows. - -| `updates[].warning_limit` -| Integer -| No -| Usage level at which users are warned that they are approaching the limit. - -| `updates[].usage` -| Integer -| No -| Questions consumed so far. Set to `0` to reset the pool. +a|__Array of objects__. The changes to apply, one entry for each pool. At least one entry is required. For each entry, specify the following attributes: +* `key`. __Object__. The pool to create or update. Specify the `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and the `entity_identifier` (the GUID of the user or user group, or the ID of the Org). The `entity_type` must match the scope that the cluster meters at. +* `limit`. __Integer__. Optional. Maximum number of Spotter questions that the pool allows. +* `warning_limit`. __Integer__. Optional. Usage level at which users are warned that they are approaching the limit. +* `usage`. __Integer__. Optional. Number of questions consumed so far. Set it to `0` to reset the pool. |=== -=== Response - -If the request is successful, the API returns `usage_data`, with each updated pool as it stands after the change. The response structure is the same as the <> response. +=== Example request -=== Request example - -.cURL (create a pool for a user) -[source, cURL] +.Create a pool for a user +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/update' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "updates": [ { @@ -315,14 +289,14 @@ curl -X POST \ }' ---- -.cURL (reset a pool's usage to zero) -[source, cURL] +.Reset the usage of a pool to zero +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/update' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/update' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "updates": [ { @@ -336,63 +310,70 @@ curl -X POST \ }' ---- -=== Response codes +=== Example response +If the API request is successful, the API returns `usage_data` with each updated pool as it stands after the change. The response has the same structure as the response of the <> API. + +[source,JSON] +---- +{ + "usage_data": [ + { + "key": { + "entity_type": "USER", + "entity_identifier": "{user-guid}" + }, + "usage": 0, + "warning_limit": 400, + "limit": 500, + "updated_time_in_millis": 1793433600000, + "updated_by": "{admin-user-guid}" + } + ] +} +---- -[width="100%", cols="1,3", options="header"] +=== Response codes +[cols="1,3", options="header"] |=== | HTTP status code | Description | **200** | Successful operation. -| **400** | `updates` is empty, a key is missing its `entity_type` or `entity_identifier`, or a key uses a different `entity_type` from the cluster's existing pools. +| **400** | Invalid request. For example, `updates` is empty, a key is missing its `entity_type` or `entity_identifier`, or a key uses a different `entity_type` from the existing pools on the cluster. | **401** | Authentication token is missing, expired, or invalid. | **403** | The caller does not have `ADMINISTRATION` privilege. -| **500** | Internal server error. +| **500** | Unexpected server error. |=== [#delete-usage-data] -== Delete usage data - -Deletes Spotter usage pools. Use this endpoint to remove a limit from a user, user group, or Org, or to clear every pool before switching the metering scope. +== Deleting usage data [beta betaBackground]^Beta^ +The `/api/rest/2.0/ai/usage-data/delete` API endpoint deletes Spotter usage pools. Use this endpoint to remove a limit from a user, user group, or Org, or to clear every pool before switching the metering scope. Deleting a pool removes its limit rather than blocking its users. A user who no longer draws from any pool is not metered and can use Spotter without a limit. [WARNING] ==== -This operation cannot be undone. To recreate a deleted pool, use the <> endpoint. The new pool's usage restarts from `0`. +This operation cannot be undone. To recreate a deleted pool, use the <> API endpoint. The usage of the new pool restarts from `0`. ==== -=== Endpoint - ----- -POST /api/rest/2.0/ai/usage-data/delete ----- - === Request parameters - -[width="100%", cols="2,1,1,4", options="header"] +[cols="2,4", options="header"] |=== -| Parameter | Type | Required | Description - +|Parameter | Description | `keys` -| Array of objects -| Yes -| At least one entry. Each key has an `entity_type` (`USER`, `USER_GROUP`, or `ORG`) and an `entity_identifier` (the GUID of the user or user group, or the ID of the Org). +a|__Array of objects__. The pools to delete. At least one entry is required. For each key, specify the following attributes: +* `entity_type`. __String__. Type of entity that the pool meters: `USER`, `USER_GROUP`, or `ORG`. It must match the scope that the cluster meters at. +* `entity_identifier`. __String__. GUID of the user or user group, or the ID of the Org. |=== -=== Response +=== Example request -If the request is successful, the API returns `deleted_keys`, the keys of the pools that existed and were deleted. Keys that matched no pool are omitted from the response. - -=== Request example - -.cURL -[source, cURL] +[source,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/delete' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/usage-data/delete' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {access-token}' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "keys": [ { @@ -403,14 +384,37 @@ curl -X POST \ }' ---- -=== Response codes +=== Example response +If the API request is successful, the API returns `deleted_keys`, the keys of the pools that existed and were deleted. The API omits keys that matched no pool. + +[source,JSON] +---- +{ + "deleted_keys": [ + { + "entity_type": "ORG", + "entity_identifier": "{org-id}" + } + ] +} +---- -[width="100%", cols="1,3", options="header"] +=== Response codes +[cols="1,3", options="header"] |=== | HTTP status code | Description | **200** | Successful operation. -| **400** | `keys` is empty, or a key is missing its `entity_type` or `entity_identifier`. +| **400** | Invalid request. For example, `keys` is empty, or a key is missing its `entity_type` or `entity_identifier`. | **401** | Authentication token is missing, expired, or invalid. | **403** | The caller does not have `ADMINISTRATION` privilege. -| **500** | Internal server error. +| **500** | Unexpected server error. |=== + +== Additional resources + +* xref:rest-api-v2-reference.adoc#_ai[REST API v2.0 Reference] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] +* +++REST API Playground - Get usage data for user endpoint+++ +* +++REST API Playground - Search usage data endpoint+++ +* +++REST API Playground - Update usage data endpoint+++ +* +++REST API Playground - Delete usage data endpoint+++ From b3a1fc7b26fdc81bf32242ebacd0123ae5d017f3 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 12:55:54 +0530 Subject: [PATCH 057/169] obj id updtes --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 23 ++++++++++++------- modules/ROOT/pages/object-id-in-urls.adoc | 6 +++-- modules/ROOT/pages/object-id.adoc | 12 +++++----- 3 files changed, 25 insertions(+), 16 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index d68abe02a..5074f7e40 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -4,11 +4,11 @@ :page-title: ThoughtSpot objects :page-pageid: thoughtspot-objects -:page-description: +:page-description: Learn about ThoughtSpot objects, their identifiers, and how they are organized in the ThoughtSpot data model. -ThoughtSpot is a business intelligence and data analytics platform for exploring, analyzing, and sharing real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system. +ThoughtSpot is a business intelligence (BI) and data analytics platform for exploring, analyzing, and sharing real-time business analytics and interactive insights. ThoughtSpot Search is the core of the ThoughtSpot system, making it distinct from other BI tools. -Review this page to understand how ThoughtSpot's architecture differs from other BI tools before proceeding with the developer documentation. +This page explains how ThoughtSpot's architecture differs from other BI tools. Read this before proceeding with the developer documentation. == Object model hierarchy @@ -16,9 +16,9 @@ The following figure illustrates the object model hierarchy in ThoughtSpot withi image::./images/object_model_hierarchy.png[Object Model Hierarchy] +[#object-identifiers] == Object identifiers -[#object-identifiers] Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. ##Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID.## [#_supported_object_types] @@ -37,8 +37,9 @@ Because you choose the `obj_id`, related copies of an object in different Orgs a ##Use an `obj_id` instead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs.## == Data modeling + A data model requires at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. -Most often, there will be multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users. +In most cases, there are multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users. Data engineers with the *Can manage data* privilege can add connections either link:https://docs.thoughtspot.com/cloud/latest/connections[in the UI, window=_blank] or via xref:connections.adoc[REST API]. Connections are owned and accessible only to their creator, who then imports *Tables* from the connection. Once imported, tables can be shared with other ThoughtSpot groups and users. @@ -50,6 +51,7 @@ Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0. ==== === Data modeling workflow + 1. Create a *connection* to a cloud data warehouse. 2. Import *tables* from the *connection*. 3. Create link:https://docs.thoughtspot.com/cloud/latest/models[*Models*, window=_blank] (analytic data models) based on tables. @@ -58,6 +60,7 @@ Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0. ThoughtSpot also supports programmatic deployment of data models via link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] and table import from link:https://docs.thoughtspot.com/cloud/latest/dbt-integration#integrate[dbt, window=_blank]. == Content creation + ThoughtSpot Search data creates a table or chart view based on the query in the search bar and any additional view configuration applied after the search results are displayed. Search data serves the role of report builder or widget designer, while *Liveboards* serve the role of dashboards in other tools. A single search can be saved as a link:https://docs.thoughtspot.com/cloud/latest/answers[*Answer*, window=_blank] object, or the search result can be pinned to a Liveboard. @@ -72,6 +75,7 @@ To create content: 2. Save the search result as an *Answer* or pin it to a Liveboard as a visualization. === Visualizations on a Liveboard + Any number of visualizations from search results can be added to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as *Answers*. Each time a search result is pinned, a separate new visualization is created on the Liveboard. @@ -85,6 +89,7 @@ To edit a visualization on a Liveboard: Visualizations on a Liveboard have their own GUIDs, but the visualization objects do not exist separately from the Liveboard object. === Tags + link:https://docs.thoughtspot.com/cloud/latest/tags[Tags, window=_blank] allow you to organize your objects and find them easily. A tag object is created by the administrator, is visible to all users, and can be assigned by any user. @@ -92,6 +97,7 @@ A tag object is created by the administrator, is visible to all users, and can b Tag search is always an *OR* operation: filtering on multiple tags results in all objects with any of the tags, not just those with all of the specified tags. == Access control (sharing) + ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/data-security[access control model, window=_blank] works by having an `author` or `administrator` share objects with link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[ThoughtSpot groups, window=_blank] or individual users: * The creator of an object is referred to as the *author*. @@ -101,10 +107,12 @@ ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/data-security[acces An administrator can share any object with any group or user without restrictions. ThoughtSpot administrators can add users locally link:https://docs.thoughtspot.com/cloud/latest/user-management[in the UI, window=_blank] or via xref:api-user-management.adoc[REST API v2.0]. Similarly, they can manage groups and sharing privileges by using the *Groups* feature in the UI or via xref:api-user-management.adoc[REST API v2.0]. === Single sign-on + If xref:configure-saml.adoc[SAML] or xref:configure-oidc.adoc[OpenID Connect (OIDC)] integration is enabled on your instance, users who authenticate with external identity providers (IdP) can log in to ThoughtSpot with their Single Sign-On credentials. Embedded ThoughtSpot instances also support the xref:trusted-authentication.adoc[trusted authentication] method to sign in application users. == Object properties in REST API + The `POST /api/rest/2.0/metadata/search` REST API v2.0 endpoint returns the following properties for each object: * `metadata_id` + @@ -137,6 +145,7 @@ For more information, see xref:rest-api-v2-metadata-search.adoc[Metadata search [#_object_names_in_rest_api_v1] == Object types in REST API v2.0 + Object type names in ThoughtSpot REST API v2.0 differ from the names shown in the ThoughtSpot UI. Use the following values in the `type` attribute of REST API v2.0 requests, such as `/metadata/search`: * *Liveboards*: `LIVEBOARD` @@ -163,6 +172,4 @@ Column and join objects with their own GUIDs do exist within the ThoughtSpot sys == Related resources -* link:https://docs.thoughtspot.com/home/[ThoughtSpot product documentation, window=_blank] - - +* link:https://docs.thoughtspot.com/home/[ThoughtSpot product documentation, window=_blank] \ No newline at end of file diff --git a/modules/ROOT/pages/object-id-in-urls.adoc b/modules/ROOT/pages/object-id-in-urls.adoc index 45e75d0b7..81921b02b 100644 --- a/modules/ROOT/pages/object-id-in-urls.adoc +++ b/modules/ROOT/pages/object-id-in-urls.adoc @@ -4,7 +4,7 @@ :page-title: Object ID in ThoughtSpot URLs :page-pageid: object-id-urls -:page-description: Use an Object ID (obj_id) instead of a GUID in ThoughtSpot URLs so that deep links work in every environment +:page-description: Learn how to use a stable, user-defined Object ID (obj_id) instead of a globally unique identifier (GUID) in ThoughtSpot Liveboard, Answer, Collection, data object, and connection URLs. Use an Object ID (obj_id) instead of a GUID in ThoughtSpot URLs so that deep links work in every environment You can use an object's xref:object-id.adoc[Object ID] (`obj_id`) in place of its GUID in a ThoughtSpot URL. Because you assign the same `obj_id` to an object in every environment, a URL built with an `obj_id` opens the correct object in development, staging, and production. @@ -58,12 +58,14 @@ In each URL, `{id}` can be either the object's GUID or its `obj_id`. Both format A Liveboard URL with a GUID differs in each environment: +[source,text] ---- https://{ThoughtSpot-host}/#/insights/pinboard/a3f9c2e1-7b44-4d8e-9f10-6c2b5e8d1a07 ---- The same Liveboard URL with an `obj_id` is identical in development, staging, and production: +[source,text] ---- https://{ThoughtSpot-host}/#/insights/pinboard/sales-weekly-performance ---- @@ -119,4 +121,4 @@ A value in GUID format is always tried as a GUID first. If a real object has tha * xref:object-id.adoc[Object ID (obj_id)] * xref:intro-thoughtspot-objects.adoc[ThoughtSpot objects] -* xref:development-and-deployment.adoc[Development and deployment] +* xref:development-and-deployment.adoc[Development and deployment] \ No newline at end of file diff --git a/modules/ROOT/pages/object-id.adoc b/modules/ROOT/pages/object-id.adoc index 6639c3e3e..ae157473c 100644 --- a/modules/ROOT/pages/object-id.adoc +++ b/modules/ROOT/pages/object-id.adoc @@ -4,7 +4,7 @@ :page-title: Object ID (obj_id) :page-pageid: object-id -:page-description: Use Object ID (obj_id) to reference ThoughtSpot objects by a stable, user-defined identifier across Orgs and instances +:page-description: Learn how to set and use a stable, user-defined Object ID (obj_id) to identify ThoughtSpot objects consistently across instances, Orgs, and environments. Use Object ID (obj_id) to reference ThoughtSpot objects by a stable, user-defined identifier across Orgs and instances ##Every object in ThoughtSpot has a system-generated GUID. GUIDs are minted per instance, so the same Liveboard promoted from a development environment to a production environment has a different GUID in each one.## @@ -207,7 +207,7 @@ The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of Using the GUID: -[,json] +[source,json] ---- { "metadata": [ @@ -221,7 +221,7 @@ Using the GUID: Using the current `obj_id`: -[,json] +[source,json] ---- { "metadata": [ @@ -235,7 +235,7 @@ Using the current `obj_id`: ##Using the object name and type:## -[,json] +[source,json] ---- { "metadata": [ @@ -250,7 +250,7 @@ Using the current `obj_id`: The request accepts an array, so you can update multiple objects in a single API call. ##Each object in the array can use a different identification method:## -[,json] +[source,json] ---- { "metadata": [ @@ -292,4 +292,4 @@ Set the `obj_id` property in the object's TML and import the TML. For examples, * xref:intro-thoughtspot-objects.adoc[ThoughtSpot objects] * xref:development-and-deployment.adoc[Development and deployment] * xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] -* xref:tml-import.adoc[TML import] +* xref:tml-import.adoc[TML import] \ No newline at end of file From 852affc58957578c09a33869906fedaacf541899 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 13:45:12 +0530 Subject: [PATCH 058/169] obj id updtes --- modules/ROOT/pages/common/nav-in-product-help.adoc | 2 +- modules/ROOT/pages/common/nav.adoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index fc8fd0c2b..897414176 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -202,7 +202,7 @@ Integration with external tools Build and deploy ** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects] -*** link:{{navprefix}}/object-id[Object ID (obj_id)] +*** link:{{navprefix}}/object-id[Object ID] *** link:{{navprefix}}/object-id-urls[Object ID in URLs] ** link:{{navprefix}}/timezone-aware-filtering[Timezone-aware keywords and filters] ** link:{{navprefix}}/variables[Variables] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 509eee2a1..7f23dad91 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -55,8 +55,8 @@ Integration Guides Deployment guides * link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects overview] -** link:{{navprefix}}/object-id[Object ID (obj_id)] -*** link:{{navprefix}}/object-id-urls[Object ID in URLs] +** link:{{navprefix}}/object-id[Object ID] +** link:{{navprefix}}/object-id-urls[Object ID in URLs] * link:{{navprefix}}/timezone-aware-filtering[Timezone-aware keywords and filters] * link:{{navprefix}}/publish-data-overview[Publish content to Orgs] * link:{{navprefix}}/development-and-deployment[Development and deployment] From d5d5c0a59cfaa279059952899b4b6d8201c1832d Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 15:24:40 +0530 Subject: [PATCH 059/169] obj id updtes --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 2 +- modules/ROOT/pages/object-id-in-urls.adoc | 13 +++--- modules/ROOT/pages/object-id.adoc | 43 +++++++++++-------- 3 files changed, 34 insertions(+), 24 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 5074f7e40..ed55cffc5 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -16,9 +16,9 @@ The following figure illustrates the object model hierarchy in ThoughtSpot withi image::./images/object_model_hierarchy.png[Object Model Hierarchy] -[#object-identifiers] == Object identifiers +[#object-identifiers] Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. ##Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID.## [#_supported_object_types] diff --git a/modules/ROOT/pages/object-id-in-urls.adoc b/modules/ROOT/pages/object-id-in-urls.adoc index 81921b02b..7720e16b4 100644 --- a/modules/ROOT/pages/object-id-in-urls.adoc +++ b/modules/ROOT/pages/object-id-in-urls.adoc @@ -1,4 +1,4 @@ -= Object ID in ThoughtSpot URLs += Object ID in ThoughtSpot URLs [earlyAccess eaBackground]#Early Access# :toc: true :toclevels: 2 @@ -8,7 +8,7 @@ You can use an object's xref:object-id.adoc[Object ID] (`obj_id`) in place of its GUID in a ThoughtSpot URL. Because you assign the same `obj_id` to an object in every environment, a URL built with an `obj_id` opens the correct object in development, staging, and production. -Object ID in ThoughtSpot URLs is available from ThoughtSpot Cloud 26.11.0.cl and ThoughtSpot Software 27.3.0.sw. The feature is disabled by default. +This feature is in Early Access and disabled by default. Contact ThoughtSpot Support to enable it for your instance. == When to use Object ID in URLs @@ -94,17 +94,20 @@ The following objects do not have a URL in ThoughtSpot, so `obj_id` cannot be us * Personalized Views * Visualizations and tabs within a Liveboard + +//// == Backward compatibility * All existing GUID-based URLs, bookmarks, and saved links continue to work. * There is no breaking change to the Visual Embed SDK public API. * You can adopt `obj_id` gradually. For example, you can move high-value deep links to `obj_id` and keep using GUIDs for other links. +//// -== Limitations - +[IMPORTANT] +==== * If you change an object's `obj_id`, URLs that use the previous value no longer resolve. Update any links that use the old value. * `obj_id` values are unique within an Org. The same `obj_id` in two Orgs opens a different object in each Org. -* For the `obj_id` format and character limit, see xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format and constraints]. +==== == Troubleshooting diff --git a/modules/ROOT/pages/object-id.adoc b/modules/ROOT/pages/object-id.adoc index ae157473c..c2af6c62c 100644 --- a/modules/ROOT/pages/object-id.adoc +++ b/modules/ROOT/pages/object-id.adoc @@ -12,7 +12,7 @@ An Object ID (`obj_id`) is a customer-defined, human-readable identifier that yo ##Object ID is generally available from ThoughtSpot Cloud 26.9.0.cl.## -== Key concepts +== Overview * `obj_id` is *user-settable* and *unique per Org*. Each Org can have only one object with a particular `obj_id`. * The combination of Org ID and `obj_id` is the uniqueness key, ##so the same `obj_id` in two Orgs refers to two different objects. This is by design.## @@ -29,24 +29,31 @@ Object ID must be enabled on your ThoughtSpot instance ##before `obj_id` partici The following object types support `obj_id`: -[cols="2,2,4", options="header"] +[cols="2,4", options="header"] |=== -|Object type |##TML kind## |##Notes## - -|Liveboard |##`liveboard`## |##Exported in TML and resolved first on import.## -|Answer |##`answer`## | -|Model |##`model`## |##Includes Worksheets.## -|Table |##`table`## | -|##SQL View## |##`sql_view`## | -|##Column## |##None## |##Supported on columns within Tables and Models.## -|##Connection## |##`connection`## | -|Collection |##None## | -|##Custom action## |##None## |##Supported for custom actions managed through the API or the server.## -|Personalized View |##None## |##For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import].## -|Variable |##None## |##Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl.## -|##Memory## |##None## |##Carries an Object ID through the Model it is tagged to.## -|##Group## |##None## | -|Role |##None## | +|Object type |##In TML## + +|Liveboard |##`liveboard`## + +##Exported in TML and resolved first on import.## +|Answer |##`answer`## +|Model |##`model`## + +##Includes Worksheets.## +|Table |##`table`## +|##SQL View## |##`sql_view`## +|##Column## |##None## + +##Supported on columns within Tables and Models.## +|##Connection## |##`connection`## +|Collection |##None## +|##Custom action## |##None## + +##Supported for custom actions managed through the API or the server.## +|Personalized View |##None## + +##For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import].## +|Variable |##None## + +##Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl.## +|##Memory## |##None## + +##Carries an Object ID through the Model it is tagged to.## +|##Group## |##None## +|Role |##None## |=== [IMPORTANT] From 429600c240f5f53759977800bb296ac46c3624dd Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 22:02:15 +0530 Subject: [PATCH 060/169] obj id edits --- modules/ROOT/pages/deploy-with-tml-apis.adoc | 28 ++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/modules/ROOT/pages/deploy-with-tml-apis.adoc b/modules/ROOT/pages/deploy-with-tml-apis.adoc index 213c4f1b2..dfb327bf2 100644 --- a/modules/ROOT/pages/deploy-with-tml-apis.adoc +++ b/modules/ROOT/pages/deploy-with-tml-apis.adoc @@ -116,6 +116,34 @@ Once you have decided on the appropriate `obj_id` for all the objects in your de You only have to do this process for existing objects *one time*, and from that point forward, you can update objects in any Org using TML with obj_ids rather than GUIDs. +[#adopting-obj-id-in-deployment-pipeline] +==== ##Adopting obj_id in a deployment pipeline## +##You can move an existing GUID-based deployment pipeline to `obj_id` one step at a time. Existing GUID-based workflows continue to work while you migrate, and you can start with the objects you deploy most often.## + +. ##*Confirm that Object ID is enabled* on every ThoughtSpot instance in your pipeline. For more information, see## xref:object-id.adoc#_enable_object_id[Enable Object ID]. +. ##*Define a naming convention.* Choose stable, readable identifiers that do not depend on the object's display name or GUID, for example, `--`:## ++ +---- +sales-liveboard-prod +sales-model-prod +hubspot-contacts-table +---- ++ +##The values must follow the## xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format]. +. ##*Assign `obj_id` values in the dev Org.* Use the `metadata/update-obj-id` endpoint or edit the `obj_id` in the object's TML. Replace automatically generated values such as `RetailSalesRAD-KPIs-c1e4043a`: they include part of the GUID, so copies of the same object in different Orgs receive different generated values.## +. ##*Align existing copies in the other Orgs.* Give each existing copy of an object the same `obj_id` as the original in the dev Org. See <<_implementing_obj_id_in_existing_environments,Implementing obj_id in existing environments>>.## +. ##*Export the release TML* with `include_obj_id` and `include_obj_id_ref` set to `true`. See <<_obj_id_or_guid,obj_id or guid>>.## +. ##*Deploy for the first time.* Import the TML into the target Org without a `guid` property. If the object does not exist in the target Org, ThoughtSpot creates it and assigns a new GUID in that Org.## +. ##*Deploy subsequent releases.* Import the same TML. ThoughtSpot finds the existing object by its `obj_id` and updates it.## +. ##*Check the import response* for each file to confirm that it created or updated the expected object.## +// TODO: confirm with engineering whether an obj_id that matches no object falls back to the GUID with a WARNING status (object-id.adoc) or creates a new object ("Rules for create vs. update operations" on this page). If the WARNING fallback is correct, add: "A WARNING status means the obj_id did not match an object and ThoughtSpot matched by GUID instead." +. ##*Retire your GUID mapping.* Once every deployed object has a consistent `obj_id` in all Orgs, you no longer need to maintain a GUID mapping file.## + +[NOTE] +==== +##Visualizations and Liveboard tabs do not have an `obj_id`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, still use a GUID that is different in each Org. For more information, see## xref:object-id.adoc#_objects_that_do_not_support_obj_id[Objects that do not support obj_id]. +==== + [#linkBuildRelease] == Identifying release package in dev Org The set of objects on the *dev Org* that makes up the "deployed releases" should be identified in a way that allows easy identification of the objects to be exported into Git. From 20451b36b217df2499fb32261fd3d44bb54e1a66 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 23:37:36 +0530 Subject: [PATCH 061/169] input table edits --- modules/ROOT/pages/input-table-api.adoc | 95 ++++++------------------- 1 file changed, 22 insertions(+), 73 deletions(-) diff --git a/modules/ROOT/pages/input-table-api.adoc b/modules/ROOT/pages/input-table-api.adoc index 5ea3a1ca0..7e5d5bcf0 100644 --- a/modules/ROOT/pages/input-table-api.adoc +++ b/modules/ROOT/pages/input-table-api.adoc @@ -47,7 +47,7 @@ The caller must also have `MODIFY` permission on the following objects: [#create-input-table] == Creating an input table -The `/api/rest/2.0/input-tables/create` API endpoint creates an input table and links it to a ThoughtSpot model. The physical table is created in the same connection, database, and schema as the linked model. Ensure that the connection user has `CREATE TABLE` permission in the target schema. +The `/api/rest/2.0/input-tables/create` API endpoint creates an input table and links it to a ThoughtSpot model. The physical table is created in the same connection, database, and schema as the linked model. Ensure that the connection user has `CREATE TABLE` permission in the target schema and that upload is enabled on the connection. If upload is disabled, the API returns a `400` error. === Request parameters [cols="2,4", options="header"] @@ -68,12 +68,12 @@ __Array of objects__. The new editable columns to create. For each column, speci ** `name`. __String__. Display name of the column. ** `data_type`. __String__. Data type of the column in the warehouse, for example, `VARCHAR`, `DOUBLE`, or `DATE`. The supported values depend on the underlying CDW. ** `type`. __String__. Semantic role of the column: `ATTRIBUTE` for dimension columns or `MEASURE` for numeric columns. -** `allowed_values`. __Array of strings__. Optional. Up to 500 permitted values, which turn the column into a fixed-choice column. Each value must be non-empty, at most 8192 characters, and valid for the column's `data_type`: a number for numeric types, `true` or `false` for `BOOL`, and an epoch integer for `DATE`, `DATE_TIME`, and `TIME`. Writes that contain any other non-empty value are rejected. +** `allowed_values`. __Array of strings__. Optional. Up to 500 permitted values, which turn the column into a fixed-choice column. Each value must be non-empty, at most 8192 characters, and valid for the column's `data_type`: a number for numeric types, `true` or `false` for `BOOL`, and an epoch integer for `DATE`, `DATE_TIME`, and `TIME`. Writes that contain any other non-empty value are rejected. If you omit this attribute, the column accepts any value that its data type supports. * `referenced_column_time_dimensions` + -__Array of objects__. Optional. Locks the referenced date columns to a specific time dimension (grain) at creation. Each entry includes the `column_identifier`, which is the name of the referenced model column exactly as specified in `referenced_columns`, and the `time_dimension`. Supported values for `time_dimension` are `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, and `YEARLY`. If you omit a column, ThoughtSpot applies no bucketing to it. The time dimension applies only to `DATE` and `DATE_TIME` columns. `HOURLY` requires a `DATE_TIME` column. On a `DATE` column, it is ignored. Date-part grains, such as day of the week, and grains on `TIME` columns are not supported. +__Array of objects__. Optional. Locks the referenced date columns to a specific time dimension (grain) at creation. Each entry includes the `column_identifier`, which is the name of the referenced model column exactly as specified in `referenced_columns`, and the `time_dimension`. Supported values for `time_dimension` are `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, and `YEARLY`. If you omit a column, ThoughtSpot applies no bucketing to it. The time dimension applies only to `DATE` and `DATE_TIME` columns. `HOURLY` requires a `DATE_TIME` column. If you specify `HOURLY` for a `DATE` column, it is ignored and the column is not bucketed. Date-part grains, such as day of the week, and grains on `TIME` columns are not supported. Time dimensions apply only to referenced columns. Columns created through `new_columns` are always unbucketed. |=== -=== Example request +=== Request examples [source,cURL] ---- @@ -104,8 +104,8 @@ curl -X POST \ }' ---- -=== Example response -If the API request is successful, the API returns the following response: +=== API Response +Returns `200 OK` and the input table ID with the details of each column in the input table. [source,JSON] ---- @@ -134,7 +134,8 @@ If the API request is successful, the API returns the following response: } ---- -=== Response parameters +The response includes the following parameters: + [cols="2,4", options="header"] |=== | Parameter | Description @@ -152,18 +153,6 @@ Use the column IDs to address specific columns in later calls without a separate | A note that is present only when ThoughtSpot renames a referenced column to keep the column names of the input table unique. If a model column name occurs in more than one base table, ThoughtSpot prefixes it with the base table name. For example, `Region` becomes `sales_Region`. The final name of the renamed column is also available in `input_columns`, and it is the name you must use when you write rows. |=== -=== Response codes -[cols="1,3", options="header"] -|=== -| HTTP status code | Description -| **200** | Input table created successfully. -| **400** | Invalid request. For example, the payload is invalid, no columns are selected, or upload is disabled on the connection. -| **401** | Authentication token is missing, expired, or invalid. -| **403** | The caller does not have `MODIFY` permission on the model. -| **404** | Model not found. -| **500** | Unexpected server error. -|=== - [#create-input-table-column] == Adding columns to an input table The `/api/rest/2.0/input-tables/{input_table_identifier}/columns/create` API endpoint adds one or more editable columns to an existing input table. This operation widens the physical table in the CDW and refreshes the metadata of the input table in ThoughtSpot, so that the new columns are available on the linked model. @@ -183,7 +172,7 @@ a|__Object__. Defines the columns to add. Specify the following attribute: __Array of objects__. The new editable columns. For each column, specify the `name`, `data_type`, and `type` (`ATTRIBUTE` or `MEASURE`). Optionally, include `allowed_values`. The column name must not collide with an existing column on the table. For more information about these attributes, see <>. |=== -=== Example request +=== Request examples [source,cURL] ---- @@ -205,8 +194,8 @@ curl -X POST \ }' ---- -=== Example response -If the API request is successful, the API returns the added columns with their generated GUIDs. Use these GUIDs as the `column_identifier` to <>. +=== API Response +Returns `200 OK` and the added columns with their generated GUIDs. Use these GUIDs as the `column_identifier` to <>. [source,JSON] ---- @@ -220,18 +209,6 @@ If the API request is successful, the API returns the added columns with their g } ---- -=== Response codes -[cols="1,3", options="header"] -|=== -| HTTP status code | Description -| **200** | Columns added successfully. -| **400** | Invalid request. For example, the payload is invalid or no columns are specified. -| **401** | Authentication token is missing, expired, or invalid. -| **403** | The caller does not have `MODIFY` permission on the input table. -| **404** | Input table not found. -| **500** | Unexpected server error. -|=== - [#update-input-table] == Writing rows to an input table The `/api/rest/2.0/input-tables/{input_table_identifier}/update` API endpoint writes rows into an existing input table using a keyed upsert (MERGE) operation. ThoughtSpot matches the rows in the request with the existing rows on the key columns of the input table, which are the columns mapped to the linked model. A matched row is updated in place, and a row whose key is not found is inserted. @@ -245,11 +222,11 @@ The `/api/rest/2.0/input-tables/{input_table_identifier}/update` API endpoint wr | `columns` |__Array of strings__. Ordered list of the column names to write. The column names must exactly match the names defined when the input table was created. The list must include every key column and at least one non-key column. Key columns identify a row but are never overwritten, so a payload with only key columns is rejected. | `rows` -|__Array of arrays__. The rows to write. At least one row is required. Each row is an array of string values in the same order as `columns`, with exactly one value per column. Pass all values as strings regardless of the data type of the column. An empty value writes `NULL` to the cell. +|__Array of arrays__. The rows to write. At least one row is required. An empty `rows` array is rejected. Each row is an array of string values in the same order as `columns`, with exactly one value per column. Pass all values as strings regardless of the data type of the column. An empty value writes `NULL` to the cell. |=== === Date value handling -* For `DATE` columns, pass an ISO calendar date (`yyyy-MM-dd`), for example, `2025-01-01`. ThoughtSpot stores the value exactly as written, without time zone conversion. Epoch numbers are also accepted, but they are resolved in the cluster's local time zone, so a UTC-midnight epoch can land on the previous day on clusters west of UTC. Use the ISO format. +* For `DATE` columns, pass an ISO calendar date (`yyyy-MM-dd`), for example, `2025-01-01`. ThoughtSpot stores the value exactly as written, without time zone conversion. Epoch numbers, in seconds or milliseconds, are also accepted, but they are resolved in the cluster's local time zone, so a UTC-midnight epoch can land on the previous day on clusters west of UTC. Use the ISO format. * `DATE_TIME` and `TIME` columns accept epoch numbers only. An ISO value is rejected. * All rows must use the same format for a given column. A calendar-invalid date, such as `2026-02-30`, is rejected. @@ -261,7 +238,7 @@ The `/api/rest/2.0/input-tables/{input_table_identifier}/update` API endpoint wr The API rejects the request if a column name does not match the table schema, the number of values in a row does not match the number of `columns`, a key column is missing, no non-key column is specified, or a value is not compatible with the data type of its column. -=== Example request +=== Request examples [source,cURL] ---- @@ -279,8 +256,8 @@ curl -X POST \ }' ---- -=== Example response -If the API request is successful, the API returns the number of rows written, which is the sum of rows updated and rows inserted. The count is the number reported by the warehouse. If the warehouse completes the load but does not report a count, the API returns a `500` error. +=== API Response +Returns `200 OK` and the number of rows written, which is the sum of rows updated and rows inserted. The count is the number reported by the warehouse. If the warehouse completes the load but does not report a count, the API returns a `500` error. [source,JSON] ---- @@ -289,18 +266,6 @@ If the API request is successful, the API returns the number of rows written, wh } ---- -=== Response codes -[cols="1,3", options="header"] -|=== -| HTTP status code | Description -| **200** | Rows loaded successfully. -| **400** | Malformed request, unknown column name, missing key column, or incompatible data type. -| **401** | Authentication token is missing, expired, or invalid. -| **403** | The caller does not have `MODIFY` permission on the input table. -| **404** | Input table not found. -| **500** | Unexpected server error. -|=== - [#delete-input-table-column] == Deleting an input table column The `/api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` API endpoint deletes a single editable column from an input table. This operation removes the column from the input table metadata in ThoughtSpot and drops the physical column from the CDW. All data stored in the column is permanently deleted. @@ -324,7 +289,7 @@ You can delete only the columns that were added directly to the input table (edi This endpoint does not require a request body. -=== Example request +=== Request examples [source,cURL] ---- @@ -333,16 +298,8 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' ---- -=== Response codes -[cols="1,3", options="header"] -|=== -| HTTP status code | Description -| **204** | The column is deleted and the physical column is dropped from the CDW. -| **400** | The operation failed. For example, the column is a referenced column or is still referenced by an Answer or Liveboard. -| **401** | Authentication token is missing, expired, or invalid. -| **403** | The caller does not have the required privilege or `MODIFY` permission on the input table. -| **500** | Unexpected server error. -|=== +=== API Response +Returns `204 No Content` if the column is deleted and the physical column is dropped from the CDW. [#delete-input-table] == Deleting an input table @@ -365,7 +322,7 @@ Deleting an input table does not delete the linked model. However, any Answers o This endpoint does not require a request body. -=== Example request +=== Request examples [source,cURL] ---- @@ -374,16 +331,8 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' ---- -=== Response codes -[cols="1,3", options="header"] -|=== -| HTTP status code | Description -| **204** | The input table is deleted and the physical table is dropped from the CDW. -| **400** | The operation failed. -| **401** | Authentication token is missing, expired, or invalid. -| **403** | The caller does not have the required privilege or `MODIFY` permission on the input table. -| **500** | Unexpected server error. -|=== +=== API Response +Returns `204 No Content` if the input table is deleted and the physical table is dropped from the CDW. == Additional resources From b1a6d1835e3001ddb366a6340e4258174227a314 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 12 Oct 2026 23:57:42 +0530 Subject: [PATCH 062/169] input table edits --- modules/ROOT/pages/input-table-api.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/input-table-api.adoc b/modules/ROOT/pages/input-table-api.adoc index 7e5d5bcf0..be6d1679a 100644 --- a/modules/ROOT/pages/input-table-api.adoc +++ b/modules/ROOT/pages/input-table-api.adoc @@ -27,7 +27,7 @@ To create an input table and populate it with data: Call `POST /api/rest/2.0/input-tables/create` with the model to link, the model columns to reference as key columns, and the new editable columns. The response returns the `input_table_id` and the ID of each column. . <> (optional) + Call `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` to add more editable columns later. -. <> + +. <> + Call `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` to insert or update rows. . <> or <> (optional) + Call the delete endpoints to remove a column or the entire table when it is no longer required. @@ -210,7 +210,7 @@ Returns `200 OK` and the added columns with their generated GUIDs. Use these GUI ---- [#update-input-table] -== Writing rows to an input table +== Updating an input table The `/api/rest/2.0/input-tables/{input_table_identifier}/update` API endpoint writes rows into an existing input table using a keyed upsert (MERGE) operation. ThoughtSpot matches the rows in the request with the existing rows on the key columns of the input table, which are the columns mapped to the linked model. A matched row is updated in place, and a row whose key is not found is inserted. === Request parameters From 55fc1d9b132f51d0f5e00d3c29331c493bab1db8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 13 Oct 2026 09:53:05 +0530 Subject: [PATCH 063/169] format fix --- modules/ROOT/pages/whats-new.adoc | 126 +++++++++++++++--------------- 1 file changed, 63 insertions(+), 63 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 416bfdc7c..1a484df6a 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -25,93 +25,93 @@ This page lists new features, enhancements, and deprecated functionality introdu == November 2026 - **Release version**: ThoughtSpot Cloud 26.11.0.cl + - *Upgrade notes*: Includes API rate limit enforcement and new REST API endpoints. Review the details in this page and the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + - *Recommended SDK versions*: Visual Embed SDK v1.54.0 or later +**Release version**: ThoughtSpot Cloud 26.11.0.cl + +*Upgrade notes*: Includes API rate limit enforcement and new REST API endpoints. Review the details in this page and the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +*Recommended SDK versions*: Visual Embed SDK v1.54.0 or later - [.cl-table, cols="2,4", frame=none, grid=none] - |=== - a| - [.cl-label] - *Version 26.11.0.cl* +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +*Version 26.11.0.cl* - a| +a| - [discrete] - ==== SpotterX embed support - ThoughtSpot introduces SpotterX, the next-generation Spotter experience, with full embedding support in the Visual Embed SDK. SpotterX provides a redesigned conversational interface with improved chat layout, enhanced branding controls, and new configuration options for embedded applications. +[discrete] +==== SpotterX embed support +ThoughtSpot introduces SpotterX, the next-generation Spotter experience, with full embedding support in the Visual Embed SDK. SpotterX provides a redesigned conversational interface with improved chat layout, enhanced branding controls, and new configuration options for embedded applications. - SpotterX is opt-in. Set `spotterVersion` to `SpotterVersion.SpotterX` in your `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` configuration to enable it. Existing Spotter embeds remain unchanged unless explicitly opted in. +SpotterX is opt-in. Set `spotterVersion` to `SpotterVersion.SpotterX` in your `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` configuration to enable it. Existing Spotter embeds remain unchanged unless explicitly opted in. - For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. +For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. - [discrete] - ==== API rate limit enforcement - The Org-level rate limit of 50 requests per second (RPS) per Org, announced in 26.10.0.cl, is now enforced. Requests exceeding the limit receive `HTTP 429: Too Many Requests`. This applies to all public REST API v2.0 endpoints on instances with Orgs enabled and operates independently of the existing cluster-level limit of 100 RPS per client IP. +[discrete] +==== API rate limit enforcement +The Org-level rate limit of 50 requests per second (RPS) per Org, announced in 26.10.0.cl, is now enforced. Requests exceeding the limit receive `HTTP 429: Too Many Requests`. This applies to all public REST API v2.0 endpoints on instances with Orgs enabled and operates independently of the existing cluster-level limit of 100 RPS per client IP. - For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. +For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_requests[Rate limits for API requests]. - [discrete] - ==== Link Customization APIs - [.version-badge.new]#New# + - Two new REST API v2.0 endpoints allow you to manage the URL templates ThoughtSpot uses when generating shareable links. Use these APIs to redirect links in scheduled emails, Share dialogs, and alerts to your embedding application. +[discrete] +==== Link Customization APIs +[.version-badge.new]#New# + +Two new REST API v2.0 endpoints allow you to manage the URL templates ThoughtSpot uses when generating shareable links. Use these APIs to redirect links in scheduled emails, Share dialogs, and alerts to your embedding application. - * `POST /api/rest/2.0/customization/links/search` - * `POST /api/rest/2.0/customization/links/update` +* `POST /api/rest/2.0/customization/links/search` +* `POST /api/rest/2.0/customization/links/update` - For more information, see xref:link-customization-api.adoc[Link Customization APIs]. +For more information, see xref:link-customization-api.adoc[Link Customization APIs]. - [discrete] - ==== Input Table APIs - [.version-badge.new]#New# + - Five new REST API v2.0 endpoints allow you to create and manage input tables — user-editable tables stored in an external CDW and linked to a ThoughtSpot model. +[discrete] +==== Input Table APIs +[.version-badge.new]#New# + +Five new REST API v2.0 endpoints allow you to create and manage input tables — user-editable tables stored in an external CDW and linked to a ThoughtSpot model. - For more information, see xref:input-table-api.adoc[Input Table APIs]. +For more information, see xref:input-table-api.adoc[Input Table APIs]. - [discrete] - ==== Spotter Usage Data APIs [Beta] - [.version-badge.new]#New# + - Four new REST API v2.0 endpoints allow you to manage Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. Use these APIs to provision limits, monitor consumption, and reset usage. +[discrete] +==== Spotter Usage Data APIs [Beta] +[.version-badge.new]#New# + +Four new REST API v2.0 endpoints allow you to manage Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. Use these APIs to provision limits, monitor consumption, and reset usage. - * `GET /api/rest/2.0/ai/usage-data/user` - * `POST /api/rest/2.0/ai/usage-data/search` - * `POST /api/rest/2.0/ai/usage-data/update` - * `POST /api/rest/2.0/ai/usage-data/delete` +* `GET /api/rest/2.0/ai/usage-data/user` +* `POST /api/rest/2.0/ai/usage-data/search` +* `POST /api/rest/2.0/ai/usage-data/update` +* `POST /api/rest/2.0/ai/usage-data/delete` - For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data APIs]. +For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data APIs]. - [discrete] - ==== Share Analyst API - [.version-badge.new]#New# + - The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. +[discrete] +==== Share Analyst API +[.version-badge.new]#New# + +The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. - [discrete] - ==== Default RBAC enablement for new clusters - Starting with 26.11.0.cl, Role-Based Access Control (RBAC) is enabled by default on all new ThoughtSpot Cloud clusters. Existing clusters are not affected. For more information about RBAC, see xref:rbac.adoc[Role-based access control]. +[discrete] +==== Default RBAC enablement for new clusters +Starting with 26.11.0.cl, Role-Based Access Control (RBAC) is enabled by default on all new ThoughtSpot Cloud clusters. Existing clusters are not affected. For more information about RBAC, see xref:rbac.adoc[Role-based access control]. - [discrete] - ==== New locale support - ThoughtSpot now supports four additional locales for UI localization: +[discrete] +==== New locale support +ThoughtSpot now supports four additional locales for UI localization: - * Turkish (`tr-TR`) - * Polish (`pl-PL`) - * Romanian (`ro-RO`) - * Ukrainian (`uk-UA`) +* Turkish (`tr-TR`) +* Polish (`pl-PL`) +* Romanian (`ro-RO`) +* Ukrainian (`uk-UA`) - For more information, see xref:locale-setting.adoc[Customize locale]. +For more information, see xref:locale-setting.adoc[Customize locale]. - [discrete] - ==== Host-controlled tooltip rendering - The Visual Embed SDK now supports host-controlled tooltip rendering for embedded charts. You can use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. +[discrete] +==== Host-controlled tooltip rendering +The Visual Embed SDK now supports host-controlled tooltip rendering for embedded charts. You can use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. - [discrete] - ==== Programmatic Liveboard filter overrides [Beta] - [.version-badge.new]#Beta# + - You can now programmatically update Liveboard filter values at runtime using URL-based filter overrides, without re-rendering the entire component. +[discrete] +==== Programmatic Liveboard filter overrides [Beta] +[.version-badge.new]#Beta# + +You can now programmatically update Liveboard filter values at runtime using URL-based filter overrides, without re-rendering the entire component. - |=== +|=== - == October 2026 +== October 2026 **Release version**: ThoughtSpot Cloud 26.10.0.cl + *Upgrade notes*: ⚠️ Includes a deprecation and an upcoming change to API rate limits. Refer to feature details in this page and xref:deprecated-features.adoc[Deprecation announcements]. + From 870dfb1b21900e1082adb1ce195bb1947fe520d9 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 13 Oct 2026 09:54:24 +0530 Subject: [PATCH 064/169] version update --- src/configs/doc-configs.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index cb02ca339..690e2e4e9 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.10.0.cl?pageid=whats-new', - linkText: 'Version 26.10.0.cl', + linkHref: '/docs/26.11.0.cl?pageid=whats-new', + linkText: 'Version 26.11.0.cl', openInNewTab: true, }, TYPE_DOC_PREFIX: 'typedoc', @@ -48,10 +48,10 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '26.10.0.cl', + label: '26.11.0.cl', link: ' ', subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', + iframeUrl: 'https://developer-docs-26-11-0-cl.vercel.app/docs/', }, ], CUSTOM_PAGE_ID: { From 2d1b1a9e22e0b83306f829b7f5e80ede0c42e736 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 13 Oct 2026 09:56:52 +0530 Subject: [PATCH 065/169] version drop-down update --- src/configs/doc-configs.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 690e2e4e9..2943987cc 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -50,7 +50,7 @@ module.exports = { { label: '26.11.0.cl', link: ' ', - subLabel: 'Cloud', + subLabel: 'Cloud (Latest)', iframeUrl: 'https://developer-docs-26-11-0-cl.vercel.app/docs/', }, ], From 1a65a96d4b370a740aaf9a1026e4d68abba59816 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 13 Oct 2026 11:06:24 +0530 Subject: [PATCH 066/169] edits --- modules/ROOT/pages/whats-new.adoc | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 1a484df6a..ef3a056b7 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -53,7 +53,6 @@ For more information, see xref:about-rest-apis.adoc#_rate_limits_for_api_request [discrete] ==== Link Customization APIs -[.version-badge.new]#New# + Two new REST API v2.0 endpoints allow you to manage the URL templates ThoughtSpot uses when generating shareable links. Use these APIs to redirect links in scheduled emails, Share dialogs, and alerts to your embedding application. * `POST /api/rest/2.0/customization/links/search` @@ -69,8 +68,7 @@ Five new REST API v2.0 endpoints allow you to create and manage input tables — For more information, see xref:input-table-api.adoc[Input Table APIs]. [discrete] -==== Spotter Usage Data APIs [Beta] -[.version-badge.new]#New# + +==== Spotter Usage Data APIs Four new REST API v2.0 endpoints allow you to manage Spotter usage pools, which control how many Spotter questions a user, user group, or Org can ask. Use these APIs to provision limits, monitor consumption, and reset usage. * `GET /api/rest/2.0/ai/usage-data/user` @@ -82,7 +80,6 @@ For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data AP [discrete] ==== Share Analyst API -[.version-badge.new]#New# + The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. [discrete] @@ -105,8 +102,7 @@ For more information, see xref:locale-setting.adoc[Customize locale]. The Visual Embed SDK now supports host-controlled tooltip rendering for embedded charts. You can use the `onTooltipShow` callback to intercept the default tooltip and render a custom tooltip in your host application. [discrete] -==== Programmatic Liveboard filter overrides [Beta] -[.version-badge.new]#Beta# + +==== Programmatic Liveboard filter overrides You can now programmatically update Liveboard filter values at runtime using URL-based filter overrides, without re-rendering the entire component. |=== From b6c4110bdb4fb462597915ea5115a26940280b6d Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 13 Oct 2026 13:41:19 +0530 Subject: [PATCH 067/169] input table edits --- modules/ROOT/pages/input-table-api.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/input-table-api.adoc b/modules/ROOT/pages/input-table-api.adoc index be6d1679a..e245f26d4 100644 --- a/modules/ROOT/pages/input-table-api.adoc +++ b/modules/ROOT/pages/input-table-api.adoc @@ -73,7 +73,7 @@ __Array of objects__. The new editable columns to create. For each column, speci __Array of objects__. Optional. Locks the referenced date columns to a specific time dimension (grain) at creation. Each entry includes the `column_identifier`, which is the name of the referenced model column exactly as specified in `referenced_columns`, and the `time_dimension`. Supported values for `time_dimension` are `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, and `YEARLY`. If you omit a column, ThoughtSpot applies no bucketing to it. The time dimension applies only to `DATE` and `DATE_TIME` columns. `HOURLY` requires a `DATE_TIME` column. If you specify `HOURLY` for a `DATE` column, it is ignored and the column is not bucketed. Date-part grains, such as day of the week, and grains on `TIME` columns are not supported. Time dimensions apply only to referenced columns. Columns created through `new_columns` are always unbucketed. |=== -=== Request examples +=== Request example [source,cURL] ---- @@ -172,7 +172,7 @@ a|__Object__. Defines the columns to add. Specify the following attribute: __Array of objects__. The new editable columns. For each column, specify the `name`, `data_type`, and `type` (`ATTRIBUTE` or `MEASURE`). Optionally, include `allowed_values`. The column name must not collide with an existing column on the table. For more information about these attributes, see <>. |=== -=== Request examples +=== Request example [source,cURL] ---- @@ -238,7 +238,7 @@ The `/api/rest/2.0/input-tables/{input_table_identifier}/update` API endpoint wr The API rejects the request if a column name does not match the table schema, the number of values in a row does not match the number of `columns`, a key column is missing, no non-key column is specified, or a value is not compatible with the data type of its column. -=== Request examples +=== Request example [source,cURL] ---- @@ -289,7 +289,7 @@ You can delete only the columns that were added directly to the input table (edi This endpoint does not require a request body. -=== Request examples +=== Request example [source,cURL] ---- @@ -322,7 +322,7 @@ Deleting an input table does not delete the linked model. However, any Answers o This endpoint does not require a request body. -=== Request examples +=== Request example [source,cURL] ---- From 63801231926c7d05ce7cd3be64c910d1a9eab706 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 14 Oct 2026 13:32:55 +0530 Subject: [PATCH 068/169] fixed api examples --- modules/ROOT/pages/input-table-api.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/input-table-api.adoc b/modules/ROOT/pages/input-table-api.adoc index e245f26d4..c50e1d9f0 100644 --- a/modules/ROOT/pages/input-table-api.adoc +++ b/modules/ROOT/pages/input-table-api.adoc @@ -185,7 +185,7 @@ curl -X POST \ "column_definition": { "columns": [ { - "name": "forecast_revenue", + "name": "forecast_margin", "data_type": "DOUBLE", "type": "MEASURE" } @@ -202,8 +202,8 @@ Returns `200 OK` and the added columns with their generated GUIDs. Use these GUI { "columns": [ { - "name": "forecast_revenue", - "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" + "name": "forecast_margin", + "id": "6b3a8f21-9c4d-4e77-bf2a-1d5e7c9a0b34" } ] } From c6d8eb2a8dd6a5c34ac8cef6c93b317cfcb973f7 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 14 Oct 2026 13:50:09 +0530 Subject: [PATCH 069/169] version fix --- src/configs/doc-configs.js | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index cb02ca339..2943987cc 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.10.0.cl?pageid=whats-new', - linkText: 'Version 26.10.0.cl', + linkHref: '/docs/26.11.0.cl?pageid=whats-new', + linkText: 'Version 26.11.0.cl', openInNewTab: true, }, TYPE_DOC_PREFIX: 'typedoc', @@ -48,10 +48,10 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '26.10.0.cl', + label: '26.11.0.cl', link: ' ', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', + subLabel: 'Cloud (Latest)', + iframeUrl: 'https://developer-docs-26-11-0-cl.vercel.app/docs/', }, ], CUSTOM_PAGE_ID: { From d241c72424c73efd0eccf5c5f8b665b7ec727fd6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 14 Oct 2026 13:50:36 +0530 Subject: [PATCH 070/169] radiant bg, 404 page and other updates --- modules/ROOT/pages/home.adoc | 14 +- src/assets/fonts/BB-Roller-Mono-Regular.otf | Bin 0 -> 133304 bytes src/assets/styles/radiance-home.css | 142 ++ src/assets/svg/not-found-illustration.svg | 110 + src/components/DevDocTemplate/index.tsx | 5 + src/components/Page404/index.scss | 145 +- src/components/Page404/index.tsx | 71 +- src/index.d.ts | 3 + src/intl/en.json | 11 +- src/utils/radiance.ts | 64 + static/radiance/radiance-renderer.js | 2514 +++++++++++++++++++ 11 files changed, 3044 insertions(+), 35 deletions(-) create mode 100644 src/assets/fonts/BB-Roller-Mono-Regular.otf create mode 100644 src/assets/styles/radiance-home.css create mode 100644 src/assets/svg/not-found-illustration.svg create mode 100644 src/utils/radiance.ts create mode 100644 static/radiance/radiance-renderer.js diff --git a/modules/ROOT/pages/home.adoc b/modules/ROOT/pages/home.adoc index f0f150e82..f6e036d4a 100644 --- a/modules/ROOT/pages/home.adoc +++ b/modules/ROOT/pages/home.adoc @@ -7,17 +7,9 @@ ++++
-
-
-
-
-
-
-
-
-
-
-
+
+

ThoughtSpot Embedded Documentation

diff --git a/src/assets/fonts/BB-Roller-Mono-Regular.otf b/src/assets/fonts/BB-Roller-Mono-Regular.otf new file mode 100644 index 0000000000000000000000000000000000000000..f9d13b23413804f84ce38326148f098ab1878072 GIT binary patch literal 133304 zcmdSC2Y6J~+V{P7n@MKUCzCQ^CX+^j2uzYmAQUAep$efBib6;NiKLlAQxUOaIfx=y zKm-&N1;m1iT?BhW1r;l(h>G2b2Ic$T>)w+D&++-rdEV!Fuj>u`_J8fQ*IwmbYp*u5 zlhTP3OGTJiDl{>;Xy{Py*s!rPgc!3&C__ITR$Mal;~PG`QYfpo2%&s7Y;5U-;q4#C z3uW~+LKLnaHeu3`8J6{BLV53WA^I#YozN%8|MN|Yg@|7xgqT%PSKj#2Q{}if>1QEw zc2rlDS4P=q;gWb8yj*$`>{ow~VFmuK-JZ zd0kca9)&pw-zJ21qOqa5<>Vs*=VLbEx>ty?!ng%4g*j*Ri=i_k2mT^7?I?W2yCWm+ z4C=`Pe{9mP(s3_Ju9B}1>Ufa?a{n(e2FBH#z^}PIdubqQA#{M{Qq;xI_|j;_Y+nB27g~~|6Cvc z-LQXcqnXIp-$DIJurHzZ6?FekYiA!3>?{6RsohXN^;f9P(6dE-@Y#T#f3i)`P1h)X z>Tjr@p>`Y$)AgC8XK)apdnpXHaca|aZ-c%`jzyE8ln#x%9=I#PAW%WTFBPPBIp2Wu zZD13iv5UqxYWKl;6lnng&3ZUIeWg+nPzopxN{_-5G&T!BWiJLHCS=dvfclSMJ}Ga(`+|ANhaVBlM?KsGg`@i@ zZ*+|q1gPA>@&@Cj_7(Iy8}1a|^qHta9Pw~(*G!evrF@W+z?TON)_=0Vf z`m2$E%0+HUpW+(|$o|26Qk=p31lvEAhY02)ST+h5^b6XS<}!4h(kFuPcC|q;ep2!e zmX(y^Av;o;&IR<$kl#6g!uL0!{w3IlQk$de1ogYYFr?Hbg3regxSK#QeX3J(Q=6l3 zWLrv${DRjgFO)}mCh`G=35KOS!tdl4-~c#=a~*mR8U`pHx+mCXD9%AZ1Eax0Kz6ML z)Sl`2Ne2{;%0_iT`JuEa?-ZWmq_WQibRUH+17!2Ad87FN#StV}XQUJdU8g)yx|AmQ z5ftBIKsKXt)3aLz=o;Nie&nXIQ&@^8=ug+~0gr&~U<;MmdZQx#TH=yeq!3MAs zYz5>`_fx#f0HyO^<$>z$U*&=Pi2td){5$sechmZJ!%=Q@bSn6i~dxU&9Ib{hyG9`zZ~|6ZON? zkCXyx*YO}5(6f;W&H@fVeI-HX)MpT6FS?iFBOL~2o6PUxroM#iNqrEx2?`f~#r zbiGTMU_2C-;tSsYclV?q3~@0S4l1w)rSf+5r*kSZ^@Ed4rTNw8;XV$}yRdXT8NeYNM3@>0zh4<)hadKbMXCvfvjI{f1O$Jq za8Mlh>A0W5m_H}Kf`13d%ZK1ma24|8WEH#2vh2nAO@R9CKLDOju^iVz$xRWeWeTN@ z{GDuPr91}HC6%_6`_sC55*E=nVITSj{VKU*jmyCw>|$$(ZG|u}dt45C30O(0a*oJR zawwc(2KEZ|3T$B0p11rNGQ{f@gGK1clj^-E$19U{Rc!ML<#xKL{Hfjx@d_QsI3=Rv zuHJMJ(9tP+n{HKDMUm;&M7kJhx^>|e^`_ep1I5**+aeOhKGPk7G(Iuip$B`D_y%o4YifMy@j>4UU{Y2 z+f>zD)il4VviFc7-ti5!wN*{t(GB$t-my&$-ic-7tLC=WmN#Yh_W67R5W$@u4-zoX{h&dL}Mp-eLi+pH?&kV)X%32z5DeWP**;$s-b00@7kK# zIlc3G=llEi&HMWlQI_hKmd5^l`Yc$mp!aMlT60TlWlaO>w?QSyaJyK8_S}2>y8mdUhF}u6V_0 zoYey_KCEeyI#HA%OchdZMYwYKX5(I;{5Qai!zo4*A`{`3IyXIiB zEJrhJLb>&xlB2O=0(>ZcUGrIukS(G@hM(VYM{m&&{|1OUlxrU1q%d<(x?03M8#e9@ z3-=cJ!Y}&bU!E-Oe_BSa7pl1y)MS6r2mcnxf4z}Lu-2M!wH38OCF0IQLywgXH~NC` zP39AMIz1KAU!y)1{uTwFwTVy>&<{ZI6I4F?yQ6+UU#oA_Z`ThS;l@aPlfF}bK)*@< zMZZ;lTwkx>rJd0J(Eij;>Oxm^Ro8S~H}qTdJM|O#Z+g3ahcN>AaKnz>VV`1ABF+-y z#4MDj61J-s3&k37i?~&+M_avLyewW7Z;AclkiJ7-t>14<)wdW|C`nSee`pw2DVN8g=sy^CBg_ajLbT5fLp`E? zuI*FGluz^x`Z_~3Z2A|5Fs%C1`ZM}%`g4S~;Tc)*sWK*Z1oC^cVCtV~Cn2 z-qn}tpX<-+&#CXL9~hJMHTsMC9wP$vn2S$13(!wv%odZyG(682qJ)==o#J8fgtE%G z)VRjD%DC9L+_>7f#JJK}ZY&eJeJKWmVwl1T`-j33OT@iOwz34ayh>T2tW;JjYn3~c zyOsNukCiW#ld4x;jyvs?Jbns^w~hTBX*g^V9~lNo`dZs+Xu&sn@A1 z)ivr`b)Wj7rfXqZjFzOOX<1q?EnDlSU9K(HuF+O#cW67b*Yq$wQg`Yuy^o%!_t#7H z8Tw4ULT}Y?KwH{~R<#SZcvgQ!|ILUt+(u@^neKTW!xQOocrrYFJbgW9dWLyMdnR}) zJm+~X^W5NB=lRWR^Tv8zUXM4`+uiH)_V*Th$9ZRY8@-FXS9v#iH)9ys=6%5XkoOVq z6Df|A_!MtSYD)K%-YFAPrlp*da&yX^DVtLsNZFIJH&sowq(-L3q`Fc)sXbGNr_M^P z%GjRqa>nZ!Uvxj(!{HN~uWeWVJbCgYEFOyX>_eN~rud~5uQRQ9JFK`}c~$vB`CUy= zyQ?{{ViBx37FH}%r>p0fR;-2<>$_O-8q8w z(mlOB`JREEV$Vp=SkG)vt!JrcC9JsKt9l*Y1aCL57gp@!Es$262`jdEm%@s7!HQeG zJ3Fix*I~u6DU(vBr>u}x++kYLfEA;=Sg|r=TgFSK6=S3o6|$nS0(LZiPKN!t4jwhu3y(5LH_>!=QEo1;OEG8c|=~0 zTy=;aBYln(B1Hcqy$^qKqzA%eAI3cJ@MVWDJ$%98 z+Qah>qrd*_H}L&uUwrodXODb_Z$f;$3N(H^{i9j<%Edv72|swGl_BWGPN=b(EQNLt zU(mL|n)hhiw70akwU4x;+K)IV@a+xlSB63c{rN7OA2aVisvXmQ)=mWdP2b;1H5|1Q zXn$k%IeIllkw$$Dj_c8TeWZV)f2JSRkLzvv@8}C7&;nzPIOANS)~Kg@jYgx%SZFLZ zE-;p$2fZA<)kYjEz>4%^X=3H0rP?B6l2?$r={sAV z&k3H(vs&B>fu7X>-G4A97-t!m8Kc!B`qLP3#$Y5E zhp{PJ&w;J&#wdM_af$9zKgS4kseZA3nZ5y|kcv^oCCA7ljFJN}I^<%6nP!eKS(trX zE=QSF;u1X|ZV*q%v1S*(_j9xIGse<^7+EG`Je`QKZWcz zc|lyKd_d!~xJ@}G)+yhJwaVAx4&}Jmr2HT@D&LC@%6Aw?+r(BSAns9q6)&lAVz25D z52^yYE>7{h8YA|pvEp?#2|F#R;$5ssdy0?MUg9J5bo54B&>vkOu2kL;PpM(z1re$g ziHXV@alZ1Rct};mZq#jmie)LFG}5P9C)f<_pWr z*}`%>i&q-6jY?y#G0&(oYK(GY7M|C0jX6fOajkKk_Ja1R_L}yC_Kfzd_MEmydtTeC z?bBY@-p~SCoA#Ub9eRv+wFBBg?LF;%?E~$Q_96P7kF`&R0M9 z^;`A0`l}jH+tlCG-_>^Yg!+g2Cq_&~(=-+H4?_#lLN%)vp*gfzZJ0J(8=;NVMr&iV z$=VdHOq;4r)23@Pw6nEyv{_oYR-w(-Dzz%DTC36KYV}&P)}obat=cH9POH@#v_|bb z?Obi1)}&3+W@>Y^IBmWbuPx9Lw1w(7+F4qnwn%eni!tXpU+bn_pt-dRwPfug&8scd zQnZV;RBah%Lzigj7{fEP%d||)jIPvrXjf@hXs2Or)Kj|}WBfIkEnTbi#t7d>`-kSk zd?_1aeU7$L%hhhs{MwC}1FX{WwVSlQ+G@gu(k^x=C&YcqZ{khWja^BXcthN<_Fa46FO$B2pP4!jz#{3Y>xU#$aJp3Pp%AL>S7MVt}$h3{n<}BIRP?R~kjW z(j@vS&7z;uBJz~;#B}UzOjXv3%apgo70TOUiSn{os=O*LR$dd!l-I>Y$}8e3>=azB z92D0m?}=-b_r-GMfOuRD5l^ai@w6H)o>e2obJ#)HqehEo)Ch4<%@7B$HhNF(E_65_5B^Q?>(63Pu6eN-!>xj*YrdB5zN4k>fh;K>K_?pMyY;{ ze!ad@U#4GTbT_<4s*!GF89j_lBgIHFG7QbI8ln2Hv<@(a7=w*S{bzhShuORSq1@pT z8MM!ZAI*sa%@%+`^BgZD*J7C42%xWprZW0QXd0u_&QCg{ABJWy2JM4&XAI1VL?(kB zL?N;O<{0`;=xL086SOCz{{lUo(Qk$JV)VzMm}3$8dT1X;zYFRE1vCqQ_Gk24paU5F zPUt{Jr!a#U9djCi?}QRM?W>*1=yyN|GgvLsOpQ^XLrmPzA`>sP*o4YWvpa(FI~34N zi>?nhISWeh65{~bh?oUNnaqY#IHD4aHmQYSD|HKDtHS_GdTpE&geU!GZ=j}^lV0_IL~1Wx_>64Z-LHY zj4Pn!j6!uqWd;hRQ^6<{AC(^{uu`~zCUC^teW98m6r&SR8& zpkzm&+y|{=lwDA=DNr7RHZaQb&_+i29C{wWEKoTLZDy2jp_nBS3bo-@M)?CuGe@At zLl-b=B9!WE5&UTlu$WO#gPzam+n^UP2G!+-jJ_SZgpoT6>){4i#S1}g7wGGt8yNjl z=tf4Td~Ra&&!A)%p#K1+X9*b8UN$oZwLhveU|a^Jb_0yjP_iRXk3hFF`qR*R8AF9q z8GtbcO8ExHRZwa-z!(RmwgU8%(4F7`xU-=TGR9KqLyTdEKFk=Spj2mo=KSIj#<&Ff zD5LwJRF^>g9J-s)pMgHk=$AsDVDyWjPck}{_bCQ*Qz4!$r4w~EmrS?aVE#Ehx`uqSK0#t7w znot@ancNKhm{ER)e!?i!WJr2HuoAUoXqf|nFU=*tV9~p&g{1c;4 z{Zl!CLUsEKqfq&NWfZD6vMhA}kPP{K`SLL(TOHz<)NRZu)v1kD|kXp_0n7>34m#bL4-8q3gpL2;VY zLaF?K<_-##jhGJ-7@8L-i6-YmT?}^Vg@R{TQU~qE&^WKSO_oDF49x|UWRokQUWUeg zg=|M$1E~Cf<_8MZ6LB>lI|3U26|x<1J?PHR96`x6Spm&rXzW$UcEl!d8bjl@LbfB; zgVPzBD=588RzrI;G`1^!Ozwb^9RbY|6tV?@zC!UcG`1^wCYz!842|tdU(gS11qBR^ z?F!Wau?-Ah;PBB8J9! z>Qf}Up(TtQKM>G1A8ybuh43S#zw3qCD`u}G%u8M!@W?dZ=g~iP|MJq0{b-*713gMLPFy$ z_4@?&N(9z}5*oL$7L;KBL|~05p>bPjX0WFsux6CdxJzROfqfS4N9H4;ci>*YsHxC} z42`Q;gGy*@#NLub?Fl`fp|Mf9fKlnWypW;sQ(3~Or$aAi#7gK@46VJe6CCt+7hLUSmr z?IqY*;%6AoG0k_do|e%16YFY*o=dVLp!Eukg_1SUHyN5EV_nWr-R);+o`|)&L{*@a zCqVN)tkosh#}ZhlOK8rB^}9sXq3|QA0|_we=_1m=t+}Lk>1=JB+y zAg~K3us0&1`8Tyi*&dN5_DdwR)>PdLwGp*DBVwRvHw5)tY8Hb}m4(`aq34FyDulQc ziuNkoEb2$4aDe83YOV>z*OyW5f})NIkqj+nXx^`uFf_MSDQzHbhmK{a4^zj1@yHwb zp?wf!Yqg9~E`q{dgmMXVI+y|X1yHnUf}R_7CPQsjEoYQ#p%sjB1+4QJ#agGRi*aLWbIhN_hp!QYhL7LG`R&V?y;z`6E1l z>Wt_CRx%3J#TthCY;`T8Y=Q1&3<^VO0|V_=J;)drL*HYJ%b`?%z_=QU_D>kgp@$fQ z@`bif7*`6Rp{fXDHWbeuVN^m@#+VC50K$OHG@UW(pcck}T{SCXpiZ<9#+U^SWsF9s zjWN!J+8JXGG>kD&S6U2XoCihwCk)hsmc|&((C#1${w>hcK`*!$K(iTR5i}3ygZlxciM~yH$>e+J%O*cTDIdfyfbv272wpS!75zTyick?hzSkwu zoKVyip?(cTeGytX)L_Wox&?&5KN5;M(rs`99rZ#`J?In;sK|pJ!Ki54I^6@P{`Dx} zK$tI~u>k3--$LVn3vQH4M;+>@Kb7*F4l-~r+MJGhB&coanGCf%9d)bsfIsE^G|&@n zKEZ_o!}kPq5B&~xD)2K9qHxJN_tL4UZ%LI;2%xFY-ymDcsG_ag2s@eLSPJLMJd9;?gHF zS{-x}qt!wwe`ScL0g8T6p9c52(CLhZ=R!w+L1=Uz`ba`UAE}#YbKs^j04)wmWdquL zDBTaVcqru+Xn2nF7Dh{eQeJ_!5W0dH$PFY50w)UWC9 zGSpYn=LCdyE%YFx(KGZOL;aurKBM)4e!x(ls2^f99~5H4WG-@xOFp>9T74@FxfG!GQ*kIRq3q@TL_}o!=U|&Mag~Fx;tyer} zFrp5M@)7uaQh16P(F`qNl&7IX8Tt&sGmOFKn8GuXq0bFGqZoX)DLiK}0&UDQno-bx zJ!2VxHt!k7(7M7io)Igc6Bt^1cxE%SckiiS@L8$w)G}f_l*#~To#Clx1eLLYp*4r6 zkrDSnDX&05JMt`LX#d!AF+=MH&oV~52EBx#HHYU?M!W&NjG;A$hw281PoOt2D%I6G zhCXxftY?G+dIzJBZ8k9Y4!Q7bWN5#{vx%Ya#(VB$X#d7TwgB|KeGkP8lwr^<41IUs zb2p<5hu*`8Na$8Z83DbQ5n)iW3s9(@w=qJ8l6`?f?S*U#gavv(qYQ@bWP}y^07Lsy zo(CCvx4`odqYQyQ%m@Rzi=n+O54Ar)pKW>`Wt0Wb#~Au-)3cjV7C|3pL=p4}Mxi>S z_6P9&VBvX+p*;`J(~O{JsNBc?)MW@zuh^9my_gTBhpy5B=>4u~tDuQRmn_fVSy^!b>F z+AF~4_QFH=0I?LhpP{`658VR<+2kFD_8~m)GJ@Lp0fzP?JO>$Z5%fJqp*+6Nh^wF< zFtp#`ImF;i2I2XTq5THWM~t`z`Y}U$51vmLaV_*yhV~&mpD|)N^e{tv7@i{xeU|0< zoKdMQeZkOYS)MN$)eb$%h^L`nF={yU7(<_BdA?@UNa#0=pgRASQKO*88TyRN^Bto` zL%(O}voX&Pj2Z#`k)h9vJU=mN2J~l!K2!4i!l>!cUm5y5$rE7I?$9=dK2!4i#;93B zcvXhxI9`pRxsO+8Xx`y97@F^REey?Nym%%FniF|pJA&pr-cW|-FJ2o%^CPc=p?R4% zmZABYHvzbC?>;E{JFgq==b;`(hpoI`kb<#u5;T>ed8-#?BlO##eHfa5d3}rl8+r>s ze}q9Dd5al+DRdm8Z-&lfbhKgbEQaP;-bRMjHr^Jn2=U}X>3+0XTAO({F*Nt_-USdJ z&3(LgGcd2+290NoQmB_Pra@st!WavM{RqPX?adfdpmYuB*Fa&bl<{z151jyzj=l_v z`ba^1`sL8+;2gN|45qALXzr6j_W*;^U&$Dh{tXPxnNn^9s}KflGUX%v=M^l$S{S3 z)*qWuXM`Awk3$szyU-ripC=itF_d3Fl?Y?H+&VzulMm6}=0E=^wD+MXitBIRf1<0I zZIPmzWuVf{GDvMp&}X0czMFp4?|Y4I6OtmkmAxOm(=C*YD`NCrs!%ZgM_>-qO{8Hq zn~hQPOfgi9785ZZ&K5PIQ7pj7btOI}x(T1mY!r9n^NJ_&8N|z&dmY5*0H5P?=^w>! z3O;95A{3{RtaMj;;XD5W@V)C1_+I4{(o2dd({Wj$JA%kz3Qv#+v*4EXZQx>uj(K8mLt9wiEkRF;~RuNeEY8m-*Fs=?=)89 z`-=1N{lkm#-NNheeZkxCw!l5w{n{?=NqkrH6>UGhmH8>YefcfEr`e7-bwcqSZnvJU z_muAu4AP7AG5RFDOHipd==1dp^h@;R_|DsE{SJMLejnb=cm{7~9KiRCzr|ZBnh}FH zG_s6b;|ybjF&W<#tu+?lo21tmtBnoDR^w6QIpam+ZR0)Tu<@ zWt3&IrQ9;lGT(BMWw~XQWxZvqxmF8#1;}Ak`R&{(mkYCh(BaN$dHf`A!9?Pgq#yn6;d109I`m%;*hIDR)*XhvOZ*U z$bBIXgghDYLda_&?}U61@>$4NA>W1k5^^F`3$=wthbDw3hxQ2dh4u|SBeW#+tk4Oe z(?ZKbt3w+?=Z9VxdTHp@q1T754&4yCE%cGlr$YCJz7+aS=%LWhLca?AJ~R;er_HcM z*qpX*wlv#mwrtx#Taj&~ZLDpEt=d*^Yq6bgyTW$0ZKdsI+j`q(+cw*Swx?{*+g`C9 zw0&&*!uFNzdt1Qvhh4YZ?J@R5yVss+?`_Ys540EBhucf-lkI2QEA8jm7uqkfUv9tF zzQ%sL{Vw~x_MP@8?R)I6*bmqb+mG3g+kdvVhpAzqVNqf6VV!-j>8 z37Zr)Bdk2EI;{!_MVS%te z!;SE;@R;y!;c4Mn;W^<0!-s{B4?jD+I=nf2N%*zlYr;2%Zwr4kd{6kB;fKP%4F56w zM1(aWDk3qWXGDHPVZ_LYvWVFcbrH=GOCm0bxHe*S#9a{&N9>7sG2)$wk0ZW{_&HLG zjEYQ(%!tn9_eMS#xhL}V$oC_UM1B?dQ{*2} zAyM&BsZqV6`b8B*jft8bH7Dx4sPm&PkNQW{Em3zy?TFePwKwWO)MruOMg^iR(NWP! z(cb8u(RtB@(PN`$MV}kp8ofCB%IKBRw?%J`emMHM=+~m(i#`(lUG(oUMoeUkD<&NeoNJw%oLikcosT-7cJ6b&=6uI_ z$a&a#%=v?}&3Q7;5*Hp98 z$K4cnN8G(}yW*aWdo}LuxDVn!i~B0>`?x^dpYcX~SiB?N6`vBH72hX5KYmbrar~(G z@$pmRXT{Hrua9qyzaajS_~r4}$FGUMJ^rrv`{Eyr-yQ#K{EP8##2<+NDE{;KZ{mN7 z|2;uT2uX-ch)ZxMq$l)D$Vn(j7@ROHVNAlLgc%7H3Fju9m#{G5qJ+y6u1&Zx;nsu= z33n&#NZ6I|WWw_auO#eGct7FOgrf=HCH$K3N1~o+PmD=SO!OvZCiYIuOB|S3lsGbR zQetIdL*nAZ%Mw>4-kNw<;{Az_C+kHqFk}AL|3va z#g*pDaGmbz?aFrLy9!*zu2HTru5qr3uIa8S*Lki*u4S(4T(`LHa_w+E<$A&Omg^JO z*RJ*?kz^!=CPgGUlM<7F1=A-6FfibxZD+*{yfCzTM93c2>8tZk64d zx?R-mnr^pryQ|v+-Ja?8X1BxLes=5bICrMIzk7&#gnO)es=M4><8E{>axZf)cdv49 zaBp)z>fY;q%l(P_m^QF$)_jhC!d)-Jb7$#S@P`UdC4uw7bIVvydwGL0y(d%bDRC(&DScA< zr;JLOoKl`ro3bEfS;{|BZco{k@?^@3DQ~14Nckw`^OSE=eoFa0RY?uOduVZ~8L9r% zLcGm4J#|iMW9mhzD^k~`-k17B>T9WoQom09HBCtiOY@{1?fxDuSmZxeO3DU^v&rz(jQCTm;P4zq4clPe@Xu{ zBQnFC(KBN}#>kAR8FMn4GZtrDoN;x=%8XkxHe_tg*qO0AV-Mavd@JLCuUr*+TnerESk-OIXHc5mvwr2F#jH+A38{qF7$b>H3n`R=cD-{1ZH?q78O zAyZ^pGb1vcncXteGJ9m^XBKCkl{qc5JhM9Uyvz$SFUwq!xjJ)Q=AD`MWH7aX-*3_)ZtcI+Xtc$ajXRXRwpS3mX z;jCw}UdcL;^;y=pSwCl;?2+ALOyTUNs`*u|^)=Zgg(XskZ*xII_Z=!n*Q`riS{$hPe&(Rr3m)YU<~fSG2ZN6_!Ym zG5BO!IsV)t=~q-yjysAfYMLrq>*mx}Ei9^RXeqC#sH$&~DfKHTmLZA}aXEQqm-ski zzLFAIx)OPv^TU}O!bL6O+!b-|inypn{*tZ21KD(r--w4jM#%Dwk++TM5?+S&b9Vfc_v{jXeo6gYxO~|K#ihYEhh~z^eq5wtHe4|q zyqN2wm?J1Q>x!xt?aC}`NojRMQ@u=~n7vBOySNF+W|&=4;w!CgMN?~Pt*b3>Z7J(d3=^Xsl!YqY}^vlS{!{z$)v9KnZ)*))TIFp$(}?H>m=EVDDE78-V|B#DV-&j zi4FBlsjR8OFYKsko-((oe16r`zXtG6mHr%>s@0d1%cdFHZ<>sA+NmwOAg8c*d2LIf zye3`J3gnWJ6qa;2hvauUeVxvnPN&~=Qg24i!p`h<1S$*$qE4>Uw=?d-ex1IYw_uq~ zf9m>zPIQKyp=G8Dr2)v(><~Mz%bc41qYOZ1?{IWlKvsnGmyw$tD0!61Lq|w{+Q^SA zjVDfC{uhNV?zC5NXYqjxv9Knd&&YGF~1!%*fBb z^y~6m(>a+H{ebDrE-By&>D^M(QaeN*i{!Cb9!unLs5}mn$KmogLLNuT<0yGNOCCqd z;~04?mB+F2I8GkN%i~0OoFI>rgQm6IoX`kcI+a;~d#?p(?{ zrU3HRJYRX0G&#;Nj>`<>6!fc*eigE>tmtgI6&>9~Ww0B~F3HZV>@pMJ-1>%A$s$(; zgCUdDU!sg${vytD5ofuG%U_gN)sX-PHt!iy#bv1K>>zXUqzQ8Jcznv^{yL93TVGB; z)1Ewj7fZ=0pf1mslPCM_oc!FmGKX_z4(E23ac-B^Hn(ebd^!1S((K}D3?$W^x5&Ka zIW z@`u*TSnA8^k54o;G*(yDcSh(RQr{&)8JVAp>+f5|Q;(d!Z1TQ&4P8vbBafVjpfBPY zF6Ig|hfg`eVq(Qb%`we3w4q~64Gy~IT@(&cv6V}*8@djy4IL)VF3IEY!6(Dt(AhO{ z{yD+E{hDOCn`B{|x|Fh6`Zt?XkLJ#*Y3>q8MwOr2f;Q3;G#4ftoOWMs@cEolHWw|Q z?cJ}SwTqejhzAWxwu5Xr*TR`>?AhkjtVEi-*sQdYzO5bhDPgM)<-|%jl@c~n$IEVD@bjm?iraUCK(>Kp_QlCoB z^3Gg#1S$*$La!?4Co-18&bSK;I>Qc;u>>t(`cpp~bfPcr3@tNNe(Hc+D6=QaNCD^3 zftXv>REH;bc5QRe$LzQ1)a<*ZGdMlz?8v2e*I^Z%oE(J9*?`=^Qz$vF;eJn^%I3+g zj@2HYb}p0Tc}E@5Sq&ZFQ(M*CEZsF7mBn2kU8kx>Hz>oOYW14Gm@m5|N1CsrSCsdh zYPBM1c(c1SqellJYsTz0gNf$k%ej;^EccOgrIrp|J4@-=k#FuO%_yj|l$TLPsa+oK z&LF{hM&~IrSKBe;X`nz29dUEtXWj^#$f;7psWy>qj%SMO>}+$zo$a}}v#A!#oiGc zPb-6WZLL_V%A{n&mpRXqx!}&0f(JWXcAwHxyLP;MnKm!TC1c9x^3eII4_IqQ^>CkS z-ht}jIrm?x=b!A{FIYjiBRF@5GdQz`vvYo060A1(@*3sTIw|3%M7?)M#!G_nqxbCW z+e*6BRA=>+aPQN#SC{d0sT1zqrEjqR;9j1*7Rf`0LArG1@&+1Phsq)>>S_k=-#bHe zJ`cIUMnrvmX8>8E#dOXczjSrraeEuBHgj|T=j5CqLsmqB! zk~QPx^yGdLLUJa2oIxM$kszd5A}(JJ=gh}(`nX^|j@rk!=a_ln6nvadxx3@@^AyzI zmm}jffWLqvE8tiPIN3sZU!GZ_LerD8E4ONW{vm9TA)JETxP_+-nP(PS?rr+~a$y7E z4DxcoFE`kHe!0O0;Y{!h&(AYFKX2puOE@99x90Qn=90gJZ;%^G@Z=1Za0W}*1Vj10 zp`5{?TE-%wfFJZ@ll!Frb?G`ED{vx;izn9uk-HYt$d;3A)jU_PZje=aAP%Z)_t zE5VZ+iJWlz`~~JU&Q2~@FVDjLa)%Q)aJ}YojpTBB$mJsP63?H@w#?-M=W?^i<#O|i z#qa05_&Gg4TfuMUg+t2iQJ-HfRUn+KpDpC))OnWe_j4xlxK;T%S-HuI`#3MWmh|VD z`7{g0#mwV4^Ed@wnEH9q>i3&@;i%<~sLwA~2xzdJ-M$=I0iP9cECrmU0#2P5`g!KF z$6Eq^xn1D%%WVdIWN5N>6c43 zcycCqaqZ`w2!9EuSHiiL3ly|ePF5~TU^=cixhTOkHi2B5`22Fg0^!?-a%JDR1xV-WJ^b~fz1j-l9}*TuJE=g^unYGOE0>vHYy^ zy4jWGqg%(cmerKj)zF7FV{67&H%zFRTUS1@yj4D;JVTts(G*qJjK%-v8X0?GflRUm zzkj*eOo!bqZZn~d0KxISw61FIDWQWGWExaH&TdCZWejv?#@NN#ajBe4 zGMCIT8wIbd!m_4{OR^Z}_+LX=B%{nDgVaic)XReB4k>D2n=GtptZAxlkVP)aX(r>e zz&IRFMRiRh{^M6lQ~qUiWDar!3((aqb7tP!)g26LUJ9PdAZ9j9chE|*XwuIt5xY%` zoA;1Sy53IbEeqsgp`{u-H*`Lyp|y#$xn?0r75$oSas;Oci>sO%de_v?scNceKntnr za8pDzWYd?9{}_=adA=qif7` zerkl|b4q&TaY{LR%f*BAYG|HArG`*GNTlW9kg1YV389oIi7X==oG2VJEvOj*rPdJ% zodhEyw;2gJJMO2GU>xKQ=BrCCJM-Jz+SpN5K{qAb;g;DCp2?&;PN*Qk6Us=3TNWvJ z#`y}K$&3Y0x+X+9)?5$U~ODBht>I({4P~6)ELJsw^(K zWXjS(#UuwMEmaneT%0($WTNDdiB;A&)KSc&6th$rGr45U(m^qkgJPB{V9&<(2uhi*87t7kZat8+Nz>KqBMktqJZ+KhUSE+&+{N0)O>GPoW`j5JY!(2Ng4 z^A!k9{2(;zfzX^1LbDeLO;8~;VT90Z36j&%th;m~)O7gN4Agnz%gdJCN+o?K1E2g> z_O2*zuA1G7Khw}6ofQpu^rWk5AwCMIt87@nr{}d+HIw~2JZ7Ups%op|@O|=3{sjn* z5f|rG;X&+j8Rwk=8q1sTfkW`JJnOtzRac1*_Bj{z9nR`S^f7|;o!g2J@T=-*BhgHt z!>2PA@@mGWG(vU>Bz-yqk%fG6qMqZEi)4s=RD5#1h%;F=KDofm@yX9);3=!dCs&ra z_)8Xu1tDY&`Q(ZeL1fMP^2u{($xxcC=JUILoVSsGnQX+C-BQoN~H_#kDm} zH1Est73MeMk7;0*A}`bI7oj+5xvWG8**Fkyu*nx>=hip0(1TEm&veSEj>%0MuF`?| zQB%W0>8z@2Y*~cpF+O7>p=D7GS_HP2YAKm)xhBoY@#Q0UWot!Cb1PEh1qbQk$M+<9_Qh^*&JFWL;Pt!ikjs^>n2qRcBSscl${5BjS3Og(IqD;}a2jCYq||)--cZhckSzCgYmj z)G!ZOGS83=UoP(p<@)-{9aiky&t`A*3O>Kw;q3IwCO^I`m$JFMag@vZW4XNHlV}4S<+B^+S9PSx+j+U!L-5JM?5f&^1szv-_b8Xw zOosH&{2 z!nS&SWmQwfA~r%k<+;--yF*w3zH;TwPPsCNr8>is(42^1Eu_-IJ+!)1+LzQQfTGuRf$c zgWs|pi+4zR;CD|KXchRK)$~^;uEp=1-i*J}ak`#^H$X1MU*@<4zuEsq{9gYf`cb14 zzhS=4xZAkj*k^og{9ptuh9$u=+R|dV&GL}tam(*khc&_Kv8Guk$Tv3TSyx$aweGU+ z#`_t2@P5Xd*7vO6g;+zng`|b_z#AF9kbWVP<$D+_L+%NADCFsomqHGNd>J|nZ&#Ft zULLwO^i7-3HVtn`Y_&aMd&Bk)-h0Tl_p{gApTqkMfw0K1*s!E9FWz9N4yz4o30oNU zR@g^j--Z1V9ul4uUK&0vydu0Vd~x`7;jf3kAKn&WkBE+li%5z%BVts<*%6fy)p+;d zhKQRZ?!dbT&qcfx@mj=N5x+#VN1TkbE~8qD!MEM3+UM9eqXgis+l8?~J}bdUy0w z(I3Ppc;~>0Hx5pV=@T<3rYL53%($4jF|~N>U`fnnF;~Z2kM|DN$83(d5APoAig`cg za7k>3r7t zp7Rsu5$9LVpW|$C5qNLF9oIdsC*B*#i|Zd(7&kg@eB9)?d2x&5{t>q^Zfo4mxF_TG z#k~>tPTYrhU*OBQZ{mK83&gAOG4XMDTi~>KUwlD)N&L9@viP&(tK#e8o8uS9FO9zp z?+I*(-x7a+{3G#C#y=PTQv93o@5X-+e=Ppz_!9{#-V%sNa3mxqB;!4S9tpV#gA#@( zOh}l5w*<=Zj=;qU*C*VOa8JU+3A+=XN!XY0YQmcd2NFI`_%h+^gzppD@OFTjXiW@H zbm08}PhwhPPGVu=u*5NmlM|;Vo|8Byu?24kEKR&F@ix36aBt$HiO(m#l=x=ify7S| zze@Zr@n^gvU~z@HqFr%#H=ws`fNQvGl53i4maEz|&(-K!;JUzdiEFv*de<7)I@d8fZ0iP zNv%m2B`wGM0IQQWB;Awr5Z(!RKIx@Ex%;TQpWAa{hJKc1#+>^feRRkDk0l4rEVb0T z?E#nVnVq|yywNkm+Uu<|zgXs(W^HrY%5JFK^^EH=>yyiN&Ya}3pKjZ)=egUDS%K4{ByzZy9B!**Ny9OvEEz)73czIg4XOV=ko_sFBqCa)=7Vr^Zxu(fsR zt?L$e?5`IYUs~G30^!C0i@lF~yTv}YhuiMVcH1o(Hv5^jz+jv4u4P9c->_%73*Gj2 zEm=0Z^P9SkTs|dXA zo;z>tT?;%lB}V<$hZjATG{$}3C7aLR3=@oQn-J*ZZnwYawzsXcwhy0y8ug8J+t0G? zw%9kUTf1Syng!?I=CSYFy?dYML0CNSo%;&QlEqhDacS~(D*{TuYn*B6=QV08E-0Jq znqnRO#MBo(cUWG0;)xfNOP_L1vDUY=)O%Vj^(`B=BtK={vSGs(T;8&wr9L@gip^v9 zWFpQQOJG)@(b#{&QWV%^Z7*+cG>QTV)_uES+j(d+?K6r3XIqYcaOimQ*1(UpERVg- zyTAQlU`arC<8W~Q39rTO%(LXQ3*%F`+J@P#a9?S8vUdEokqd10O&f2#WnJ=kYkf1a zGT(CE{IwgdNFH~-F?IE>>Zg;|2NG?8sn!?Eo*eC&A2{ybSLS@ux@F_WEuQt3EgPHb zlgn^pGu>FT0Md z2H8eVoHce)@*DGwyKmgQerr--yDhnIk#)eRQ3H}MvJQNCLO`ehBR^O7p&ZG9m5V{5>t2X3ur&druP*Dq{d zk=&lxo@fLj+0dKYpT#ZbwXWTCMRFi9kYKb&a%Dw0tK3IWsrL5#wjF_9`%gp^1$v#> zVQ=4hVuG^<9Y|oH)xO$NXbbckX6t#PEO4zm(9c?KTYVzR5||he&Y|v$+M-s&f_OS3 zo`uO#pVizZTP)3J2$!MCirn^`B{usa>un30Ry8C^d*R_HgKgfl>b7;BMf=xU7q8oN z@#cSRwDxpqCm1krsns+e?kCH60<~?iPFWG{=`im_?g(^!_DySV+j5`l2J4Gcp9q}q zo;o`D5^K$^jd#xX*aJ)4r&x>{WcySn8mMfNn`M)1OLxn*+<+#D$7;t@&V9#9EfKd* zOIl>f>TfT!-EJGvelP=_Mj$;f$61%}zS|n%9Jbz=eo=XKS<=|)yZ0uy-PGPx6gcg~ z7;DxC1CD?6=AMJMd+gNHWZ6rnO&{yA!;IT4D{aYdtT*1Y*^2^6?MYVZ{5;bwL)`GU zI|tqV=J=13wp+fV2lG|yS3}3ZCVVqQF*byRUtUQS=@^$^oA{!ucz@ zsCO+d1>ShM{SD(C%dc%KjY7-d6Vc-Xj~Rn3btx2^{Qt?stAKsqH9SztXIEKiafypQ4O>MUr%dS|uXkk)b(Z`nO?tNgxs^q{8 zzbP`8*j!1?14!}`y{J9Fwqte?cY1cPM=olnQJMX{`lUn+;FvJ+w3{=K@1$T+HZ14 zoLGg12mACMd}g0>ZmZZ*m+bg`JtecAl6jhvc^b)hZJ$}%X9e~I#sp>?JuU66?bjNx z>A*lQxBZwc=4fD#+i|EZuWhB%@y&3XDBrmJhUGV)>ddB^=eED_B*vl-+#@XLJWHpelMWmU1l)Gxx%m%NjdTTW z!j&m6U=+%?RGwwr+*Ef%?cMI#H_zEn=NaCv7@t^n>@zO7^X^Nwwq@ELyl`jp-JbTH z?e{p*^Uwpb_SP#dy(PJQO#2?=iq%)Hx!Dz15g6#Kv@Kfnj~gyX4wMF-H&$G9-Gvvp zB9;a6Z1%~vh`@#Jw%GkK0kQwu# z`_Tg!>>pbEXi{L8`&##=%Qq}r?`iLU;?^;?Wr1gGfsp+p_B*~0eDjiXdSIXX-oUlC zANKdOIF62;HqN~sXAfDP3PiY*-?-g)Z$a_%eUr*9fwOJ%t)*KhKUVK?d|y^yGjX)* zTx;f`0mnVNEg!!X7-6HFPDzRgU>w`Bzio&+4&xb~f-1_4{NkrpLZ7wA6_tHW5xF7WXJav&F9UW=IZmY-yt3cX_(mM!+tK#8H4xf<#CXpV2*u!j z;_>~z4en`ePdH(3PiV8_F^C9OX!+XzkFoE7i{e`Qp50}4byiUsS0iM=mKZe}JC>kC z#2S0=7&UgWqp=|t>>}6@QS7LQy`VHJQL&C13)a{*Sc0Be&tks+GqYIo-uu4a@8-(R zDbMN8dHU(0E$C=%L4E$mg07#no)+|KV|yPQwuCK{#;oz-)1A0fSB=57*WEH?c=Xy3 zA2v<>%It1$ncVGEMr!h@KSl4%Vl*?K&y=@~NAOklPC;r}k^UdA0P&O&yY&vS)sXpP+@CBM*9h|#>#w#0FUyTp6D&ysy?=j8hi z|3770cOve8?lYj@XrJ9eMPeEO~5H{i6_jm$GQZ#F;kqYq!k zhk{Vqwg;E*?zrIIn|ykY7#G~ni!CeGcig6fBYX~Sirch@=pnk3ecbIYMHazNV(vlV zi{h!&l+!+Ith*;{8MfNnrkGwnv9rk{vsh}0Hml_9DdLbG5N-2V6Vb#HAIP}xN7)0$ zinvp=~Wva<9KzeVrMmFwRix3Y?TfI4L`1Kg<*>ywQILnj?BG4ul8jXMY`F}@(4Ry#l2XB=-yS7 z-U?{*S!gP_ihr|@?sS{{CEAqV=rVgMW@zVVh8-k`TAo-dcZa`PTVySi#mZu}3Vt}| zRg{6~Spm_O0mMUu$UOEnU7d5~UVKCV8_|U|lpBvT*I#|9?H%B3Fs|;3>UL{hh|Rkr zc2ya)v_Uqobj74@U~goeXk~pw3vcDbe4A8v^FpV)#huk+q1cAvMO!m44C6+P42jza z>MS3cQ%r1QSZP2xv0Aj{8akov-u=c59OtuRXs@+hygprfHdaIqz-?$_Pu26i&@`(n zvxc~*)LY;dzz>2Ew%JRGwyL7^o`I=kU&%pqt^W-w(T+RC&RUskSXcu-mpA3B%=azK z8;p`S4+6Cx!pH63&)&;s+wo-wQZhU@T5U&G>`gvFKOS4oD>imnG~dT0B_BRXjGOw% zelps^M9ei?B!7R^@5u~r_FA?+iM)FKnJ43-4cAX=&><-x5ok_-MHiU_KGkv{aX?V- zfdhN{d~f-6=!V4UK7r%REn-jfxaeimNKQg_`vaVj)OBFH0_<-L<&eS;*?bzunQfAq zCfe>?#06nvGsK6AEsPDu&&Hy3I+S%)bNb2B73>fsPm^hKuj~ zvHo(l5`FgZ*=PlEG48OI4uAVlQF{JRly1?&04bFhpR3hOuaFU7#e}WnjrclqfLcxA zH?1syt>g9CIx{*h>}YQR|tFxeP|H@E!$*6hxj$!u=x4D|9Y z3$WE_99XmFg~0nh2U&h`TY`^mfoQOq--@;!heNTC)b=4ZH5(h#0WsR0PsMAu{`dGIP?!AV6B@VzLuEK-O0aj(MIb-hO?rl7Y z*{&M!$i-?~pEbNzDbm{=0s{ApyKK2=V15})$}llM8=Hi$78xu*z8cvM4c^mxIZ!8? zqS(|~Y?}Rb6Ciln7r+<`Y0H&WY#$Llj%r4A_IC$M8GrLn*6d4WzOlU3)(pqi_B%_? z@W6Uaw6TUxRZ&&j^^m~hzFs!4{pGxE!DH4zXi-J%9$?SGUSZutmT8L?e^VsYc20c8 z%7IUT2nLin4&5d3tlGzP76c^g0Hy<1ZhJ5r{vd3f^>`Jvp4r{-S^>E>3jOo79!uDt zy4-u*1#|uJZ5#P|`dMunp^H_r;Vey;x#0W_7>`(>d9p2oCI4-D3Z)8!`pU}^~kWz0e7K(ja}4`24f#=sTJ6^ zKJNN)xa$+b?^Rw2LqI};4q%0uNLy91P>bCj$)VWh4Y&k$@;MKxm3J;AbBZH{@s zjm$$vLIc@7vpI7^_EON=Tf*e2r^MC)XDzm$gL}1T=*j+&`zR1v+3Z0iGfN{D$C||V}gC0#WjBRpvbPUV1){+zx}=0-=f)OKh%S5W!ubrPzJ+rTC;(mG>zg}R?fq=Lk14;uz6flh9DzB z3{!0Lu=5mF0s9yIR_o$QQS*t}Hg-YeSGdLI$F=~Y7LrZ4ewNENh^<=s*xGdK*2cz! z-(;}elX2+mY`(0P=8f&n(gA8|i@O^Hj3E1PeUj|S7AEo>=YVwd_fHvHhy|$a?W&Be z(v~;HCBxd*#gJ!Py7dYfI>d(s+t}^X_WiUMQFq7s^?MF^-okzwsIVni15Y{4%Vv14 zua=;vKY|)6{3A3D71&6{VAE(gcHP%*16lBkh!s#CD327AjlC2X zu_ZPzT}%LWlmr`S^&x|C&&7iyLmTHn#eg{SvUvyTTTGc`!Tz!-c!d~L(f4#+AHTjv zEg`FBaU6&Z0b2vJP{n%F=7}}7Da(~R!1V1Eh!^;H><0s`Kb6egW4l zhj#YwiSHi2{@O$PzJKAueIHwZvpFxIHqZM5nn7*kXoRzwVI3)w1jM_w)!p$J$V{yv zZ&GX?*(z9XR*)T*ZEc9y3}Z?7*YKBG+Vqz#)3AaqF|Dv2Ju9L+CqVEhtZ2p=#g-1T z!{+finv%E4HpuE)LJsc1{4;F4j>78LRMk$1pa4cLcsx~BgFsoLNay@*C3~uG3}e(D zCiY4_ZnyDotq}8DfjKY9I1^FodF-j~mqlKIRj`GHu=_HW2=@|hdyZQlSCmbyEVHS$ zT+yuy?hhA_{qiPcOg3xRjlFk|^zJuuWbdw?w#?&9P;1F*BOCBSA8ffwvSGcVev2uo zj|IEQt1E1xvy8=Ey*2?;eok(2rk)KVJM27#&tTpG97JtF!!&l;G|h%okVc9Mr3!Fh z!3>kS(8d}$*4QDmwh^oR1fz{oY}!#{tpXH}*K|X~y`~+9<&0CLEE{VQ01hZZ`(tbV zhqcSFemz6ISN{w__U28AiJM0ZAe3QaV?kQ0fikz-GOlJ^WbI_z7||V@^_nf?B2sXO zpJL`gDe$@$o8hlale)tOUb6mpADb^2Y=}8Qklf8ccbkXUf;x2yg7C5{XdlpzwzWgO zrR3<4(Mv{n(Vp&1#2y})wyA#X9`z|S zWH|0z1M>m_z<+4CwK*$%f}~?hWp>HNAigMMQ{F0uztv(Ub&3s)bOYCc!-}b_39gP+AbS35IZskbu{v+z>R}5M>k+@iL+j0mtc0M1(D! zD;QSNd%=bngHRR^Ng0G)ctXm6m;VfF1!1Lt=W`Hg-LT#$d`nM%8a5e)J$OUP4Ph@0 zi3XSz;8k=y`GzR%cp4q=gc}YBLOFxspb>Aa84e2uM2#&k7*b6X8Xg6%2!^A04%A>c zX2b(dhLdhWMJ@XC_X5Reu7sDS%oK3Bvi4lm5A;YBVl*QhGa@M)uAAs>C&Us3*jq-# zQ#Ran6H@5mCc{H|64db6hM>$8S3OOjS1K0@^!{J0fEUgUZ%v4!ZEy%eIv#a0Bj&YH zuuuf;BLbpq3P%k_(TE_(6leLkU@T-bdJ9I6d4~y2*&z?(Z8N?vS6Gf7^j$w(* z!YRQx&kc{FA!;Xrh8m;X@Q@O{2Xt02VnreZBbFmTFk(3x;cXxTLbn^S9DxX$Dj3(g zAr>hfFf(EmE(k`f!bQP|Rk$P=cjh-97L1smCI(}&RcIy{j~k7rv{#D}5LXe583y69 z!H9Oz5W>1%6^v*XzySvU0p}_`ZEU<`5`Gqpe;5$*)Og)W50$kNjQ0$%C^7z-k77V0 zZ0j|__`(Ql65~rZydY(KD;P1`H}T?&O^DLo63WtEc|oAvwgNrtvQ7}%8BBO=wuAPv z%PqVUWD*d9w<8{^G2!hQQxWYomrnHFsHvz?xMMICHw*U!lWfBa0rX%-7r|7)4R3u5 z_XX1r^t34AnBs8=Qw;%OS?M*12ZG7BifItN)M6S!@1~fB8t{^eX}Dk-DVRnGrcp-I zI00|5m_kb6WeC$^Gv0x~Qw^qQBOYeJTMKxG!4xN$HsZ}6lWCI?ul(S_AJeu%rewi% zSTLm+@%E1?T`(PWGyN`@GVr92$#jk$>M@-!DhxB29#|=W_#(mdqM6%ZJU~<3ZAdT#61-#Lw%zFVJ02w|?skfv2yr`&$3e`9 zVT};jh;WSn({5Ld2yczoI^1p=5ThC4aoz5i5ZoE>Xt+HzAhI)pI3or$LPEPeH{+oS zyj$V+x4Tdzzu9O*9A1Q_#)}f>!h+c&(A-r(q-JwBqq&!0?kSjq1aofzky!B*lX-w( z9%MF;5X`}Xd8E-imfl-3k24E>1(*<-CmHB@!u5iAiko?cV4f}*{7vSWZWPnsPY^~4 z^q>Mx3XabNMDrDdAjJI@C{lk(L70d)Cw$-F6_&_{a^!Yr6~ z7=-=;jEoSW*Nhmx{RHzN!Th&iJ}l6y0GqV8k=Gy;xnNG#-ZPU0bBX~EF`Cl^p*OwM zXim=$d?5TLm`{Iaek+)B1oJzS8M?^#g4t;>|09?`Am2^E*+-b>(Sq=+_TJ$}!D1E! z9NV>m&{GiN1Pg$SFj%Sx78GkBSn_=%Ox7aT&lV^?{uDu&E>OVwNrEs-5JI)!_%j5A zs<%`&SZWKFsuoKf!BS7K)D_Gt$(XAUrnRcj9OhiRg+B}?LtTUr9&DIz$TVad^BHRy zTNwu+2=I0s_M67nrm7}CQ!CRjg!N4`9dRq}Hrj0}46-)6ZE;J+6ZW^^E*u2!d9RYV=Tk=^dTN+t{;cEk`WZEibL2^*d`91k#;gon&2aO|o9g zC*`Y!K)AE>?Sk3Wh5QBbm&so*e~bLx^N&FY+r#-U=2!BoqE+-3e-PV?gT=)NM|)p< zWi!}{*s9s;*}5Un>|z9%J!-pJAYTEoz|RFb6&O-rW`X4h7JCLpSZ@o81%D{$Td-Nd zkp;sG?ksq;;N60`?w;=c?)}|oxNmV!hOyO?LPZMIDHK#_cA?}#j>08iHq{A+QjvvM z7v53$0s^!K75Syek|JA*94vCa$YYp8)kWylJ}`gU>~YNFw#REplDwrdFmmb$gQiW= zCFzdz7tEOo7j0H_Owl<-R~Jn#daLLM1Uqej0H?$3bL|`LX$WDOi=d@_i_L_o(b?i9 z5O%Z|42Z@R4=cU|K}M4hT=Zt~$Hh5}g*?Bi3?reQUrqTc_N#3$3cB{y{jXSwd?m`3 zXjo!ki8Uoom2i00L|D(^o>88sJhNe(Q_rir*JQ6{Ua4L;yxx5+eO>?Sv0v}{`uf*5 zWvlEdSCU&Hz-9;nYo3!|cvtZr=e^4NxHrV=K0o^m^I7S0vt+)K4NHcVTwC%;$%my1 zl=`Yvg;M=XZ7r2m>SgHyrOTIYR(eC}^JU7FIa;=8*#HETJoinhZ$^CU`R#~r4}I$_ z*Sg%2a__%u|J}y&CCVSEV5rcw!omuUioGkwR@_!`U&Y@mI=(OeegE$xzCTwCO?E#T|r`-88aZ(rZ3zKeaMeAoLP_I+C0Si3}Rui8J>u3x)L?Gd#jYj3H2v-aaU z#p~3m)22>Posc>w>wKtNtZx0f?dtZaJE88F-H?TGM zxs}*`Kl-7HH_% zuzJIv8xC$bw&9Y7dm7$q=m;np@J&EKK=*(Z0Y@7ZYE-pRk494)#W&j1D6P?xMl7&E zV5z{mft>@#1TGHT9+=*^QsbW*cWFGj@sh>|8eeX#HmT60X_HP(#y45nWOtK&O|Cb2 z*aT9ergGCNP5U*S(sX{)^-YtSDovj^GdA;VR<&8vW|NxDYqqZ0p=M{B-EVGgUZwfO z=EqxjxA>(+($B?z4)}S<&#QmF)v|C)|CS3|o@gbss?@4it68lMwmQ`6c57SfA6pM^ zy`lA!Hr{P&wrSU9e4CgykK24`TcmB%wqx4PZo8!I*0xvLK5P4-U5R!z+BI!Au-)W# ztJ>{s_o012`(N5mZ@<5Ndi#g%9UTgG_`X9xhpruVcevjnr-QR&<&F(Iw(mHsTGi=6XG7--o%?s5+c~{+ZWp>1i~LC>{4_w_v0^I=a%uOhw5_xh>Vv|bUtHup;Hb){E!?}*;# zf(i!B?c>+y;4dA2iTve$-}-&S`hC@}Wxvt=UibgHe~13pe@z%re!#B-mJE13FlgY3 zL0t#^HYj1x)xiY^w;X(E@RK2aLq-nSH{{{aGDAlUy*;efu-IW+hMgFeG3@lPXTz<- zn-1?de9Z8v!oaI4_2fJ#NRihvRri(U58(T|!2MtPEKd5+9Njk~zNc_)6njj&D7_>-g0ZOcRPss4$`F zgzyPb6LwF?oRIUI;kPos`To}7w+X-P`0e6vcYb?2vEW3{i9byAo7j2c^og+(6DMAn zcz=>GspO<)lO|4DJn6(FHrY7YYjVZOl_vi%x$)!?Ao=z<^wer+K zQHDW2n|^Eh!|9G0MQ3!Iv0%pW z8TV#5W=b=w&ulRBr*@oF3v+c9Lo85f&^4ZttRGw3H&iXkU z=lnDG+qtdhcApzOclX@Aa}Uh3%qu!CU|#QeQ|G13yEnhk{Ce}7&i`fpi21YTubqEv z{`&=W7lbZ|TCj1!%Y_XV4qZ59;i83?7QR_jdy)U5Hj5@LnzCr|qNqh{7hPO*cTvuw zcZ<{rOGKdv&xpzqwIci@T12#u=ov9NVn)QOh=hoJ5h)SJBQ8f|E&gV4nV-{~- ze0lNJ#ZMPMU#vzph-@9%D>5kZm&lQkdm?W}K8So7Ws3SLs%%u1s5()BQN5!EMoo`e z6165OK5A#wk*L#4epwQ=ge^U~tnjj4%S$Y8vizSFQ&)tqShr%|isTh1S6od) zL$nwzMVE@M8C^fRWpvl*;OGg_QPHcS|6b|2a?r|{l}BSr#8i%{AJZhJbxg;Y{xOqd z7RE%!tc%$ib2#QyO!g{iRl8O5R~=gQDz;2)li0qoi(}8NF1>pA>fNjVSbbx)y2f|S zpfxkrY*~{TS0!$I+|sx`aS!4gYpbsfUwdY)x~}uO-1Tnj3$CBNe);;u^@r9UTmQ%U zhwJ~@;JKmJhUps?Zn(Q4XJgTg6*o5B*kWVvjbk>3Zk)4m^~OUR&u;vCllLayO>H&} z*)(U<#!V+T-QM(Wv&ZHtn*%m?+B{_Ql+BAbZ`yol^M%d#How{YPrO%rh4}jMt>Syc zkBFZYzdSxZeoOq;_-*kC@!R7Q<9EdGjNcW%JAP06-uQj-`{NJ9AKX%P%YrS}wpQF) zYirEbbK8V%t+z#QQ?~JhDhVSK;u6vm?rkr$z4P|)?XR~x6H6slO!Q6sDY19rki@Zx zVTp?pS0!#qJePPo@$C*_hiymE9mRK)*zxrapB=4sOx!VfN5;-tJFo0?>@w{tw5!A} z-(3N_TJGwxYsjt%yTW&^*|lTWp^G}p0<0}Gq4?y0(`?Vgc)Chgg_eUJ7J+5hZ7u>+?MmO41-;Fg1bCY4C~F3CSBJ}Euv&qIw5B^
oygCa*}|nS3nyV)C8jHz~%HVkwnVYNrIG^iCO>GB;&M%Au5NDJ<2J>Xlk6 zH6XQP>gd!Nsf$vhQ#YjUPyIdhTI!QDW14r`4{0sadZkTHo13;QZC%=~w99D^(%z+; z(|yvbq&H9RmL8lQm3|=o-VygB<&M-p()q}kBV(_t8w?5R22%oix=eJxE*nzSP?I{a zSZVP(gt(&i)yVOtxy*{>&azW#I&(9ymJsNfSc+pxn#>yHPSG+>F}Eb>GxR*Q(fh^C zWk`#(0^umYF3HfAgvu!9!CJEO5WY$u03sYE=H`amzY}-zT4uhNO|jo%PIJt{mCIIn zt%?qvxX9-gcbcUfSa|)?LcUG_c7AM!J$?UmFL|G@JwqHSJ`~ZJ-}5@d%0VL8QuP%j zCrf)DR7sx0huNj~%VBP%nHHcd^-BYI6nZ6yiVwk%3X0eFKSA-D6AIP*i%?CJEIk)q zmi%`UYH4kH*h9y}t}+{tJ5d966*5DbHH<9F{*C;r$foBm(QC^H?_tY`Dm&^v`PS#pwwJ@YK3@OcVq>{}1a*t@qN~Q-ikLl=)q$6bgM@;H;E$^(n-#LjuF8szu$=x}`S zu~WiDeIH>8vshQhIy;OCU`@i-Yg=Hq2kpam=bJvM}D2(r~aS?OR7qeUYu^8SUg%Vhn9v zsBuiJ@=Tfi#*?Wab{mqOBXJ!Y2y=J-x}6Mjhn#_8PO)jSdpO>FQRI`ThZJTfa6Dgb zjvZNQ8ED167Ab>@@{W9YFiLB)Ny!RLsEM)~^Fu9UUMcfW6!*wceq&2kC{hmPNH2Iz zK9-^1C1hqnCoIKan6yB=NXUu4-_f9WW#COMT|;~pWhqdnhWffVvh9S3$OzN>rYx!a zyWDKODD_zb@txLb4|EzJNPF6JE{yXm$_uiObgGds(s7o=3j0;GN*`d2tu;x02q5vP$nu zv9hpyg3*)oE|gc(?YS0U8<(SzMJab!H<@)JVYT1ni(jnCp4tN3VrEifkn9H(n>=c5+`F*sNZ9sk16Kx zca{ub*Z35ED1aTppKGuyV1?1e8-y(^%CCfS1?f2}&wjzg0O>yWlck3PbJtPRY6BQj zc)?&ag~6pGTzBbkXKm!?q_H%qv(zK@>*L7|wYvr8V10St5#(PX;-2<+uEb%tttM5} zKdkMS`;CS3PZcG{=T%eK1DTc5j$bU#_>a(cQ<3sGiW7M9|17}2%~V)-nRK<@nZN&+ zPV(-~4|b@*ZorU8*HWYW3*{NsF_w<=Wd8bpLY~JKi)wuoQPi)SVw@)xb~1!L64iPR z|AYFsNeN(`q1g14)m!QbdsU0-C-Vp^{;eAD&^Z|uGz&*{@7pqq3jwm=^4nh@JfWeY3|hpOJf2hnhoB*+LPPlv)b)l}^!@-RFnc z4q1VL%67TwC+G^OJrGsV${@1idcwGNf>z{C&_Tb_JDin?{`%4R3Cx|F*D+kYuYp40 z6YvoGVZZAP^@c$w&c>&MGf!c&6gKW0Xa&sVES6v4`PsNU{}$Lfm;>M}Fbn=am?2D# zc7(iHG8BU>9n=aA&uu@sUv9U&cG*_k^*D&EfW!ZH5nnWG>i3wnZ@3>49O7Tdyr7o0 zN5Jad9Xr>tIK=Q5j94;1CG!h)Kkn2?GApE9hsL;t{E(1gAyn@}YrH5BP7$zY;pbJ= z>W=Mj^a$lL(~;}qp<*4+So@3`(l5+ArnC7(^noL%Jx^HmYbXWiiy-#T<-sD_&w|O2 zR#D2lE~bKNah(xNO;=bt#f4DjSyVXdtd4C+1b|-Q9@6g7)`Zok%vz#cCG>49<}ujH z0$E^}RPMn&%Io(+u-_wdG^8o+dLan z`A}i&-iYpME$tT?*EfH?zz`YMsv$Qp^;85I`gZo=O_77k*bx?@<-8GtT(dx{fU+es zGvA0wpC$oNV8?=-Z2Zr}qUkDVz()ZJCc-g~>LBNhn57-jp`zxdV$s}GV!N;#vST!M zJCaA^xBBLz|B8jWmko6MP#FzuJc=;pR@zXPv7xpC8}II3p4u1yW&SPMJq8EkzNn8b zCU;S3N+EpvL|FrTyM`{Xf1PUS&DvbhX($Kk<_Vdw=u>bYHy5eE=15zmej_`Ykq*8V z84a&uURD^eJCDL5hIx_E@MRYnL}l-aQMqq4fEr(c-u#_+oog4jp39z#>QR{YoE6cW zext{HC{|i-%@4Ey0i`hvsJh&BnSWMO%cOf9jg`(gg)?i)yV(C-ithL)${5Vs5HekT z7RpM$FLj2Pr{!7~!*CQ>GDaN>)0kMA9L-c&deiJfIc)?Q*MP~>@)gO!{N8uK<@--G zUmY*%g~+z-sDjQsSDxQO_jghE(`XSiJEV86xgbse9rnz)h|Qs4r<%E^wKl>+(131< zAxO#UY8aGCS*>O1+EQ6c{tJJ39p}=802&tZQ1yV>2+`(JDr*vGmu{n67RsffT$Wx= z?+<$~N_TWvFHt5NW$vI%HkDZ>t0k~rVIf%n$25io;MTPIkKm{rYo9?~q`t#k|x7(#V0Dl|c(*XYVr>@eLeWHxO)CVhZAMJ)sBFu)5%VYp09ZyHiyF?oC(TNp@6T z1kM1rOF>l4sm=>y#om7^kdjv*>b=_p6j;bde<}bTK&`Eq9)fgX{b1X80Y=8Yf#eOL z9kJ`Odco0e8y16(nZ6Wk!XQc@1}ksCIHOmXw_{1DD4k+nx!bg^U4-T64H(_%b0TGh zqK6&P!yBR8#yfTurN7AJ{s#DZ%F}Bt5Pycj4h)2(7wUepdmnF=vc_9u$B$e(Lic%e zR1=%A_EaBzsj&$5A%t3378rWf(WZs_6`a!xOqC6h^=8(~RpfRc2;| zEdzRZrFz*}H8v6snKE4yDpr(zBkQ>Mx}1F)o{IZ`n-3~%KIoBsBA-vDk@!3aqMcjV zd|cqF@;P}{nm7GZ_?BEFvdr^ zJFs=4MS68CDe0JID~^=i8fD<9yH9pn@~*>X8o;5M(p}9Bh;OGm(JEc|!}8IL3~gN_ zdcYB|Pv&#!0tDacXoHVOx!1v`hOtl)hJMc-{xwAS+=Ys`?eXopq-zFJs=_uXY)c4| z)w60vdvmrWfN#N7M1L9uT;jDY@SHsWSK>@7mw9b_TeyqCHCqFBOXE0J;RamyA8$ao zO*VA3e1q5rodzhuo4OK-^d_bTw3#3G(|Y4D&~?x5>B2(SwZX&rC|4C^g4AV@tboeJ zDgOs{be6&nq%2%Yd6=+&Byw(RIk***6s;ch02S}JD!xQE|L4OH?0Bk;J4n>;AeIvI zu{Pzfwts;9X`Xp1|e(4CKs(>3#48KzN2hv}Nxnhy6ATr>Opam}z9_HenebE$=V z>u}9{16#=eaI(kK2>{K-E8I2O(EfGT@Hur|3;8M&y_nCIM1FSLH00kR7mUNxOCM)h zts%l~=$>5Zvftww?3BFE`Yhs)8_zvq2T$|lafj^%(WXYy^?r@F4X{X;wO9%K9{e}R zos->z2dDHvu}YVb{kvtz;1IYi^7HH;nVq*Lha4E1;GJR7dL0KNMf55bf7TO0n8sQ; zb|%Qub!=oeSHC}>na}T|KILgm9U|OUOl(21=Lq8fPZj3GYRWRwlhnDUB!~Yf5wtS> zb{)b2fulrFqI43Fnj!OG?x&?ZBY~^7|9KK0r6pm5Q6X5(l7s_t9FzoPk}szgTMIBO zP(Ffr=l}}4mI!Q=*GTU`N^>=%F^~heA0=Io`7ZeHNf+>2Bd0$?U>>xsQ6&ouA$QY@ z)`FrM9CHv>kc_T1idg(TX%4sVx1Y#v=t9k5pab@u@>vc}?r#Lt2mh{;Zp( z^*H2@71-~uYd!Xbe$slln!4&wLk1(KPnL_y7z*V_-eh6#y7Eps4(eKiP}a*elgNbl zQOi$OTYjMg(F$QgH8sc;`EP*1&H}>ts7SdCDSF;az4#w91<(*q>Y!Qn7ut_J&^u%l z0#DZ9}scLY;c?+SP&GZc9rE6-Dh7fe-<oxU6#f267bJW7n&7LN!vJgh6>y{6jH2>b7%unB)Ilw+PjJuh-p; zx;tbIWBAY#C9-aG2kplaC2C8=;;}<8igSHM5JDSt5}9b-twbW<4z%+`3mjVEv(2A< z>C$SGb=DF%5^g?~#f>7ff%!P=;seLFawWN#d}uG%=t5OZ1uDH=-^o=Vg;;G(BY38( zD`__+op7CnJN-VU;v@k67n(pkyZt;2!D5=RqK zZeAl2Uyd71Yr)0vpUhCsXJ{<{bAMf7_?C30&voqKQW^f)4+0J8FaPS4Q333izc#mO zVX$$r5KzYI-S|wGD7~$kw*nsp1A4*tp}JmC`bJ157ugAVIS@fdE`Pax|Jz)FEypm@ zF!?$~bhfi=NgzD%U<>6zV8Ago?{rdVEia(Y&HFFr<{iz=`;T+;PM;f+2c+uqfG=eR z8*>ez2AmNq(K|)F>1PQkU{%KHjCW$Lg&J#nN@z?3YE3_fD z1+g?)IuV5WC;U-=V-V_}@c&q!BoXjv21)zM@c}}YZ1yAM5Fr7sWyupnfQWbw>QL9_ zO7F^i$|qq2^%dPuJmm z%tnG4Kb!%-XTFL*vmdq|nYpiL2hZ--j*I&MEx6BPN#N@XDAyIJP1V)PL|IGH zYC!^=^A&YI#H7r_0^a>PIygEmd~Nt1=`K|CS1lC~BI>(3GW=Y>Tj30XuNl&VpjnCL zURtUb^Rx0r3T`vloGe_qVp+`m68t#IvE$ZNEAnhlFmI)07NIm*JNAl{qxNAp>?u}B zjo-3r@4+v$>~Hq$Sh04Cj~@VJS@$PwNr7Yl48Axb#Tr{ z1QlMEA}Z+y15kLA+VtGc@Qm=x@N2LY_^6cjsgEYEvBe5s4AF{|6JHN={{Chf4?sGD zSC`{>UrO17UzZi`$)>=TAe>LJ^C}2kSH)7zxzpa1O*sb_y#_KuNNsQyMbz~O1&Wbo0 zeXV>vKW|6KE*?IJpSM8BPGQl;u<$K>GD=N;0g#$f&?8$p8y~(goE5}%^^A0lh?9af zI?G330MFQnI5>1;vfr=&S<#(z94CqzY;CJhInKjt*ZHzCAoK zJT_I4PKBz|6}u~ln?<@9ia>5lElB1o3C_h(wsMJ8IuYt@LZ2wz#7anoA4kI{La|Me zwuz6&7eYpiUuu=^g*uHWsv1+BFsQ;Tp9)>gTO$8nC~JxQ6QMnHNQVf}CSFJfRA?iQ zq;x=uWN@Y?W||e)6MlkqB06vkhK!g$PB7Hhb~t~vG!0qWcm2SG(Ixmm)MEXuXfMUbt0f=MM?U!u_C;O;FQ=A3@drdX4PJl}4Ha3=3H>s(`_z!HknT1;s52m@f zvV|w|ci5+{C@p_6cP8uaz$kO*OublPiQ=i)y(vT%(#5a< zImh=W9gFaG9z}lph@hn7o~}?-G=(c!ZT|y*Q(KSGVa=_dt+GftD|^pL3{38&CJ?mq?}yMGcHAF@hY|2=uTj zybb_v=Y_T27N*~@dq4lFXws_xEh?NsI7Uc^(s<93DI29TXjc^prW- z2YbJjW;WZpaM8TE3w@+F!GJ2g-2_aqXJ*2%<^A%NLc&Yyxiw})ariu}>5XCLrd0N6 zrgd3(v`fN$){++xReH<2u!?q_!qg7>(+g32oOQ-Rv-DOEmCD>Wyp}_(($kednn0Ov z*Ya>|7FClAvr?}3#+AXT9U9)pt`6f^XEtT@b1)goF(hZg=W5lK62PH>)OR}OJk$+@rrtG zWnlQd2^&+7X|gyv39KS37JgnzS0U)KL-h5QGjr}{ly*d0rMRd3ym>R9hMkbkrs4aH zri1lhnJdEAgrCsH5{!EFoYy+A3+9@Z4*Wtr^_sb%F(hbU~#J6IZ6qmowE zH1i**A8`nd8Zq3=f2WUhwhMz@-q=j{gcNtvieir}h=gO-PHHME8qNw!aj-w+o!Kiy z+k0U4MIb@GjaNbx1z!uZ@_uF>WtGx-VLs9<#oe*&xoqY~b=bfoaV#JE)yz2(7`L(- ze7~6|u<>>_(|QhpN2wJUJp8rMr0&E}J_}u1*Ya6h)4y1EGao`QMq6WdnE7b>ISDB4 z3;7qjA+l3yOi9^&nuxd|thuQAlWYI5R$3B!0o^tE*)J#B^kpbZV!mW$g+M^rp&68- ziGZM#jp?LSIEDBkNi2t;{0U0*Wx84k23hGS|I(kzr|adj{bO39JcTk)B4t-A(aK`I z9Tudw^F9dmSRCrHAidtZIBKUm>6xdA)YeY41(I?&C~uYygI%;hHoN$sF8arC>0`G@ zj)lQMkhNTqvg6oc$8PlPWe^N_;e0N=qsCrRV=rBeWyfiq)EgqH)Mwi0iGI@ zy9(V}sz`6yq8C^KwTM{0nKmw+8v7auTq7N93>j}3`EQtevCDfz=^%yMQubMg z>T!FXA^;)62UNgS!e7mhYtZQdL-|ly$d-f?TF+7IILd-oe9zqisM8IVC)nm#*PWW= zOZ8-SG5Nq6gs7_I3J7B1b6K5};xrM;6E_029twgbv>I8VYH@WAl=Y!2Vx!ishYZXc zhmUn6t8%PDR_LWZr&`B*<1AKXM#!|tLc)3QBdAme^IXud?ZF~C{=mV!?T;`ofSLXY z=1YHqnN2Hu+dmIxx(jBuzY8X@t8@-}$@)1!N3@7yu9$PW#4MjbZITDny=TO)J_yAo z34GdJ$_<>ehPtwm_c`B7Q}PA zq4jx)LC6Y_QugCITH+DdT+`&}`wC_LR387=LcF%~1k`W}>kq(v)Jh`kYRIbQSzesp zpT()XkDXJ)K(zC*J+SKp)}Wm@OtT!N&m8p{>|?7rD^ViMcC<3zIvT@_xR^7hofs># zNLXr7(aO*_)OAKsL7X5;gOwXwhk%H+oF_DxbwUt4q_^lkOx&#~ie@%=#Ua`&SZ+-W zI91&%z zTo=#lAiiyA83I8l86bRU@>6*Oz|cZT<%o#0@(jiUkjCb+it_hYD0W{BE7ZJX-X101 zh&X#J_6n9B>*}qFavMI#4jC8C53;G3F%M8_5X}zZUfj1x z!z!THo2l1?bn352ryNyWjdpLs@39M?0UdjA2!}fVLZJh^~tA5t$t`f=hmm@$?gG;A>PbaR$~yk^c!{! z5xKvNl!*)ESJ(<~u`~i2bHj!r{Q6oM1pGRf)(&QGB^hqwkLZ<^u4V^5#Z&>hHyQx+ zF#8a~N}qkPhoV6@XlBD<&#toq`C2!u6! z1@X!&GjnrZu}3Y4TomcOD|2^q^FnxfPWK!=K4jGBkTvVQ-JglKSbqq0qi{&q(D)vM znkJI+8PRKxi9~$tA`!3pv#(m(rAPjVMSayjNyM*A`h{@R&%_%l3`VXKDFykie;d1$ zjZ(K!C>v#NYemjek)+l1*`fP?D)591fe>DV_HZ;J zuo9Qln045V?YD^>hDMLA6gpKeK`KQYs=Y(n!P{akR z9Vu+iiHOsvhGOjkDv1=I&OKRvD^n;o=1qwdNcSzNu_#FuwEL)JU|#wuED-xe_oTbc ze$g@LBdkuAhCdOiupvTzN|(oq7C?b$R|8y4yTIId(>yRRh}JUd;tu-`ntiR+ERjXZ zniYAFW<{x!>xlr<`Bqa-S+t3k$(enN3_5oz@lhS;|bYx%LDsXHy}@R8IY@m z3E#k++fGnl=^f3=)GD?kbkiB80$P87ZC)eDFiqdP7a|*)8$h00aKfmgHs?bFSXrl$ z2L`ZbpDf8=iEOHPOl@wjOjrcxsvQ1f8)d5RTp8%B$0{c3GB>EAQ%03&h0Jd{W5oxV|+zeM%aI86M63 zcFXEC-a=um6m~$#0=aOTewz>q_s{QS)-1Oo{J{+DAASJQqxpf#)+#^!RHe$5pB_EB za^;cF6Kg=R%GNHw^y%EC&%V^OeS1^A-3izhh4lc|Kr`xm7G|%+Ht6+x@UH{d*StOg z>_BeTd5)(K|f9%$SH+b7q5v8>j!lCWR>GcSu3gCYE9xko-3Vm85cTBb^*%Shp57cf=phO#k_q9UR+vvzkJ;HY z*ddC?wQ2kahTr3vnr*z|N(bTXYJtz@zvS8b0kh7*x>m(J3{ei|^?^@iEub6KOr;$MomUJN#v>=zi4B6Od}!;@!~QyI`^gtKq$pS=?C$~reP za&F|8Px4Hkv0%|m1P|68kbpvihgcU(pFV#&dn+!9nmsGh8`6?bk4k)+tbf5~{?_d5 zE~(wSo7oHv6yD6JTQ{}KmM!LTpVwEvm$3lgjlRRR)px*z;iG-x#|@6{?-e|9+HWC< zZ5>O@5ZEQPs5No(=EUvs!2`W1=HzFeY^99wZe;#)mOT++dDeua3MX2zLgL3ND05CU zWFQ}bp$RcLi(1s8qO+)#{w-k*INA2no*l9A>%E7^B}~}mwRz*xRcm}E;3TQ-*&|un znJ7vlm=Ql%QBiM={RQ4lZ9{GS+DZ#1Cyl2P2lWzcG&rlwP87;}FZ;pK#eR{O0+HKY zMD)$J_6Zg#0r3c>p;RLw6lE$vH+_-pQZ%^iHC;H#UH=6a8%tfvY@bkgH|MQ?6U4Ol zHxTOs#9uP=5DZYz_hf1(Yob^$x6%<2Xg>^rw_k&`&m!xOzg~zVn&~Y~qH@VJ0uAYF zP_$B?1L;MWANWj7LRXxgEKQ5UttVivuAx0*VoxALx~9(t=~rKCo(Vxji!EjSHBN48 zSy@`D^Kk}$nv`gol&;i?XiUmdObU#Niz2Eg+or}ml0ohN&gP11TjA$^uoCI4ki40w z?CYh7F(D%R5jhHg$WGx6P>A>&a)wga_u$5B=qZ`34V(?WpqO2Guv;h!X9IGeB3^+- z%WHX;NAiSRU!1>4@eEa5{yDw;5he*d(9qWz$8b1JUr@^*%Mh)ctqcdf)!#*Lm3E9i zBgYbz{2~-1ps^}M2_x1h`IfgJBDpmY$#1mrA&V?I$v0^e6u;zN;L3L(pV%COYoaFP zR&5~=;qmM2iF80-O*j>t`(G5^S9p z_&ZB4eKF_rP#j;Q=6~(epjC#T0MW6$DiQH`D-a&5mEK&VRoGxd% zz}zPgnmfV2Kum{iHVhe_Bfcjnsx*?MeDoqf(c6HR26(s8nl@u$?3TERi4^;u^z_Hm zQRsLmN^M9-vE!jAH%wHRP!bK3{igchqpv{A01TcoXN$~8j6sez(Ml#X@*?qsFl+4n z(LF#f^4?Vh3VFRql%o^uZgmHNPerI}EM8Q9V-4(UVBhk2KD!|v?Z^&Rg6_v2t`_nT>N-_8g;N1o7IVsvfIV8eD zh+j>oF^qM=zL^VVK`pE>KV}iZKQFgWWqtwNZz^JZ(o1o*t>0zU&Gufd#a#X6GrKy#S%HHPKijO^OCec^>n})m=w1oi4Ucgv#5WgfsN5R?-O1 z70zpRR|W|~kimLuwB)4R#+0F%2wljMjjc^XaE-avGpVVhqYXo$-Iqa>DGj#KvRIc$y;qGp_+nI-|p> z2+FI0^Y$kw=&Uja%oDm)F!T5!`8YVnJYUrDmdt_FR8>mXLNl9j&q zd}XesqMu(yA7>;;g;#*mofxp@cIF)>CRJq~puVm+;#{3`eglQx7tKHp za)(t%Bz6y!zJ?i*RP`_`V#o6WpEbzh@|udXR?qzD&SdYZdCzy0$1@`rmmN)yJ(rI> z@s4Y|;6DtARn2YbqQPj9(KXOu{~k4)>-_WMJc8n)7_;4p;`$#2w-cK{QY5rTT^|Q) z#8>|=1tCG(+=>t=fl+z{W8lb|qWd|xEzE^jE)c&#rgc$R6U_nmG`nMOq)IaEN~&AB ziGN z)*myQ-}o2C%82!8yv95{Y{b~XUQ`k&3x+qO#-dm9=yA3^3EOsiV-m^aT&D+Axv4fk zSQvOTe7X-|4P@8ml5G|>qj^=0QSZP%KzaqMHC|30u0ovDlt zW+nMpwa2x$o(PF6g6pY`XJp8A#bwBKm7E%+Qv%vO1se=>`_+HE0{N`E+IU~#4wP~N z`M3B2E%)@2zEms>qOtmq!Zgv?qa~NFJ@JI}08^|b3!5h*(b&4rXjT|L| z%>#LFz&E=h@;-rD3hi}D`CjIO;5k5rbRPpEn)n|07*G-|IF(XmZqZ5=VRp2QBq=DZ z*cG&WRV{LyAA&W+adzmcvk2a;E2+I(*MeX88G2jTGoUMq+6hs&K^8re@v>P{IFdDB zbMXd2kZibx_|mu3NMDRBh`10ff&HUh3!MY?Wa=xGV|9SWdviZM6>=Q|>kYvU?jfzy zTlgsCI18|HM>UV=ctwZItRF-Wph09Ut;5+&LWweYfV3T~ARt5`O&XEH?Ro=bB;6MA zV^~`fMU>><>dBe`ay2qQ&SKSG%MHpS8ESaLVf0X4QjB+0+n!?Im{%;0TC&C~OQ~z= zI(S6C-+cHQ=Lho*3#-gjSRATm2pJ4`R0mPd3#gH)qAurgrD&pZ?h~jbYc_dWK~4P4 zO}r`6A)dk2hOtBD%ggXll%%;j7~!j?L4+j-FvS0d`V6Eggf)n*okyA`Uxm|amab__ zhNdk`)3hZwmO;gmRL~XBoet0WP#9xDDtILna;I~lkP4m;)fK=Ap{yXJf|;Q@oP@VW0Qo3R19>&B zG5zjFitFic*w7T$WGPIF>pwKb_4#y7Yy1cGlsd=1{$F~h!yt_|W(^u`3WFa9tV9~^ z^LZNWt3fnq>f!kyy@!c<56`)Jm`FW5r}r=sJ;Xv#*GSdSFfml+w%(IebmX?y57>f!Tv_r3c?#|FU6SCY zI4avIt`?-bZOMv2uXqO)UuqTaVEtaYmJdBUgBICepR3vbw-%@8d5AnE?K{l#?qq{o z(t3DDZzv57-O(CK(e4)~l|ayq|XRRedM# zr=2`qCRz1UO*tP)m%?op1!1QaVM|Jigw*=F-iahsysmX3DX$tlO+HqH9{M}4t%JS|$k`g; z+gO0?Zlojxv+6=DxTcetFMQws%hn){6;oa!=Olk7isC6)}1eH2z30(Ao` z;<9muAtf`5`s1zY9q=#;TL3vAsBp4#V{=J^1b1S_?H~+(6lYUBnC5IKtS4A!aMr;0 zPyZifUjZ1!@%^6=ZZ~Wog&Z5X%id9;Xz{ja2^`+yF2#$x1t+)#cao3M~4!it)@=bWmHyEx0V4sJ{0gvrfQnPs!NbfQbONY7a5Y`Y?_`rxNgm;UN z^|CRHa7w<(IxE)8tSe6IqTzFL57;r^vpwBY-)IMYB*~*Vj|Um|Z}Li{?O?4%3YB_BrEa1WPI!wn>nk6q6Ju_{*DnfLP-AKlE>dpcjmc3aM`Mc`kE2(RRoJ+ELu1?88kb=9G~c@9m=Eg;s zA*fa#$WRetw0R9J34;4A?7H6?BGd#l$9mr=j$1h3a6qsfF-$+kt=FlysHSx7Cz;(y zBgB9i1fk@^Ew-PekmrUI0G{bal2`fE*BfX;eNxecE*j$30=ODkpBwMFc9LEbO43(Z z(T!Sc9K~TW@xEqvaz7vt#(FxbpJ%9dQ4V{#rDEr{*nS;N_(NUdjMb8aW z(erecqUPc!YH=!`A_L$jj0&a(Fey@-czGGh1Q}(mPFSWwtY@aJao_!&q;{IS_&_^8QKk#q5xVT&WPNk2Jy)TroDFq_Pn zK7Q;phnSLTn)CMEsB4vc_im%TZQEMdAk&IBC=J%AOk2!=Vl8PMl zvysZ>w&sPC?4@F(n~6-^%*gHqm-V|j$^|R zPw^sVgM-WdjobFlbTpH{J74zi5soJC&EqOAr)K`OioGK?wx|zZ?}Lh0d2WR48R~Ni z*)yb+e~H<<-WKW65UKYqF!c>3p*M1GsfIB_DX4AI}Sv+o*jX2I02mZfI6yMC6T9IwI#3I!+OJP-e%7%+&k0 zpY{F?_5N*I@86{M9`g*9I^yz3FMk8t?cJ#g_m0X6|Hzp4S_onK~QP61e zC%Spkr5n0=u?i{Wkal^w`m3DU0Q2=`x6DX9dIx^IQFx!!PYp2?_hx^W5=HK!2t0Jz z!~nV;g-7=I;GKJ-9#aIKxA}A+C2jU@Bt!Iu?`lDuFoW-Uy37f{Uig&!yAU~d*NnX*ndptkkanLm{dCuey-PlU z8oaT0>B^9*-&+O;sRlSmrN!QTD>Uy^16>cw{6!EINQIBTnP53i>llrO5pYM{`Y7T~ zi6CM<9+gI{-ncu1Sko)}X?Uzg_P>Z)Q zBpa*Hf6}1P!HLPdoRLmUtfM%J%UZm$9PxmvyvbK=5ZHZ+5DCDb~0XMq9;#XZyr=(>Rj=ga;%x%QwU`grnT z3o(>zzU-ua7ME&!A`O;3i7;O!ucZ8%mmx`+LsIt4A}RSbq~tV@l~NcHQrA49JfX0< zre?n z#}KO;LW))@2lyDXHN>Ax^q6+~CR)faGeXn${Y;tYTfA#OhO?ZgI~Af|0E! z0U$#w&d|I{WPCJv)MFz+_)1CS3uQGwJb;9!RM?9oGv))odVRWNDYCfVCtO6(<|fm% z`!HVg;rTT8Zq(sLeu;r{*2t^8kL}_!R5MFF<%@T+!WnTsyUZGkA~a9wdkEV5JyoF$ z?)$rGpWpSP>Y^@Q{-}q6 zH>o`dHk*|p!CUyHj54nqdQXR`_jJ6_N~P4p^<-aCd=B>GtNBZH&(L4j*S9xq-K{m$ zorx)ar0)EV(eg^hM^cQQV7Vs^JkpoX9117fd-#VhkN1b1H+hwPqy?CxV_fX5G)Jvmsei@=G+P>{cvPL7qeJ#R4( zUqeqbkbO0lLWEDPAX3~MWoj`lMB&)pDB;&Nog5TX^tIe=)z$$!>~oFi;iFM3ceHFh z4{!aJB>*oJ#aqeHcut)XJ=HEWiUv9##T;}gVakFTakKo};Tl4;Hb>2#K5P2Snf|TL z6u=e!45??E(evzAEzaYMs9N87CZJk-xUi5u#_)arD&|3|WBY;u3kNS5>F;Sok2jFV z#Kw(VV2^`Ica6vkPM3EE#R@HylSXa+6>=Ww7ua#Q?js<2owP7v)Ua451t%Vp;|I^{ zJFVB*gwS&^rOWjfHQCtFks7(#YvsnlTkT0?Q?C%oyOXOT{3Y49ORwnGq5ONCGeuXK zwSi{H$hH|L&7U`E@;s+#jhYcdyJE)Dn8XDCRyqP8MU@m^{;h)Ut&?WXm@s~Z(-SC< zA31Wu2>bFWD$gwM7`nPu6I*+&ai>FyV7xj5^C5^=(^og>>D@*8<#>dX zJVppJ)Yc9PP2_&VIivTA-4Lti>F0mTo>~XA!t~27#uJ zE3-ngq;-@D`eeLC1W->h%ZMekK5PtFyYF^M2R3g{Lf-L*3a046{IT)ON@I21Okn<` zmAtBR^94v?F20fTTq*TryrV9vI2bGM-X6blm9vs;B<^l6HR2VtbI5YL&dm9Y=Vwt? zk)G-@D9&6vh_NWPFtS09Q)E!Lx#_!8JO2xuDIw_qbv3&*RDQwa)eOgIRsy(`A^hV9}Btx^&AT zC`_0YkY6)@OFl{T6_YHy6gd_?QDzOcc)r429xlTQ)E_o5#95y_I(FUI`QS-$^YmA9 zVQ(aVNVRf;C7rt=z4Sp8bej|-ekdmz`ylEC1$QqKzu*hv#DAGi!QFyW`(d)=vh_sN zJh2Wp5huP55wRztL?|^ZlpdSssUhXLTpA=&0@tojrHIgN@|CG44=nf{nvwjPdp^|P zyUDWUvwdD!ZredY9lU5oFTu_iS zyN-bF{VUfWK5b*Ak!2bIU5J3j>KrpMdbE=V$X5WGES zOq_0q>&(be(b1!vTp8=hBsZJWVe1|=2ekc>A5GBli%a#babsCUxbU53<<;nZij&35 zlV{F~o`r7h+uFYAEa$ld%jL)lhj;int%5wq~<4aKXm+Y&;G;o*hV%{!@tHx(` z6`xr-UDRY;nmKLe)LE1L#R9x~LiB`aN5`CMOBOG!ja|6}4kQ?5_^|xOW{eM4~1)?(g&geP6PyE0zVWW8nmLnIh8n(uc`IDrW`IDz$GZ;@Tyuc>P>*lUl7PHo0 zSm^=;E_qtaZSd<&NNtEcT7>__ExLv&-7nI z3c#~quz=|pGP8eQTjYrTLxzx|E$HZ_qx!bPh!0*f_7P4}|K{g{LEI+3$4tIv-|rE$ z5#t2Y4qRf6@Hei4{r|H>6vOA243R?r+=C0w1u+1FKH#WGFr084VmI}3Hu_Ri-q+bTxtM&fojq?_*a0(*`{5k6-&zxZqUCeIxfH(W|q>d^>Em`EZt?JEGhHwX!2siD?5m}kvIyG(;esmPqsR2 zCye@a#Lftw%~DQ!gNH6k$JyCgO)Mgb-k88v%Ts$ zj2Y@LXm@ALM9w7Z`MqZ>x=4oM;pj`z6;ucO!aNrG$}+YE8Qj^(DtMk!Uykypkn-l&!^I1L zN;vP9#2j+#!oU<09V~dDiYTD6C9?JQd~DAmG2n*6hEkQ}YUZQ!WC*ngRa7@Cxggs^*5i{}nto@VNiuTE1H8Zt zA^KWp?RCE`TvMNWG#x&y?di{NV%;vOr!rk}oJ}B{0#jJ|){tk8@e&Fl7I%UCy-`=Y z_eostuh6Z7*#eE1sRTo>XS6A?wWY8saFyS&dx*i3b@vA~|0ni^LvYAPr4x~? zoE3#a95s?3N{qsLr`NrEc9|77qUe%iV6AB~Bjqor$>AHkqs$(Pbv(ysvx4C^XHG0k z9qvG$jb;gRj9FTTp--I=nwVKqy19~BxnN^nOi4AD*-(nnM$aRSp6^TF^T#d~;V+Q4 zfYAgig7{rjl+2+s`)Q0Eu*nBgM~gv#u^_Tf|8ewk z(kb{S|8S@=8(q^4(f9}6QEjlbMUrE&w0P0X`EkwxZeUFuYrMC*qaSOk93E&{G?iD; z5_l=4n{#MExk1a84V{N3s|m4jiH>_crEb0Zba%9o`VNdubXs3G7E!=oaEsAcV^Qu) zZrCA$kXXI}8{EK+O`$v=z>X-1(y={zjv<)lXyd)?vC^o9(_KKlFE3lTXt^U%TE4J% zcV_{)Tc1AN9DSv3eHJcvTJJXylThtYB3^&v!#QNZGrQxHLFaxTt@o*ZU< z4s5eaEHHQnQzx*DEUyhIYszB15;ue1Ff9cVPUQp&HAgpc`84t7@)>2O>@k38mj_>y zRs)e5;S}FcfT%`!tDbKoks&+b<05(hX(D)Za>PXf#Jz_&98~uLKWLwam4EA}4ned! zn=Kl`D*H(i55V10QV#l7+WL_Gr^Jkv`*w?nW(F{eFI+Q5NCL)Q_wRFhPl90K8{3>QY*sw zqy&^?nD(MnC(&ChQ0t98!=0SvSKRAhY?Z{FjO?2?TFqlPWts)y>Fmp_z?^?%l4dNB zm02baKSO3f1g6DA`u+(Gw2q_R#Lt*cX-75HU@>wfc6=j00yv?S$}qm`BJ zECw!fhuK&K6T@BwvlYwC!)T2QRKYZzZHgq&cdJpsJ%H<924K|XXHq$3Jw3h21usS` z{zz<*2OID-@8j(*K&_gJT@S=CnwqV!VzQyS7>Yl?D7mhddgjws7P)ix$nI@NFX!KCefy0XI>5;S zz(?6iBO3~#c*C10i@bXIf~8x>cki>-VZAmue(}g9_QZtgbK;yrxj^g?;Mi*jV_Rh{ zffxh??sEL1C2nd$OrkwTA0*Xo-oEZ2r^xG>E-Lb;5LGwoY&s^&3AVG4@~VZ1E0p36 zmp1~YSIlQnFJtLItH_F>48RRV4z?7k(!VLL`Wvy^!gjlGasY4MjVtUY@i!LxQ_D38 zKuAX{K!9UN1(;79vCPCGH1G?+{#Z2ZLi5QpDcNL#Z@~nUSt2rGG(3tB^!T67)wwYt z3@4Qo7<-a|Y4Bj`AD187SOE=m9?mOBFhUd78&%E71sz`4m{!+ z05!xBtbg`^fV6Rx8K_&In>Q(coR_8H#6<;Skwc2~$S89QX%8^z)d7b>@JwlV;K(Yc z^I!%9h&mpe3ktbdInfV!o9J{}2>fTTX5?3#h;|hOeSD6rR72bm4aIZIO(eTvJJ}C# zA)bS_p8+q|*$lW!WB}=1;pn8B6ek~+ib)F-H8RT$04kAFbF_!(F#o#emgyxgcv zQgq0al0F&Fpw>66wz)ZRkqh-AgB!RAwzJFHqvIM&#K#2qEE^4Y??rSU3r)t^e!K_} zx2(ygKGKfyX~Xg%0pxq`go)}Dym%-D5SywHO#5+crDlsquzQB<5nSPJ>NALrJS>Xv zq=D%Z?fDLw9zjnj*i=VwA4Kc+1V4|2hX1ZU9bo&^-m~81F8A4A;#=Bmc|HX)9__Mb zzJ)v37J6MY(vtj_EI#NYE${z3g%O4zEz=LBrAv?en_QR}!+%bHgl91|NFqd`WfQ2E zu=APjk#CJh|CL2!7rp_TMpd$DR81b%TlrRGH}>XBWISky`uteKd@&b~<(E|FySU@HmW(a85 zTtuK>+7VI1pZa2bquxVbOm>KrDDP;$jS|yDuQy7X1#^JGRCr@76-E&KuL@4uFWwKirmo~4Wu)9vJ5h{lg0AzsPH-hD65z^+>om#i< zggb$}8rC}{ar+{e7t-)8Rg7jShW}lDguR(J5F$<`*>EJG5aq=&xJ05o$Jhiz1#yxD z=%OS*-#=-J&rmh6(~zKfO<)upY(@g~eF)GT0yJ{`M!#X2Et(aD3LC}`f{;kX%OOuf zl5}svfd(K+HOMp12xBFz7t$ro1A(Z2uJe&rMW{ z{1wv>01(%ZUeLw~Bid6<=hGo*holMGJdlM#5p`CF2ZFW7*?@sh*4q$)(R&O(>x_M^Gm5!@t1uPtd4>t>L%cJlXDPy1s3<;8HJX7< z{6EB6egp%>tDV;F<5771(PPzshlM9U4OqFCwpWxlMoknK4G|6kL)`xywTbclPvJ2o zbhZQ;?U0#iAlOJwM9z~I5)@``-PK&4YB&Pm4>bSxd3M_Ssio#o08iYYOpoWF3HH>!hReS%(?)xvbg4ijFXpA zS3x<}1qfSfNh0q8#^cL!>a3UUw~W+gnLO244R3jgf&z#c>T(^aZL@W!6H$u^@zw1p_7aS1|j@`wVKjtkY=# z&s@f7APT2}D5gqyz$KdFB+%SA37}m+LFh^gMum7<6k02oP4}`My6CaJJDhUm%|>jY zabr0-;>KLic5By^RAZ8f@bPyl>c_{hFhDhfF#mh1Fdq&RM~U&(tCzCVEH!SkY0vIWoA)>wCKI#DcdP>BfOi$T zjB~Kf6yh<>8G(3!nTA_EW-yU=p&9IwZU!^r7$BOn94?VVWTLr5i7t%has+#Y@Znb^ zSVBxsGwK+UJ=qwqK7$(}GM=?}sr5<1?JSf+Fz3*yv0*+dkH_qg8N6z_{;eV@ZYcCHR&7(YHhSMx*3Laeov zG+&v4)ndx*&9Jw}Luj972<`0d2-V=LkVv*`X$&`+`DlxwMK^?YWH2*o4$@gXY90cq zxDXo*skn8jd5}#4Rj?e&d}9qWC~kYF6X2_P*_%N*2FvqGxc_`4%2)H`NMm$fQ9cex zJgK5QA8+(KzroQ+8p#0ekXJdV^B~Cedy}4VzY(=+dr)89l)EG(|RE# zt~I4I_8tg&IR8)8jl@<4B8BzrJ)kIkws%uIQSzp4gsFJaxvwS97FU3|_9=O#?&soX zNcK&8Qn==)f;~C#Snrok`3Czqn({%gCy@e%kVz>$aEIJR{xfa{0@OQFrgbw68uB`P zQ(Av#~^tw}7G9CI2=D8b)IwZ#!@;ZWx(xml#RWDFP=EuH9 z#Zp5o)44azGJ-m(C}eU3fkGxX5h%Pe`J9pzl}S4#x@SyV`k{LX6tbKOtpTqz9&N6D zEH-linEOq0%+gK3cWlzTn;x_zjvHeHaeM{_2|E+v(EUS8{yC3eU#J~McInm5Zi38h zUAu0Z^C?7_`}q%R#j92+(QHwhb-kU|=WTlTL~^koPgl9=cqpAayz@jHJf6};=Ei|@ zB7*4uKsWu|gZ&e)F_J=Rf%^SeEmI0O zLM$8P$_K`x98Zhs2BI-(S?*w2T>mYO4bKoZt#LHHk&f8@bNJhT4@W9W4uMF8jkDj+ zhCf@jRDU)jez-B-?doRY-}QmWmlIqvU8$NezaK*+5A<0+AN!?~G4I67AHa#;luy z<8@Xu>t%Xf&;O>ZE-8fpO1#1-y=9b zK>5XRAeyi`$^r7gS&sx9ANA+D@K{V;R$-RMg)<DncP9yz*k*WcpsJr8Qn3=ZOkfH0H&Y4fQoEA zWf*S?uyCsK3eF;@5y4%VeMc!2j6njA?8@@|jAmpol$hJu))Dz(91(5!ma7We=;^9f z18!4lLY9Y+QP!|Ltv3hZv=4-FLNZ6P`8%lXj-`bZjf5O^U_0LfJ8mrm&5Kx6N^s(B zcyV-E=RH}TpKyF;NM`6`J$@~@2G0#KG(}QZu8!Zf+lEYq)|F)FgExmJ&d5#TTdeBj zsDXptMpheqXl1P?1n=@Eb7)9>NRC^pVOw2E_X1}q>C^muu2|40`OT-g1)9KvEYFYE zgN`EG*jY9{xjfArJMCFR%7OK5XcNHzRl7iLC&{JYougA#v<$P zkJ2bz!Q-_pIBr2LPCC4A z*_PE#YnS#3n|f`x!x(K{Euu&Kjpne~dcB94@0MOb`@4@HEDu(--SYEopfYZvzpOPs1}xK6W{w(iSl`$ z!5-xU@t+Jce)m{aHP^M$PbWB7rU{m13;T8haxhLz@|k-3D@Qv-rf5s8=q5YewiVMB z!GnOEV{eh>7Ip`yrx%GsmM$FzH);(}y=t(E2fdm{=xi6**Glb%-CK2XVok(p)*i() z&ny^}$vpAD>h{uyG5(w00IcyYAK=GzT^%g-?LTk9D5q$^=UNtx=(w@2J;HTKS}X`jixdIh@xlOk{L|7bc1Ncq`+Ot(zLYtYImXx0x+r~D8z$FW*n$5*o;&Qgaa>Oal18`;p>)*p z<2wv#VY=(SsRF2irN(|%9I^U9$#9LpIwbJumpGE?h9_I@lCXGV*t{-e2Bgxf4$3Q5 zMJ=P;$GZyTfy+isMVIm_*9;V^03M+6HP~TA>|IS1HCwgr0Y#c38ENO$j%N~5d-|xj z1=6flnLIwozxIu007y(jD<>GOEaHNm)@yPr8v|)|7RR3qCNMpJQRoOPF{W$uCygYV{FzFL=xb}5MX&) zd5kKdK6_?VS@NgsN8=2!Hu_q~hc!Z1_R6x{E6bj#a^r(6Yw!=MkyuE7 z)YrQ*U2BE|whCt%6%g6*@ZRIl0A{qPcsVKEkg%bmz5hK${QERc7GriW#*cw)s**uq5t z&iRkn{0#(AKdjhH{D5h78KX7p*Y=x6&VeH>;)~ifD-^Pc+=fK)hrD6_Ar|CzES+n) zxAR2OV_RMY-l|S4T(2<&?j&Eq+FL;Py92v3aJU%3+~iYI>_ zLQ3EaTT%%u%lhD@RRm+F;UEmZ^Vz`Bsz^=OsC)lP^=Wg>7Bb{tG8(|S8 z4U!_QP!eb=nC&rXN<2-ascHsI={$g!Qw*A!EJYt$xav?m3)mcbVbR|Gy6tMU6Qu$1 zCRMA~vep3S*?yK4GnXc;wj%}A#?_tMwC>!iCCt#7TU);G*0N?HblZEJAE%piH4bD& z0Ke(!iY@%Fbj2=#uGpoI>FQJ}S@9SmD`2?slDgk>{yi3fW%gY4QKXwgV#>boJ@mgbAPDSQi&INw4vj*4Ao1i{&7mFxjq|!H zo8T5DVQEfB=6E_pNk&HOR66HdK&7C7opijJOSA2Ci98|7-%h}mvmx_(2f<8RLnERNyBCruiTQ@#xCWetPnmeoYT z$Lfg_NLfuU$}LZwY5_83+qqrWj@{~ScuWLdcnmSchg=b`Ts%fONGc_nVsK~ISwWcs z!L9#*jfFTKEEakUt1^~_x^%FNpW!?1<;2$eOXtp*f`3!PL{9SAeT^uNOWXGDy=}0= zG)4~PRw^rplJPI`6MTB_;|+&!P$Vl6TYDa{szI-hjNOsAU@S7o`5=khFJy_`7{R~f z;VR;85R!HE8N_CPI(9@H5M@!v<_K1H0|h=sAiz5pRSht&?XDoEF*7R@F>C(w_Z}@F;`mPsw=QsrH8(taPAek$1Ps$|BBV zOGICK!^Wt@XK*C{Cn9mFI-sv5QT|mlQlq2wyB1-Q`_Ab#qvs@yFYQ1?L5^iE><9gt|u1)sB(Fo7liM5 zNlN@e!_TTPpGIW4^=@M81;wC2Xh`^MGn3-t#*9Sjl3%I7Yq)N%>Yo6I-4hDcR{j)N z!c+YfVwJ`ob<+S}j{>|KXtajB^QZ->n7z*r{;6QTJu{iID%JSqPgC`BP50g4{8a|+hbK2Y)b7s!=-{lEoleGIVAVeM6vGXv( zR1A;tRxom1i4w~mM?I6#|DnxO=Y!XD0`(f0l{2T;jU2&`!*)9w?5+7qalS{>83m(7X5@c z^k^{XD+Yfa1NO{{LI`<9LdX^fA)`OYAa8bjE`zWf;LvPpa|H;g*e)u;18#|%y^2J8 z*b?j*_~p|0i;v#V;?V&18oPw-X44{RqmZc?xDNdO*G5BFqMH?RGbik6mEj@m$II}F z*flbuS^Nl^h1X%v$c7euwr3PUi}*swMOCmdu}umaBnGhwmE4WoRv#bhTOYOwj<`|S zLEie9l9KQ}reRUGSDVh=){gy#(}>UU-FuHY*UAUmZf`i#F?ou`>hX!D>ut2avTk{A5vxWGW_1NA$$DQ%=#sMq3E^t^=a$p;L7eV`AN)Bv<@3Ph-A*~83j8xpr7q$J0 zx}ta%D)uu9M6nA5g@ml~?|rE5C=&PFtiJmqT3T4E=eF)V3@kHr;cXiYu^15}6i)`U zleWlUq?(}pyX?_A7%8}p%kH}FdPh++9!a5Yzl%tHhzC<^jPcu% zCAtlY?9$$bZ_TJgQwT^QTJWb5>1gcKtlfv5`Uy7bC)5ZKATn5&Rz}}b{;8;p#vaY4 ze%PZyLm?of&jei1K#0Qof2fbkwDZeUBkp16uTUCviJd=dMWWAKAd7Uho^<=3f}`;% z?mq%T3Jy^dgu@-@w!VhCkBfgiTa6dK0io~@5;Z0PgBrxvxuY=+Ru9T1n zPn#(=;U{yZKy~j7s`EskvUlmI&gzLWA5NiZ^Q4(xd%$Ve_7lj;FxC2 zqxChqoHpS#l)46~@9`mO+e=mN@d0^yqCjw|^G=70!tSfIJ|>6}ZkEY-#B65@t&R`v zgxA~#Mt?zS)onj-N!XxY*!c#F~Kf9R^ zt-<#`2v{KLOl)8aKrA1sy~XX=x!l{`iJ)!_?E7y#p>#^&Uurx8h#Oc*XeNmHJ(vy& zl-74ixe$*{yH6q%Sh>wU?M1g2ie7r;}qCm7M5lvB2 zqa|DRXzG$h4Vb+5IcOZ;M^Nu_Q1ARPj;Ix@_LwtmA-tQ4I^X+y>wGsAb-wpE>m010 zMfKgxf|X@`SIcbthn8pkye?W)@3W@XMT_b^78N?je=?S8Z45mNpdP-BfVtG_iTJFJ zWa^_Qbzvq`A3f+JX7Cnfo`$-Ndp|~rhFS=i5WELK>-*{&i&wB9+`DKwfW*aX(TO;? z^&Oavhh-r;Af|EASPBsQ#TV|G#=`lCjlTJei*j(2H{hYEtl3?Y4hr{@F#*WK_E{F&> z!SlfA@@p{sCUds8-)CP4C(#eIjTPZ;XsibSh-J|hPDAL-B5B#8KHa*G82C$9=ZG;F zhp6%$JGZK0D^2H-8u9Y7Da%f;a>UKF99y+^#YvkHdea-u3sL65Uu5v)GZzCd4<=q% z6TOLzH$=Z9=)9D+@uWn3He~ONA&4^jW30mnb5T)e-nbj1GpwX>(8@*2DTO*x+1NWf z8?#f{y^YorF{*dpctR>_sdw353abo)G?x?_VlF9K=H4asF2Z<#RiugLCA8gcKaBeu zF$?=I4*+V}OkCt=7XIKJ1%xI=7XK=Z4}OQ*cfSJey*k4Z%~IP z3Ug;nxX0Vu5ytN5$?#ED7B?(E=Ey=ghb6wfbgsOD{q(UR`$sb($j1MnW?Euw~eB)VERv}D_MsA##_ z4r%$K-re{&n(^}Ph+0Ef+4_B|`(aH)XT?Oa>hQurI>87SBw)Wi#QPAUfCrI2$VANH zq>m7V&MenJlwqBLWs-%JhlINnZoj$cpK*O>Zp~Ajt%H5U7m=5K2uozKr1H$=>xSNi z{`YeOpNRch%lN?^2j6PEmJL#M-qS>HZFnN@x z+y>+gi#xEBEF#6Cgd-$wR5Abf=)woyQ^ue2E_lmUL24yv`Va?M4?&!)MlkMH5%oyG zH`*S|E2Aq89*L$;Al#NaP|u$0XW2D-%esB`jna|bO>4I5+o^eXXYCGc>Q%4}(BtII z39Gj(aU5U2@z6ONtEaS;eymWZ3{-c8p&B-O0qqk)rW}CPHlSdh^XY#myfT}Fn5?rm z&mty^S60umNtIw|LU^C?DUj|5vH52q9VfB*sRdw_h0{|ma;9oeaS`*_hTPCsHWh%M zhq#6f=c6ffc}8L$g^J$z@Ib`t3RUHSx+f66REgf%O2jOdr&)Z6sJ<^gOe6o^JB^qd zV-Co8{OKIPRFl4A$q|1j`JmOH|9y>&b(eS%ObUb3qQqco!7qg9v76~iQGne~?1uX5 zZ|ip=(3V{T$UFDJFLoV8c|nak6xJGK)H2 z@dzNKJbRaTYxNWwT@`J{4;+tf8r~H~TX~?_Rus^xqNP>Q&{Jq9VL}@13^tkxYrfe` zx^6TxI61;-C7JWlO1f^e5@xw{%|z1269%@X(M;T9nayU3OKHuVru&}d&HT=?X)14~ zdzxW7ap?tIEMCy19J(imc?l2>NKw|9T~@_O7dwfIM^Ya>lJ+PrnUCU<_fcH(K8oI^ zKI+RnzR!3?zh`XA0bn0hIRJ{IYe#Vn3Anc$fB}hBIe=lLtL#@c*bl!@)_dW5TtIXY z$^}m3xez%VtLedWacZc5^&1HsMxdbju^GGq)Z56e0;gK+kQ^o92J&%H)|aNxENGzK zn|#J7hb5Ap?XVxyTKy=k)pX6<>PH`1O;=M}jk1Bpqs-fClneayKRA3HHo~?wp4ZPmVOf@;2*Prm9Ve{(gx$p zZ}_rXuPO~aY!MyVJ~h2R%{~Drg7Ok_5(lfG`FV#etTkM8*jL&W{W;ms-tux3wCdTp zV&y)!ZI1lpr_1@KIBvU&iF}Yo@)gr>%htC~qpx0lYFk7O291|Ha>8H0>Oo$ww`{hj z0z)R$yf9?vMPg%M5Cs-vdHDgv&gX?;@*z}t?8b3*u68!Q|HWztOHU26ZodpQy=~)BUa6ueeIfg@;!tTL8dJMjls3Y5j_9=5hT{C9EHP6h4d{Pk<7i zA22Gv2k)u+g#CDtdDuHO|2j*FmHpT5wzX2Wo39ygzQ+D?GsCP~ub}A{%gA}h{Zu-S zt;pUw58FE)w4bL{inLg-#Fsr&=h`@b>PI=CJpNt(JdZ*&{u0!PfItdkr(La!c#cPk;O86t zB_I)m{SF>22P-gQlGr73?H`JyQRoVMPN^>l&>fBVTl4|K#0G`;(+{842w($ox}M^a zXr7Uk_aHX0AN)@79V`mzFks=PHlsDMfu zz5-%6#CZMqhYF1)glnmD}tf�M9?Eqi7M`1a+pT;Y0(~#U59*c15>;}`c zp4?pbz0E88-6jilWnH|HSR0lsngGEDZj_$y5meFyh&F8iaTo|h1~~Ym_;|nD(D$8^ zE{i3WyNGY&+;U1s%!Fv*xmAHp0Yi~} z-$b1`aPah*dIu^yalLZAdX=45Jf~GyRtQSKQdy!XU<-=v#v|+~C1QtvNi!ARP86+2 z57I*pcQ9_k$>785w&3$Zdfl5SRsx#7)b~(vdbg7$B5!uPPJ?>(aW3i8DW;tr!Fo@l z;KW@QuNB)o6UU7mKW@UI0hL z5Q$irYnSzC&t_`tmMvZDw6drh9KDMAt`%uH8hTZj-KmB)aYlx`uc32fF_4GrI0(&^6CNblnwn&7GiY_Ejoj zv#&te##e*1@pTF~K`L=4gShFNN!`hyZV)c3ga+{dkTqzU2pR%7bcP=YnrB?1@o=JC z9!``y)l1v6Kc?*_M8yL^#d&C@+5|4r8pa6xc0X-AJCIT~v%{;~GM{*|)v+5%)dFp*7 zWh#|wxfSnAHe0?=Wjz)CPG<3%=N-NB6n|&3E_Q<-MPP~M86)af<&92>`grZTQ^x%B zc>Yd3(K| z_Y41C?k=83e_iad!lg$FeLVH(6nf4j^qhA%<>}zhsA#Wtg0&=Hwiw_OVBw&kSy05FVwCV26{eL)r-9CPv^<+6WpqQ%CUVDR$f#!3Sw0 z*r6K8C3OVN`*{9A+6Wr=KaAi28o|=W2oCU$VCnxhf;gJ{uI7vVRIsW^=I3&p{ThIR?p+!#yWt6=JF!=Rrz8&et0rLcp8Jfw)P?E9)Uv0XgR~ zU+it$1GMcja#EU&!?%BJT&lw02Jm;b-tm39pKVFP+t?bF?eOFPCK>Z64PL6na^@`d zBG>I_&u_!24CawpZg{KsUURcR`rnWJ!Jn$tq#sXuykO~?oEg7C#BN|>Q{D( zqjIMn-8**dv23-2Mb{iG&l}WtW*>W%`t_?ggvCgn5RlA0D>LYnCouvu0_Jjt=ta)*0lvfqKw!92)Q!3YM*W{Zn;pj>FRoYMWNdyb+oR6oE1@mjl@V3N`k<#a3vy_;=>9|BPN4RXk#o z6qYMxsh<2)bf;i+xHaj?J*b)O;YCjBo;yJ4-mhMcta$iGdt1qRfz0_mr}UoL54ccW zJNIwV)RyN&jW^vLH~U#G4p`T&wym4iR%+OC-LB!ziv28Q;?LK)2^H4UYgeBw8MAN% zP^vDhT(w}^F58nz$8#=r{E%QNx1jy{!#4Q!ZlrS)oL4rB?&_i$iF4x|OM9;yxP92o zexWQ=*NN5o*?N!cGh~3H$D;Oe&1V-+2o;%DOgx!r3v?%4OJcS5Ur+MAm~?#~YnkNN zPh<00PIcXg&P#r?M@r4xw`=YcA#(F|?Y2AOr46f=texp>6k{1Oe%SCKxIbv<+!!Yd zkz?l0iNXDOb4CoAuj&NqW)+s`qvYHR<&#X~$QV!%{;gTNcfWUAn>+ zFK=(RuDK(hlmvkHcJ(; zDT&pQmgcf-la@TQh&oAZ6LtdwE$vGkel33NOTI=ecCON&x6huv{b!|f#lEjt@q33J zyko(l}V^02la-nmCxd$V>Mb~sr>^1*TJ+BNZV(_LXr zca@pgw5fmZ-ov_dwuy!^+~T3No;!8!tXYou_*E0*BjY0{c8-h$9xD!2<)Ns30atH8 z1`v)Qw*u(tAJQP=axg1u>RpTKqA1URdoDs25I}Mowv`Rp$_8)soyf95OOy?;Cj5$u zKy@g|@w+%M!oyhcm-mvcCOPZFpSDtmGWM!97H?_pgk7eC91V;>ltroH4)|*?!%v~6YwOo=!0NY~uj(9EClA5qhqA_cn_i>Y?psPujlJ}vU9NYZ4bLShBKYZvU=id32wIe&F zuACN)*Y{f%Lh&JOu)wU$IHOY_Jh=qF;;^J~r1C?zRqonR5dkpDItP{ry)?E+! zL$5Or#zDSqqgv??%e1)3aq%`*bia-`=dJ`UT@w+-&GrpgwZX=kDf_mxZ#tVWW-mon z0N-N%O5KGmH#7%C-mjgz)~{h}gyY0sDQV}zb*r68wJeAmR~vyH?v*zttXUcFV08g` z*}H!iAYg+F+)ir1^4?qfr@NilP^Hb=}v?&MofjWp_KCyUgG5WHE4St!X4;zg1LZrQ69>-M*J0 z1~`(PC5<6G={p07rt|Q>)RSdpBs!A=bFdWsQl#%;aLtsA)1}h~0ot;}HC7viSzzZi zOoE^2Pa}@>BEC0H`b{sHn)o>fWj%QmG>b-K?ymA{? z*gu*__Pn&*lDN!YLJDJwr(McK`ubh z4U)vRL^O#%>4=iwr0~f&mfOz^P@z^*&6UI?lwSK zAaZ_QhBB(oMm|-9om5ZWSP}sQU%_^5?Zbiq>HSe{lq7Wx+o@O^uSp(_#ncgtsc{+2 z+F)lns&+mK*H2xpn30p1^Wijyjgk{Ec$q~FP$Ny%3GaSy_fLb?R&LAh?g^2iJ5#l{gxaFKfceLX=3I8UC{&d z%$fDfS@_@C->4g{8Jrn>e0?(e1p5^BDdkhcr>;*^pSeB@e3tmE@JaGH;-mXq_RZpJ z^$qte?E9l{Ip3PTvA#!qPx^`sc`_8pFeXEEhQth;GHlPVJH!4Ahcg_@@HoRi8It{S z`xW#n=GWD)mtTLsL4L#hV*C>P*7T#*7&=Wz3o}B%>o^fs8dXw#~RaXtT^&X!)5A(r8mXv=iV8p}q@Wy_zIN0zsicTz@4mF&{j zQXc6$sjO5{Y9O_eev`ULkL7Ig1UXJVFF%x@$#3Mh{)&H~f3UyiU&_C+e{=t#{uBJC z`fu{z>3_yw_kW+sFH@mREi$#w)IHN5ijVTO(pnh|n1{v6YGs4+JfLhqlYl7!^8?}o z76&{F5Shzou9CTW=24kfWImetM&{>P%4VsarFE7?S$1bRndSE^H?q9UA_Bt#a|C`J zm@lwWV70*BfujN^1WpT_9k?&>c;NZKi-Ddme7>-J;rOEE7rnn2^+oI#%fC4E#g#Aa zWtFljSwpgZnKf_LB3X-Pt(vuQ)*e~=W*we&eby~mcV^v})t&WZ)^k}eXT6d2udMg8 z1!c>T?b~emvK7kKC|i$gk=cf18<}lfwi($LXIqhNeYP#x?q+)*6c7{?R5qx5P}`vK zLDPa_f)az41+5O+5VR%eV9>Fk^FcR)?gu>$dSkU%Gg~!lK5IeiFV?!&#?~n7XzMKN z66`~drWS^LQTK1Uii?grEzA5{*>`B=VWj~(%ZuW=S->Q-tpk`H7)vo4Hzg3H>HPtq1 z2erF8NR3is)I@cqx?bI)o>2c%AE=(-jKP_L!-5^b-v$>6E*@MqxMJ`x!S#Zh1h)!q zAKWdtZ}7n2VZq~r7YDBhUK@Nk_E> z{W-K&Xrs_hp*=$Tg$@oK8#+03MrcfELg@0)wV|6rw}m(A%N+LZ62I z6Z$sHFD!GIBP>r?!LaYcN`;jRs~q-ASnaUpVQs^@gbfLs95yX1F>G1bwlH_tsj%x| zkHVgZy$O47lWbXRA+~Va*S37NLbmU1rEKMGRc*Cw4Q$P9t!(XVooxec<88BSi)|Zh zTWx!7M{E~tw`~t>Pi)*S*#qoZ?b+>N_8j&+_5$`|_A+*ty{f&Iy}rGPy@kDly{~5pzx95c7F<^bdonxd=!8gB2+p;lQ5Sk@yRf5xgfLdKCuLK}TlLm8GXsDyrBUF5V39X)bHq`jo;nzU#2(v85jht`t1Q$TQ$pK(h-gn}%L0ZU@z{$F?R z0$+Ls%}L!bt_8TMI(&})zqj_MOD*OQ4~ed z)TpAUs!`OSDn`{9RaI4E)Tlb)q`cqf*_R|8)0y}6|IO$3f5rOl?^%1Twbx#kXRp22 zv!1oK0JF>oQ$OnF%XU4E6?xO>%MF{xUdp;f{^y|B1VhqK^l%xUm`1E8nL1fq@+)Tg zAI;JGE!;X1I^t~pdYQW*dwu#6luAk?uMxpXzu?N4IDKlie=ohYt@SO3O4a1dm;IkE z)<1gg$%4L7S*~uWPe3mVrmmN}KHG&>&|_BwDwr;udN70Tx4$dSW4JqdjQuCP2K260K?%&! zRlN+=&})`<>18N}UhD70RUY=N-{3dg@gAe}J~*vCZ@PYa`y1nm@6AA{$Ef9*>oxAC zFZrJ+OB!7;xo!ludZ(czdwSgMy+*3Hw5@}pDxOjn4mx_bAlzmwC+*RH$9`DHO817l zAN3eBVf}lZd)1QVE9d*(dtU$Gx%?>;BTj^YhJ6lfXos(a1Km1}&9U=uyv zKh-@kCoAg(-?%(|Twd1Vm5~Of`e~o)j$ZWI{ymK1*W7{oalL(SxKg|ZRmii*-nd}{ zbA3y@>R-J1@t;mc8ixZdBJxd*zD4G{dal`Tr<&I_3S29eW@k>!o}B3)*`oj}azFf| z-?*E?;Qw27L3@*_ny@~KeTcsH8nEL(+G9NJ@fk1E9;618sI-76*7R_?sSz%N^e~_> z1T~E7rW!_(rG|m;hQYDWzsO+A4y6?@0xsGV~B7X1fSp1sn8(KXJV}5=E zL)l9h%3@~rigD~;haq)Qh4Kzk&&3j`iE*_0b8hf!T89a^GR>m_}Ea7vFreRqqxdJnhp z(rk|beM)MBc=AC%PB(s~OhScMqDNvtJ0W}OqNQ&xTD;W%XV=9OCocLoxZho~w!pU> z&3soN+-nqi*@V<1w0k&P3J%WrocnXka zM{Vqfh8g!jE&K|@3c#A^gJHp1KI4-YJ{Z(H(n$H*-Fx)l)aQK5JL)HwetPWd$gkYS zV!R>M38v|Rv=rkMH1hVyDc3~jf4Ry^W0?a9ahqg{c1kq*+7J6&qu2^ZSW6&bJNow zM)3rLKX`8HKF>{0L@jR`dJgSIH5)x)jeBG6yV+}er%t8rN=nj~rjN=`i%NH;jmphV z_a~i7O+A&QXQ$_mN{dW)r{#}Yn(j+V+Le0hl%Boj-Q0~)Yg`-O&0o64e=2F$uB21? z(lz<-Zj1~LgCgx*?;0}tvF3(19rN2?m)Oky+6BAcSMP3L8{aSLkxBbyF8UaFw+*Li zp<&R@9vzAv@)kV-%MJYoWse!-$I@5mi3Og5oTVK+#(CL7&BeeUy}`FF8#Na>#7R%q zTkpW^`sbhQIpSZOGQ~Y1Gjqa(Y0Fkj^cm1n=;?`Q@MYWYsquW@_R9th+q7wjZ|%Fc z6xH+;)$ro~mfgN^Qq~B>cn#R2yJ?U{#0)Z)1sjq*Bg(Gx#5%gERm(0Hg^mbHUIgC` zyyCss1G>JgVFI%`~UF5f(v9G5upX8hN?DILl&knTpRE74ya#t|&rW&ydAIge% z+KMRo*;&EI&-o$3M^xL%s2R_?2l>=S_ujtVE@)Pm-~ z{hs3cHL~4#5%X#9nNqO<_F6dWfqE&a_L^ov?`ke^``Y!p_eU=8R3g z_k)1nQ#a)wc+5pYM*ezRd&Azdu&BI;j9t~lqb;kWzIw*ejPa4d1#YN^_yUtsf|E?P zz`b_as<#*TCLPs#PZ{!fx5(h@?vzg-E!?tk+4_~fF)KGt+7eax>8FMM!0YbMhJM_8 zu`j$(Jr$@J5m@Uz>}rl7NitTpTATc4S2l?ek-95B-tOq%dF^f;AHOU0@@2bQ|KPC& z!;oM_JR8#EobDWs+gj!ht}Ryd6l}^H{DV8Nwn)(n-53r)Vm?Q=yNUl^?*ADgjsprwa59nh1P9i#0bi#%A|>>iJh zLBBg#ZObzq1Jwq%4C2TQZLZs}6=maktTck{A+*@^%PhQ11-C ziu}6`nw*-AF%dT4H82PK2yCcNs_-q@1hSkyU+yT;VEdChZj4@>MVLHEYaf^r!*lH1jvB#r^1&(+=cx%J9HU3Wv-rsX9 z^39aV?x9(uhdk};nl`Lghe&S!n_OQX+xyir*h4Av2Du}Mrz*^dqpjkNvPxm_^P(cR z0UK6Jio81Q;#Osuy-xc#&88m`DAclQXmT>wyeQ}Nf|{qT!DIcT}S1@&~0(y^hrpz z+jKK`ONnC>-;~I11)E$i}9U^_P zYt374ty!}e$_73IyRvvyB;Owm9N&$pmEIh51j90Xu-;@^Xn?j5$`-l?Y^8oCQW@q7 zZ{6juQtn$W)`7}n% zfeToJUVsnY0R@DfBq#B;#aw1*(0WWG;;9jn$4~UH%^LmY@Tl~spU;`(uQ>HhGX3ku zcAS;m1#8w6yt_7iq_4OVMtyF>GI8w+U{^q_;aQLZ{a~`Po$Rp;FJD5f8warF8QmOu zD69X9SyU_>uDJ1V<)We3z3mZbC*m{6BgIAfiOQHMYE-luMip1<;Zr=}ojjvm%{n}q zOgf2>$Q!16M?eocv15m(G{f!RhSmjx<4?F@5xTRUa@ZVcr=XO2rR@E|Q|P|X=|tk| zP^sxodngne<`*TXG8!&g&uTP*5n@QzjKBj(XJet^I_x!i_V3>_bx6UETvD<&Zg{gk zLv#4M2fGo@)s3Pq?$2KNX!oBY--b+iq$mmItTtd|yBK2^dM~+^TN71D;s9TaNE`&- z^R?d z{n#ByE$XMkEOIy|OS^gc8>GX5I@*;QsEEHx!AiS!1uJ1Yol1dmXZskmPWducDjK+0nDBRBJD@6@FK9nqG z)T=$Y6*GK)-sm;t-$tS{V(G7e?))A~ZNJBFz_4$E$N1*+&%Zg_>1b1bufQN9@D~yS zZDHalxEUr=zM&5B0-ngUO9Oo=#0rufczX&&(cmdC&A6HO1b-|INUw1eRwJ;{CmA?5 zXjLw%{?ACQs3966Ci4SnMO|Qgg-x%7V+*Q_g~lhZf3R~OwPh&OBY%ZO6^|Ra`OoD& z`)bJIrFkn?V0gwQzY4(`Dsygh+%{iM4%6s1(h9qz&x zIodN0I|E2W+!QE>FMRkejK#lw_8Z->n6uk1EOYJD9%9g>Q!Y>BVYBL?E9=dTUY8m@I{<^}s&@c@Z#A z(gmBBZZ?9?V(qkHtqa{-`D?5Q#iya>uJ9-}s2}`(GM>^Ez32r7E%`0-pnmh{iT&7q z13JX8SsIvGXcRT^#1_c(cd)1>+}(?{MC6 z?QxGk{QdP~o-&Fqm|qZ}9ynpNZ%RtwjO*Be9f!!M^*2~nObup|$Jpo{i+6^imuU~J z7MSTbibA|WUy6ar|91@RT^ENNHzo!Cj!Qm=N#5s>K@4Xqp!Ju>rHhIt8G~uNc~sI3 z=oq80^UzGM8rbIuLmgpOy%7lYQf5x_$e7MAdEm?RCD z>Tq6Fj6eX3dNAPo8>t2uyWZLKVZJZ>pxz; zt=!_XfwmRT-a2hO?+J9ljSd)|HqbXY`tKKksVFmAPLpH~ z!MPG*1EE;tguy-R5dAWTG1*9k1H^hf{@tL!hrDr6%E-x*LwwF zKP$xGu4g|3OOhTK1Cs@u92Pwl?kKFd%YfngU=v>K9BhK-mp*dTcr?VKN+|}-X$96s z3`AYr^3an#!|r`ifafy2)+lahem{H+L~TF zjGjIcHCSo2ZzrC%m^mwgrVXZ=U+HHII%%>_?rwDgCxb}t&P zR7eaw2zEso_?Ef|PX-9`qV|x$M&PLT^+E$RNjn4?hj;9sa@d#zTkGiHP{Bm@u|gTW zapgq(Zh+QWuENDPJQc5?7uTjI(sj)DxzMXIviSlg9t>>YQyJ|KE&0TLgRHVlhu=+! zuZK6)fX9f;@8p??%6iok-q;&1@K3^pG1)B?(HXznz&(UNDN^t!MF)`&TqITl-x2$P zpNWIO!{Q5Iq4WzWtIJxz2V_HFW7!ngTs8-`l>LDN>HG)X=vYT7lD^FoYj8R{vo73Sbt8a z`pf!4p`y-o{C-*}`a~VM(I@GXfiLSX!{-%*P^>!kh||h0p|$VWwU3B=YI4R{QD;QP z@G+v<*ddwYMSG!98@O|a!-tjnB}KVXzZ4NJ5=F>E{W`>mfG2os0(=PcmL$yiO<;#`26l#(Lw%j2k0cF?MF` z%Q%cNgE5zJ9^(?mb&T5>_c0zvG3s3A3TlT+^?&m(UATl>gosei=l{-MRNp>PTQm^O zM6&1z)vmr`5SOeJJ?Kvn8)&0%wyAI!UX{*n_UwwbOhOasCjHz)jHlXkFC)E z9=x3tgBlAH>%;?)J_s!#D`XfPirLJ;r>-xr`Z#MqwCp6gT*4c^lY_F_ZBn z1(ILPQ(}Snj8iz|6h8Y2<6OqBiU(o3GoQxz5r0%o@^Rd29OXeKC>sa` z`6MWi#xjQeA7K9)%xh3Axu1RNvrm2IO_?V$k26vB#kJ_4Y}K<>8hT}z*d*eF;!cKZ z57z~*CtP2+0dPa%M#7DU%Y@5;%eCB09BnrTe1Q<|NVpid+CsWp;D}OXhqmcn2e%P! z3*1iUNa?EXRftb%LsmQ2pzGQWDva)EcdWZk=-JS-?gnto_*W};A|2t^)?w`D?&$97 z?!{+_rJA8Au6q!07~E(+8%=%=o4_oK!%YPeo9-r7He4O|EcZO*Dv#p2=b5RyXIbGE zIqB7LFE`J+SDRrFVuQ`VH(4?3xVPE9l#1oM>n?1sbO7>X86I)@e%YVHnapkn zAwK?%>xR^{nVlZ$7colLG}pQ1hZyk`gZ@GqIjot(l5FNaXV($78{GMHHdq>^U(g^Uf!AVz;7*>b+5 zz7u0b$PzOzAuCGxtu=W_L5R(^hita|cH0c`W>H+^4{<~Gndiwbbc z(7hbL&%^Q6m=%(CPM~93JZBM_MbupQpE2`Ddo*ce!=z!3n4jajg(iv~pZ|Hc(FVn77oJIXo z4boZ4m0g#m{HRQGC@$4jXr{wBJ@(5bKmHqU*IP+TG_T9G#dThW%{1FC{N~uTYUdzy z0a9GZsS;btY!z@FvyGu!LU%fB4>3-KTN5$!x*;=g<^YGIRE{|8xWi5n!?W_YM+i0P zNh8I=Ci&whyNq{r0~=K36;iEE!pQ3V+;0gp{B$CHv8bM0=%+0 zT2S|a^C$vi8uD+$Dg4Mhj>Zy76@gKWHA?Bm{!Nud6ieLBl?6Z^z*P8u?=L;hH>Kq>U*Fs<)|fcIp)#s2fzzXj*BGRKWmn;=XK^QLNb@TTfO zV5-^$n8dM?I95C(zZuGSP9dISz0CeUaL8ITPLmHZKFa=e+26!^>|c-G!Q~h1A4fh) zvdL8%Ez`(X%481Nhf|2-(OP}>F-L0&943K%THL|=wJc(v3yeRqe?!I?Ml=0y&6JhX zls@G_e1GR*@GSBXv-w(&aQG*<#IAApTAZs|oacJXA7K9nIHZMqHqOEqkY)_?u1W#; z4|nj5M(*QSad+l`H|My`Ikf@o-U3nV4@L}Te68rd-Z19%+rdXc&U)a9}^Hv

WWQ*w;9HxxU&#S>P-Y^oDaBd7Di3g&MRZoSWSLY(DzGFlB_hjCY06YDhcu;y zm%cB`4(wyf+79f~j(m_C{3Ll=e02NY|k2 z+O9|`h{}qZ8a2IUV$DQmvm7?hVR;T)JK?a? z4m;@Ax`3!9bPTeQpeiw<*G1(VfGjIQc1AF=3~C=o7~=y-=Yeo%wb6!w_TaDot?AY`D`DY9UR?{N*ru#bXsW^O=mOcY;^WNhl`$O`$f-i*zD-} z(fOP*u_X>$;jp#L3d)4r?3~^1u-y*Z=deQ#JLa&H4m-o_e3_IlIcKjr?1sZQr%@B4 zi@l2N=M5p|4Tr1but`IyRt~+OM+01U8Wx^pZbRXXK(N3GR zbA?>;b-g`N=Ujf?z789JvqS0Lyu?N_8}ImKIxNRwB{6axznNeQymQQwEV-^-8dPd# z{=lpf0^@S=F0{{jm)eYL!77b1ekG|m%)VdmD!aD8W|=hzHqT+39A?$8ca>GESqQhw zIlIka2OW0QVJ94R+F|FIT`7};>(1F*4s)(+IqPVuA+fnUPPR&-rj9Urk-sz1#%?=lp<@4BW4a{n5W&Esu2|ue}`aE{O zgrC(f;b-+rpT}38a!)DyD%&jT9J4EBQoin-z2z{gog$o>mwy|>ZqLZUIy)7+$CtjE zFWNbKmmY85IZDowIk*Gs-oUJ!QmL7#fLUdAml#~mPPme|)?K1)2>Yy^`@5%XmpIN| z|&@ z*UMq44jbgKVGbM34E?uMDifTuSq__OvyyOkV?M408Z-E~7MNM>w2V~wO}TbgX;vb0 z{;!i}cfa$0EyH|ycB^B?CCQBYxo?qkb~(yR5wFA(jhMLmWK5NFc+eWG9mMQD-oc3{^DF^>7CrhNj-O?-Z^KJ9( zvhH%5Z?D4+I_#*!O8ibZewMUAD(4)(iw;B2#g(#f_PWDL{A~HR&2LEt-!{L?4(AVZ zm?gPzwkrEwDV=A(&k2W~L09v~`x{xTnavP4$qrZQew{n_x3kasI}`JU`@7q5YbKUr zeay4)>qpE#*kNg4{A~0S%iy!bvYAaQb9RPvb~dy5IJ?B34_pCP;9m>e?D&h1f}lopIQCW|zu@yXu_1;jm(x#V8I7aag#+Dmg5YSWHamlw)c;XX`mE z!DePoV_L){$F#ToV!9B6Ur*Do6zhw-w5OPLJ3|hi!4#PKWJr*a3$faoBN(ndzM> zlk!>T>;;Eic9X}D9X7~eB{7DT@f+==Vx~6%XHot@VpEBcjIBPM7)i(Kvm7>$ z!{wFnTf~0L9lyQ~qqwX2?1nOaCFzy0O%#qs1!he%>q9v$>sNi7?N@!5!}dDtpu>(j z?1aNkJM5gpE;{TAGmI2Ua!~!cbM}_aO3wPt{QcV)vBHiU>vC9_&7z!KnT(z!u@!!+ zG)kpcl~RfI!J)>0@pvBXV%7-1nmH`VVeOc8w$D<}i|tN+%y4asagV1_eW|m9=`6kb zS$RD;m$Z`&pYgr!>%&B zff&WasFj${4`xWo^5eMV7Zb^TC|Nt4zho>BZ{LwW-mXD^d=14+1uVp2;SQ^0Gy6RX zajiNBv&seRpdGIIQHPyy*lCBIbC^|{+s)Q>%80OOLZkpRZEPs}VKW_-WQ_GxHpS=TVIo zY=FZ!y&6MHr(9#Cb9TJLG98xVFefiHa>=j8Oy}O_ zIBWs@m)2MaB(}<7rr$c}>_&%`#Mp8dKj&=Or-mh|@pSo*pC2X9l>f_~AOGskfBn>` zu@mLDhiit|0f!x7cD&5lQ|x!v@w;HNsH_^7ZFvROhr*Thv-^3C%XY5?vwAI<)dy=_ zwk0*#5<8VxOHw18*+Z|CzM9=Han|ma|D2b98^h_Bmu*Rn99Vt2^wnxyb8^M9y+)DK ziiz=^lb?BS%=q4F+%6r?%rl?mJQFjo#*9-YDOyvbtHq#CT4QhOogUk-W_gEICRQ`r z4u`n0W_{56ul0VE1~!($`RBu#?>NpIOUbC7r8keqOUBtH{47y?lhw@k>gmKq_NhDc`~rE)|PP`u)YR8U~B#}PQAf= zHX$_3rL3Y-$T$@%H-Mz45~p?mwo!j#PAfx9jh5A{XH%Q!T5EG$QxCW^`zNTB6H^bS zmD&OE_t`qsL6X~u+Hs{mFIZRaPu1jkz z*XQfj=j%4*E7rgLK84{l8?z5<6iIVVyN%|>S#xH)DTi!L>5FANKl}mTOMOXNGOhXE zTU%kM1p0GMI`LfhN1UHH4iiUVEZwHA>Hvg{og59LI`NNr$_NrqZ?4X~1|chkD!&<1M7t7_U)lOyG19 zxGoa7781A?8gMO`noRNB0^_;ds&XyFb1lSk+l%LtH?^JK=6v?#ob=?p^=00W@8z$| zYcv0WxuqAyKDCrQT)^M<-4}DwK%t?wpLvQC4g0D z&^(iIcX|P9F?!j@%Q^9KPHJ%;yehRHFJFZokt*v@zFdW3JQsT&I>69k=Z&Tqbc`CUKma zsZkfloJ@MgYVST4m5RS8nSa9@8@ zW+9zfN_pU0+!}NE?s7P84&Pl4x92uogK_Gk2w8>J{y~@YC?Q|hlvJjMVr%v>^)fr~ zwOVuQZE3ytqLjPqb>3`O!?yvVhGjdP-LPBhMm#_dYu{LtDYtWe@|NMznp zc7l(osnmnpRU(&Fq7{auN@*R(L7bD$oQL0W+4kg|4B+qsxNHw_$`6<&$r_V!cc|~j zK?@NroKvXJDbzQ6<(*Xcvo;o1S5Xel6-S^#hI9<33vib$cMV6|6@lMIx+GblQ?lo+7|iLI>cP=J^jeXb=6H$CrspsD1=@Iw-Ig&+)lVXaMT`-z#WG> z1$P$i0vvSC*j>ZXcBBbR^>Y>uVNeexVJW`lP!C?QLaY@9Vzbx|N5%C`t$Yie(C=08Y=^ zIJz#7o+!=fy0W%{UIHH)m&8%};7DIj(1#&4yY@0r!Zcc)1~&tao;vg4^5K@it$Elq~|CZ4s1XTLkyBErJNPMG(cd2%^~*K@GM= zP?K#Dv}Riby;QPA@EF@77^sphg5hk7V5Ca62u86jg3)Y?;Ayr+kioVHa@ZEZi?BuT zo>+$580toKlMrl`KxL~0p=_1FV5_f9NCAERXD52-aXd3Giy~eX9*uS2iL$NiDpTb!IYCZEdFILGa)aC^_sXNC(v`6EP)*dr z_9?B!!{RY9M2r*9i@D+r@wWJb_z1Q7XYq~rJKidEdB5~xWZV?nsC1K0pyr;I&&n6& zYw|7muKZAbiZwwR@@eLmY(_+4ERulL`(3bhf2bHQri*#pVm66guqAQ=tK_eUThb*f zNS}jHXUbeTM=q4BpV{}8{(P#J;VR3AO51A5Ou^qObTd*;eF zn{3krN8|l;x}1j|xLR(KyU_biSgDe&4!@`?nnM=!z?M5B#6&Sg{9e2Ysk2^e z6@L_;i@%8P#ZTf6jM-F?H6Q~Xl$~U6`J@~pC&}N*m*rx)27UZv`6v0Ml`7f&h=E;# z7NR|DJPZ&cMW&c4W{EtpTx<~A#9nb!oQ7S6>*!KpkSR4~Bbg*S%RX|j94oUSJ?3M3 zpS5zc+>I@MPFksw4Uy`izGw-V^{5yqMu}&{v*JbZns`gRD?SvT!lKPz#Sh|VDX~>h zHOQ>SvbB6zJ|>4i4o#LX$XDc>@*T*cPvl|wm6a;lr-;R9x)sLJycwMX%?};6-!&4}}7Jq{!E>+$qqaa0_$Tsp3`8Z^0Iwa}u z<*Ra;TraoEKg!SLU*zc_L&jzr@r((Ktr*)ec46$r*pG22<7mbV#vI1!Pffh29>xQV zM;MPYo*G8!oMpVoc$Kk;u$*8FVJy#Bl`)2~4r3$67Q@D;k1N-fu_I$w#$Jr6jDr}5 zF^*=Oz?j82m2rAn#*nAV&0@@BT+Xov{yNzp>+=85cg7F^zF7V+Lb3<21$@jI$Z%Gv+fcVO%jb{i(6x zYZ(g|H#2T$+|9U;@et!NTs9;8B;y&z^Ng1muQJ|XEGE29VGLmmXRO2+nU2GKF^sht z>oF!UwqQ(VY|q$*u_t3+#sQ2&(=&#Rzi%Yt1jcN}T*g_9^BEU1E@xcJxRG%i_faVm!-uf$=iqHO3;w+l1vcM$g2FjT)CP&sdo;nlYBK4r2qxM8;N(Z5cZ< zc4h1ZOemkqIEZl=<7mbSj9H9R8K*POVw}gA$G8aCr2KNm)r=b$H!*Hw+{L(;@gU<- z#uJRE8P5R|%U@)?!g!tW7UBJZ(Zv|XSb?!BqmQvBV?40w{f!u#F(xs#W9-b>ov{yN zKgPj~X^dkTGl0$R&t{y)ID>IE<9x<^#wCm^7}qiuFm7ht4s3q^ZpM9#hZv7Bo@6}3 zc%JbR<5k8RjKzc%6kv-AA&lXSl^7!#V;E~Q)?-XyY{8h!*q*Tquw{jwjC~mgFb-uL z$vB=dlQD-emvJWJ9L5C`CpKde@ku@7TE#=(qfjAI!y7_%9tG0tF| z4QyU%K4U)P62=vbYZ(g|H#2T$+|9U;@et!NV2es88P71DXS~FCmGK5+F=2$l7{VCN zScx$b*fJu9u{L8p#stO|jLD4c8M`p{WbDg0fN|)=i3yD&Mlz0P%w)`A%w?R(IEQfo z<3h%zjH?*eO?+nP#E6ZITNrmT?qNK@c!cpd<0;0oj29R$GhUnc%!G*%MU1xzD{G7% z#`27n8KW6v8S5}MU`%9el{qSNY~{9$9T~ea_F_zB9K<+`aWvxu#w^CEjMFpm45~bf zaUNqH<08i8jH?+pFm7Vp#<+`dFXO?S;Th?bk20QMJk5BH@gn0D#_No?2&)K27h@P> z1-!N@aP&_8KXsJ+ef<9fx;UrziYne=y?8go=b^hWm*wZj8(H;#5$103{!>4R_3KpL z_lmZ?#s8_J#G51K^IlQIyJACpy&+o!{~I{INAZ2#J0@~E_l~SvfG=EB+VPC^)l1?V z5@9XII*dFoYuPWX$3FLh%{Ya7MFn5FnjoeBsiVZV7Al8(M>nT)?-;`A+&hMHI`@tq zPUqf{H4k8KlS=zuFpN{UcPz*0+&hMII`@vS=8KZKcP!88+&jXOF!FQnNMis=)`;&B zVZ|6J+&fm{bnYEl2L<0iDOdM`l{tlb$10r8y<=5Q=iZSuWibar<#R6>$tm1Bw%~N` z9b0lb_l~ig&b?z(PUqf{H5c)foa*cUE4IeG!VJuw;|u;Go}=1=xsiSNihn|$kr(6@ zc|+b-TuQi76*H3YN`lf#X{U5idMW*2i;J`#kaJ@-M%_4uwct53DM{A|zhV8J=FlWG z^UNbOpZWK8^QgvJN7C9rI29VQe9W_s3#{X6^QhIfj-(re@R}7*qgiqKJ=HqezxP_d zNkfCqpSF%x{6atettSFe_Xb zYCVi2^$ZaeCL#Jl{3oMh&L8-!ZG(7 zixIEHnJ-a>?=brcaeroZ+F^e+8FHZDN}X{>;kcS*NnP)TRu`kaulK-lA&%W~T#O_9 zl_J>yN53ShjkJ#*w*dGeT*ejZ9?`Z3^_1XsQU2U`Wfwo24 zs%_Ig)IQR7X&-9`wLfWxw8Pp@dU^eRy@Fm*ucSxlmGvrmRlS-XsYmHvJzDppO(p0} z^hCWW+EjDBh2Bzcr9Y@A>8qIm;oE{J(Qlx zqv*H2l|Jy9E-Imp`YMkrsmc@R%l(xB%0Ok1@}x3Y8G@eulrjv~2G6K#)V1i}S(vR; zjBH^jBVa9YlrmZwql{I?DdVA^@D1u!L5PRMFVJ^h+sZACTcP2?-D!>-~R z$|7YkbSK_~mBwYta^)>$g|bpvrM#`IR@NwMm3NeN(5cv;)rkid!Nmiq(hI z_G$-MTKqyirXJT|f6jA7gkWAY8k!0|=~q+Kcl3eqMIYB(T4n74t)(_h8x5aJ@NsKZ zv^rWVZMZfDJ{RE=qE*%6vKTyIIHQy9ftfvvrj<}4%3lOeW;$!KGL(`o?;KibwW^g zd3p|VlFCx1UWruGVY3w1dX287L&HiRqrVQEP%6X%4)F?yK>Z`cs~kdlJpTt%Q$qKO zWavo5LieC1=Jac0uDlMkSK^`JQ4g9E4WN_Z15To>&Tt*h2e>#p_CdTNhqy|muwBg4@LMxc$4(q6@N zI*U*|fp&>AtgF)*x*^l#COpUJnN)gzjx=cbkRHTL^znSLR6|?SR;$0L#khB7D39lb z3cuUhbUxnEX3$X++Dtx5Z8jej4OS=NuWEDosA;e8QP-a4qf5)+qg%sn3J4dXP3B{$ zHieHK4ZG#Q-#}T0Ag5Ke-_dXNj`n-@m)a0My4j9qC4B9yDe7r2u%FOoSz+e!QPYO< zF+_Wck2G4*v=_}V+_Eb`*C|$eiG399Wj<w^!P-~<$ z))KTPTB6oeYo;~VT0ri%f?Q96+)nD49=cr9pmj74dUZ>o&$R&>UEA>9vKLxiN1=bD$m+^@ zU_-1NQ6K})qt0GaK9!I;kb2*V5XiU&kSSfzm%XTqhLCL!LBc$u{-XI%bB*x39pp_{ z^lU%su`zz9K>Bn;i;h99Cg68_$fEA(>D5ukP4K$|BvTJfYO$#CMEvduIn`5Bv>K@Y zruf|nQtMGjfSPCx&G5T3WLPgv(`un@G{^6UA<=qkx>g%41tWGyw_#{8Ey2b>epSI* zK@HL_4K3(FuyK%Q)wCqA@sMkgT5GU$$hRmh8LU3;i|$Ir{m|X0xDUDu75S&!tH?Ly zT19>-w<_{Uxr8Zc&Yg;UQLa?vhjOEEP880C!Z}d*>Iz?3;j1cC>$r9v>Xn!R)&=auis{U=f#!%kXN zped)6zhLD04X6JOvuvOhL?gYI-Wy-ap^*!X zz#b3;z2p;|@AJZ|c2YYDpE_He1MNcS;-bAmqCj_b4)R7Z^5k3iy;82iDDxEFpvvPt z>72MMVJLN!IN??YsZWYf^$m3~zAfW9j_(8Y zS!OC?jl2#YH*z11(6pmnv>K1Ki(cq(Zxk`=c6Ga`4vp;tkZ@G zElAB?+5rAdExI;jXm4#GeoMUzp?r`~`;ri~22_T#KYfWP2W{vf7zYm1)ASMgNPUz( z8sofi`UKju4lOl9pNK8ep3$GBGQbmpLgGBfUkOwYYZQ*ja9*^0+6SyX^f$XggL5$C z-Y{rCk4H@|M9nQ0%ke(^2WavhhR$W7IE{AIkG0E3Lw9o~G)?oM6}t{CVk@+XKZP#& zMfn4@acGTKfeyJJ^%JiaW0Z0mC54WKo=v@3$F4z4Wl>v$LLNGA9DzhoDDDrQCPZ2{D#y(|H1nPMg)}FYQ|g&f$I!J zh|zeL@IW5qnelM_-tZl!je_s17?V+I5~-W>r{G*4ipZ9qQd%e-_(4+B>{&@ZyqpgS zjqHD2s&<*KM5%5lQ?6x8wWLh#61|EtEh=5Acwe4RQWd%X?Xlb+0_yPB&acSzfs|F$h<9WGZBP}%@HGYBP`DrcIweZOEMIz7 Nq(f>^`Qi)v{{yFAbiV)q literal 0 HcmV?d00001 diff --git a/src/assets/styles/radiance-home.css b/src/assets/styles/radiance-home.css new file mode 100644 index 000000000..1c8c3947b --- /dev/null +++ b/src/assets/styles/radiance-home.css @@ -0,0 +1,142 @@ +/* + * Radiance product pattern "home" - the Home page hero recipe (FIXED, admin-owned). + * + * The finished Home page (Spotter home) draws its hero from two layers: + * .radiance-home the Radiance surface's wrapper - bleeds past the hero, + * fades toward the content, and carries the fine noise + * and tone lift at the language's values (GRAIN-2) + * .radiance-home-stage the hero's container: a faint glow layer (::before) + * The grain is the language's one grain per theme (GRAIN-6): the renderer draws + * it, over Home's colour at the hero's strength (PRODUCT_PATTERNS.home). + * Markup (see README.md): + *

+ * + * ...hero content... + *
+ * The renderer draws the top wash itself (subtle, fast; locked). Nothing here is + * tunable - these values are the product pattern (RULES.md PRODUCT-1..5). The + * glow layer follows the clean-blend order (COLOR-5): pink - violet - blue - mint. + * Theme follows the surface's own data-radiance-appearance (read with :has()). + */ + +.radiance-home-stage { + --radiance-home-base: #ffffff; + position: relative; +} + +.radiance-home-stage:has(.radiance-local[data-radiance-appearance="dark"]) { + --radiance-home-base: #131416; +} + +/* The glow layer under the hero. */ +.radiance-home-stage::before { + content: ""; + position: absolute; + z-index: 0; + top: 0; + left: -16vw; + right: -16vw; + height: 640px; + pointer-events: none; + background: + radial-gradient(ellipse 58% 36% at 22% -4%, rgba(255, 118, 154, 0.072), rgba(255, 118, 154, 0.028) 44%, rgba(255, 118, 154, 0.006) 64%, transparent 88%), + radial-gradient(ellipse 66% 38% at 38% -2%, rgba(165, 102, 255, 0.066), rgba(165, 102, 255, 0.026) 38%, rgba(165, 102, 255, 0.006) 64%, transparent 88%), + radial-gradient(ellipse 72% 42% at 62% 2%, rgba(88, 150, 255, 0.076), rgba(88, 150, 255, 0.032) 42%, rgba(88, 150, 255, 0.006) 66%, transparent 90%), + radial-gradient(ellipse 70% 44% at 84% 4%, rgba(80, 220, 180, 0.048), rgba(80, 220, 180, 0.017) 40%, transparent 78%), + linear-gradient(to bottom, rgba(255, 255, 255, 0.02) 0%, rgba(255, 255, 255, 0.16) 42%, rgba(255, 255, 255, 0.56) 78%, var(--radiance-home-base) 100%); + -webkit-mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.94) 26%, rgba(0, 0, 0, 0.54) 58%, rgba(0, 0, 0, 0.16) 84%, transparent 100%); + mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.94) 26%, rgba(0, 0, 0, 0.54) 58%, rgba(0, 0, 0, 0.16) 84%, transparent 100%); +} + +.radiance-home-stage:has(.radiance-local[data-radiance-appearance="dark"])::before { + height: 560px; + background: + radial-gradient(ellipse 58% 34% at 20% -4%, rgba(255, 93, 142, 0.06), rgba(255, 93, 142, 0.024) 42%, rgba(255, 93, 142, 0.006) 62%, transparent 86%), + radial-gradient(ellipse 66% 38% at 38% -2%, rgba(138, 93, 255, 0.068), rgba(138, 93, 255, 0.028) 36%, rgba(138, 93, 255, 0.006) 64%, transparent 88%), + radial-gradient(ellipse 72% 42% at 62% 2%, rgba(39, 140, 255, 0.078), rgba(39, 140, 255, 0.032) 38%, rgba(39, 140, 255, 0.007) 66%, transparent 90%), + radial-gradient(ellipse 70% 44% at 84% 4%, rgba(45, 220, 177, 0.026), rgba(45, 220, 177, 0.01) 40%, transparent 78%), + linear-gradient(to bottom, rgba(26, 27, 30, 0.08) 0%, rgba(26, 27, 30, 0.24) 38%, rgba(26, 27, 30, 0.62) 70%, var(--radiance-home-base) 100%); + -webkit-mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.96) 24%, rgba(0, 0, 0, 0.5) 54%, rgba(0, 0, 0, 0.14) 78%, transparent 100%); + mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.96) 24%, rgba(0, 0, 0, 0.5) 54%, rgba(0, 0, 0, 0.14) 78%, transparent 100%); +} + +/* The surface's wrapper: bleeds past the hero, fades toward the content, and + carries the tone lift and the 56px fine noise at the language's values. The + renderer draws Home's colour at the hero's strength and the grain on top. */ +.radiance-home { + position: absolute; + z-index: 0; + inset: -96px -12vw -220px; + overflow: hidden; + pointer-events: none; + filter: saturate(1.16) contrast(1.06); + -webkit-mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.92) 22%, rgba(0, 0, 0, 0.52) 54%, rgba(0, 0, 0, 0.18) 78%, transparent 100%); + mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.92) 22%, rgba(0, 0, 0, 0.52) 54%, rgba(0, 0, 0, 0.18) 78%, transparent 100%); +} + +.radiance-home:has(> .radiance-local[data-radiance-appearance="dark"]) { + inset: -88px -12vw -150px; + filter: saturate(1.2) contrast(1.08); + -webkit-mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.86) 20%, rgba(0, 0, 0, 0.42) 48%, rgba(0, 0, 0, 0.12) 70%, transparent 90%); + mask-image: linear-gradient(to bottom, #000 0%, rgba(0, 0, 0, 0.86) 20%, rgba(0, 0, 0, 0.42) 48%, rgba(0, 0, 0, 0.12) 70%, transparent 90%); +} + +.radiance-home::before { + content: ""; + position: absolute; + z-index: 3; + inset: 0; + pointer-events: none; + opacity: 0.22; + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='56' height='56' viewBox='0 0 56 56'%3E%3Cfilter id='n' x='0' y='0' width='100%25' height='100%25'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='1.48' numOctaves='3' seed='21' stitchTiles='stitch'/%3E%3CfeComponentTransfer%3E%3CfeFuncR type='linear' slope='1.58' intercept='-0.18'/%3E%3CfeFuncG type='linear' slope='1.22' intercept='-0.12'/%3E%3CfeFuncB type='linear' slope='1.5' intercept='-0.16'/%3E%3CfeFuncA type='linear' slope='0.64'/%3E%3C/feComponentTransfer%3E%3C/filter%3E%3Crect width='56' height='56' filter='url(%23n)'/%3E%3C/svg%3E"); + background-size: 56px 56px; + mix-blend-mode: multiply; +} + +.radiance-home:has(> .radiance-local[data-radiance-appearance="dark"])::before { + opacity: 0.27; + background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='56' height='56' viewBox='0 0 56 56'%3E%3Cfilter id='n' x='0' y='0' width='100%25' height='100%25'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='1.48' numOctaves='3' seed='21' stitchTiles='stitch'/%3E%3CfeComponentTransfer%3E%3CfeFuncR type='linear' slope='1.64' intercept='-0.2'/%3E%3CfeFuncG type='linear' slope='1.14' intercept='-0.1'/%3E%3CfeFuncB type='linear' slope='1.58' intercept='-0.18'/%3E%3CfeFuncA type='linear' slope='0.7'/%3E%3C/feComponentTransfer%3E%3C/filter%3E%3Crect width='56' height='56' filter='url(%23n)'/%3E%3C/svg%3E"); + mix-blend-mode: screen; +} + +.radiance-home::after { + content: ""; + position: absolute; + z-index: 2; + inset: 0; + background: + radial-gradient(ellipse 72% 34% at 50% 8%, rgba(255, 255, 255, 0.08), rgba(255, 255, 255, 0.034) 48%, rgba(255, 255, 255, 0) 78%), + linear-gradient(to bottom, rgba(255, 255, 255, 0.02) 0%, rgba(255, 255, 255, 0.16) 38%, rgba(255, 255, 255, 0.48) 70%, #ffffff 100%); +} + +.radiance-home:has(> .radiance-local[data-radiance-appearance="dark"])::after { + background: + radial-gradient(ellipse 72% 34% at 50% 8%, rgba(26, 27, 30, 0.12), rgba(26, 27, 30, 0.052) 46%, rgba(26, 27, 30, 0) 76%), + linear-gradient(to bottom, rgba(26, 27, 30, 0.06) 0%, rgba(26, 27, 30, 0.22) 34%, rgba(26, 27, 30, 0.56) 62%, #131416 100%); +} + +.radiance-home > .radiance-local { + position: absolute; + inset: 0; + overflow: hidden; +} + +.radiance-home > .radiance-local canvas { + position: absolute; + inset: 0; + display: block; + width: 100%; + height: 100%; +} + +@media (max-width: 780px) { + .radiance-home { inset: -82px -18vw -176px; } + .radiance-home:has(> .radiance-local[data-radiance-appearance="dark"]) { inset: -76px -18vw -132px; } +} + +@media (max-width: 520px) { + .radiance-home { inset: -72px -28vw -162px; } + .radiance-home:has(> .radiance-local[data-radiance-appearance="dark"]) { inset: -68px -28vw -126px; } +} diff --git a/src/assets/svg/not-found-illustration.svg b/src/assets/svg/not-found-illustration.svg new file mode 100644 index 000000000..7340bc549 --- /dev/null +++ b/src/assets/svg/not-found-illustration.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/components/DevDocTemplate/index.tsx b/src/components/DevDocTemplate/index.tsx index e3760503f..0af542a6c 100644 --- a/src/components/DevDocTemplate/index.tsx +++ b/src/components/DevDocTemplate/index.tsx @@ -12,6 +12,7 @@ import { BiSearch } from '@react-icons/all-files/bi/BiSearch'; import { Analytics } from '@vercel/analytics/react'; import { Seo } from '../Seo'; import { queryStringParser, isPublicSite } from '../../utils/app-utils'; +import { useRadianceTheme } from '../../utils/radiance'; import { passThroughHandler, fetchChild, getPageIdFromHref } from '../../utils/doc-utils'; import Header from '../Header'; import SecondaryHeader, { DocCategory, CATEGORY_PAGEIDS, CATEGORY_NAV_ID } from '../SecondaryHeader'; @@ -20,6 +21,7 @@ import Docmap from '../Docmap'; import Document from '../Document'; import Search from '../Search'; import '../../assets/styles/index.scss'; +import '../../assets/styles/radiance-home.css'; import { getAlgoliaIndex } from '../../configs/algolia-search-config'; import RenderPlayGround from './playGround/RESTAPI'; import GraphQLPlayGround from './playGround/GraphQL'; @@ -130,6 +132,9 @@ const DevDocTemplate: FC = (props) => { }); const [key, setKey] = useState(''); + // Keeps the Radiance hero surface (home.adoc) in the site's current theme. + useRadianceTheme(isDarkMode); + // Pre-process all category nav HTMLs once ({{navprefix}} substitution applied to each) const processedNavMap = React.useMemo(() => Object.fromEntries( diff --git a/src/components/Page404/index.scss b/src/components/Page404/index.scss index 299fcbe01..c42cb9ace 100644 --- a/src/components/Page404/index.scss +++ b/src/components/Page404/index.scss @@ -1,6 +1,19 @@ @import '../../assets/styles/variables.scss'; +// BB Roller Mono is the large "404" numerals in the design. +@font-face { + font-family: 'BB-Roller-Mono'; + src: url('../../assets/fonts/BB-Roller-Mono-Regular.otf') format('opentype'); + font-weight: 400; + font-style: normal; + font-display: swap; +} + +$not-found-text: var(--rd-sys-color-content-primary, #1d232f); +$not-found-brand: #2770ef; + .pageStyles { + position: relative; display: flex; flex-direction: column; align-items: center; @@ -8,22 +21,136 @@ text-align: center; height: auto; min-height: 100vh; - padding: 96px; - color: var(--rd-sys-color-content-primary); - background-color: var(--rd-sys-color-background-base); + padding: 96px 24px; + overflow: hidden; + color: $not-found-text; + background-color: var(--rd-sys-color-background-base, #fff); font-family: 'Optimo-Plain', sans-serif; } +// Radiance top wash across the top of the page, faded out into the page background. +// Size is the container's (RULES.md ADJUST-6), so only the box is set here. +.radianceTop { + position: absolute; + top: 0; + left: 0; + right: 0; + height: 320px; + pointer-events: none; + -webkit-mask-image: linear-gradient(to bottom, #000 0%, #000 45%, transparent 100%); + mask-image: linear-gradient(to bottom, #000 0%, #000 45%, transparent 100%); + + .radiance-local { + position: absolute; + inset: 0; + overflow: hidden; + } +} + +.pageMissing, +.docMissing { + position: relative; + z-index: 1; +} + +.pageMissing { + display: flex; + flex-direction: column; + align-items: center; +} + +.codeStyles { + margin: 0 0 40px; + font-family: 'BB-Roller-Mono', 'Roboto Mono', monospace; + font-size: 96px; + font-weight: 400; + line-height: 1; + letter-spacing: 0; +} + .headingStyles { - margin-top: 0; - margin-bottom: 64px; - font-size: 28px; + margin: 0 0 8px; + font-size: 24px; + font-weight: $font-weight-bold; + line-height: 32px; } .paragraphStyles { - margin: 0 0 16px; + margin: 0; + font-size: 16px; + line-height: 24px; +} + +.homeButton { + display: inline-flex; + align-items: center; + justify-content: center; + margin-top: 24px; + padding: 4px 12px; + border-radius: 999px; + background: #eaedf2; + color: $not-found-text; + font-size: 13px; + line-height: 16px; + text-decoration: none; + transition: background-color 0.15s ease; + + &:hover { + background: #dde2ea; + text-decoration: none; + } +} + +// In-product presentation: illustration beside the text, primary button. +.pageStyles--embedded { + .docMissing { + display: flex; + align-items: center; + gap: 48px; + text-align: left; + } + + .docMissingIllustration { + flex: none; + width: 140px; + height: 118px; + } + + .docMissingText { + max-width: 440px; + } + + .paragraphStyles { + max-width: 420px; + } + + .homeButton { + padding: 8px 16px; + background: $not-found-brand; + color: #fff; + font-size: 14px; + line-height: 16px; + + &:hover { + background: #1f5fd6; + } + } +} + +@media (max-width: 560px) { + .codeStyles { + font-size: 72px; + } + + .pageStyles--embedded .docMissing { + flex-direction: column; + gap: 24px; + text-align: center; - a { - color: var(--rd-sys-color-content-brand); + .docMissingText { + display: flex; + flex-direction: column; + align-items: center; + } } } diff --git a/src/components/Page404/index.tsx b/src/components/Page404/index.tsx index 40e563eba..7820160d0 100644 --- a/src/components/Page404/index.tsx +++ b/src/components/Page404/index.tsx @@ -2,22 +2,71 @@ import * as React from 'react'; import { Link } from 'gatsby'; import { NOT_FOUND_GO_HOME_PAGE_ID } from '../../configs/doc-configs'; import t from '../../utils/lang-utils'; +import { isPublicSite } from '../../utils/app-utils'; +import { useRadianceTheme } from '../../utils/radiance'; +import notFoundIllustration from '../../assets/svg/not-found-illustration.svg'; import './index.scss'; const Page404 = () => { + // The page is prerendered once (404.html), so it always starts with the public layout and + // switches to the in-product one on mount when it is opened inside the product iframe. + const [isEmbedded, setIsEmbedded] = React.useState(false); + React.useEffect(() => { + setIsEmbedded(!isPublicSite(window.location.search)); + }, []); + + // The 404 designs only have a light variant. + useRadianceTheme(false); + + const homeLink = ( + + {t('404_GO_HOME_LINK_TEXT')} + + ); + return ( -
+
{t('404_PAGE_TITLE')} -

{t('404_PAGE_HEADING')}

-

- {t('404_PAGE_MSG_PRETEXT')} {t('404_PAGE_MSG')} -

-

- - {t('404_GO_HOME_LINK_TEXT')} - - . -

+
); }; diff --git a/src/index.d.ts b/src/index.d.ts index 44350b3aa..dce9face6 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -2,3 +2,6 @@ declare module '*.svg' { const content: string; export default content; } + +// Injected by Gatsby at build time (the site's pathPrefix, e.g. '/docs'). +declare const __PATH_PREFIX__: string; diff --git a/src/intl/en.json b/src/intl/en.json index 77f58424b..3354e0ec3 100644 --- a/src/intl/en.json +++ b/src/intl/en.json @@ -3,10 +3,13 @@ "DOCS": "DOCS", "NAV_BACK_BTN_TEXT": "Back", "404_PAGE_TITLE": "Not found", - "404_PAGE_HEADING": "404 - Page Not Found", - "404_PAGE_MSG_PRETEXT": "Sorry,", - "404_PAGE_MSG": "we couldn’t find the page you’re looking for. It may have been removed, renamed, or is temporarily unavailable.", - "404_GO_HOME_LINK_TEXT": "Go to Homepage", + "404_PAGE_CODE": "404", + "404_PAGE_HEADING": "Page not found", + "404_PAGE_MSG": "Sorry, we couldn’t find the page you’re looking for.", + "404_PAGE_MSG_DETAIL": "It may have been removed, renamed, or is temporarily unavailable.", + "404_DOC_HEADING": "This document doesn’t exist", + "404_DOC_MSG": "We couldn’t find this document. It may have been moved, renamed, or the URL is incorrect.", + "404_GO_HOME_LINK_TEXT": "Go to home", "SEARCH_PLACEHOLDER": "Search", "CODE_COPY_BTN_TEXT": "Copy", "CODE_COPY_BTN_HOVER_TEXT": "Copy to clipboard", diff --git a/src/utils/radiance.ts b/src/utils/radiance.ts new file mode 100644 index 000000000..be0bfa25d --- /dev/null +++ b/src/utils/radiance.ts @@ -0,0 +1,64 @@ +import { useEffect } from 'react'; + +/** + * Glue for the Radiance "home" product pattern used by the docs hero (home.adoc). + * + * The renderer (static/radiance/radiance-renderer.js) and the hero recipe + * (src/assets/styles/radiance-home.css) are unmodified copies from the Radiance + * language repo and must stay that way (RULES.md IMPL-1, PRODUCT-3). The only thing the + * page owns is the theme: it sets data-radiance-appearance on the surface, and the + * renderer repaints on change. + */ + +const RENDERER_SRC = '/radiance/radiance-renderer.js'; +const SURFACE_SELECTOR = '.radiance-local'; + +let rendererRequested = false; + +// The renderer scans for .radiance-local elements on load and watches the DOM for new +// ones, so it is loaded once, and only when a page actually contains a surface. +const ensureRendererLoaded = () => { + if (rendererRequested || typeof document === 'undefined') return; + rendererRequested = true; + const script = document.createElement('script'); + // __PATH_PREFIX__ is injected by Gatsby (e.g. '/docs' in production, '' locally). + const prefix = typeof __PATH_PREFIX__ === 'string' ? __PATH_PREFIX__ : ''; + script.src = `${prefix}${RENDERER_SRC}`; + script.async = true; + document.body.appendChild(script); +}; + +const applyAppearance = (isDarkMode: boolean) => { + const appearance = isDarkMode ? 'dark' : 'light'; + const surfaces = document.querySelectorAll(SURFACE_SELECTOR); + surfaces.forEach((surface) => { + if (surface.dataset.radianceAppearance !== appearance) { + surface.dataset.radianceAppearance = appearance; + } + }); + if (surfaces.length) ensureRendererLoaded(); +}; + +/** + * Keeps every Radiance surface on the page in the site's current theme. Page content is + * injected after render, so new surfaces are picked up through a body observer too. + */ +export const useRadianceTheme = (isDarkMode: boolean) => { + useEffect(() => { + if (typeof document === 'undefined') return undefined; + applyAppearance(isDarkMode); + if (!('MutationObserver' in window)) return undefined; + const observer = new MutationObserver((mutations) => { + const added = mutations.some((mutation) => + Array.from(mutation.addedNodes).some( + (node) => + node instanceof Element && + (node.matches(SURFACE_SELECTOR) || node.querySelector(SURFACE_SELECTOR)), + ), + ); + if (added) applyAppearance(isDarkMode); + }); + observer.observe(document.body, { childList: true, subtree: true }); + return () => observer.disconnect(); + }, [isDarkMode]); +}; diff --git a/static/radiance/radiance-renderer.js b/static/radiance/radiance-renderer.js new file mode 100644 index 000000000..81386fffe --- /dev/null +++ b/static/radiance/radiance-renderer.js @@ -0,0 +1,2514 @@ +(() => { + /* + * Radiance Language renderer - v2. + * + * One file for every Radiance surface: the five templates (right-wash, + * left-wash, neutral, top-wash, bottom-wash) and the fixed product + * patterns (signup, home, spotterx, liveboard). v1 is frozen at + * renderer/v1/radiance-renderer.js for reference and comparison. + * + * v2 carries the system-level upgrades first built for SpotterX and + * Liveboard (see RULES.md and CHANGELOG.md): + * F1 film Built on Home's first-launch film: grain that reaches + * through faint colour, a fine second noise layer, and a + * gentle tone lift - all confined to the colour field + * (GRAIN-4), so the bare surface stays clean. + * F2 motion Organic drift: every orbit, size, stretch and tilt is 2-3 + * sines at incommensurate per-blob frequencies, and every blob + * breathes on its own rhythm (MOTION-2). + * F3 blend Clean blends: overlapping colours are wheel neighbours + * (mint - blue - violet - pink - peach); peach and mint stay + * compact accents (COLOR-5). + * Base A surface sits on its host's own background colour, per + * theme (data-radiance-base / --radiance-base, SURFACE-1). + */ + const RADIANCE_VERSION = "2.0.0"; + const LIGHT_SURFACE = "#ffffff"; + const DARK_SURFACE = "#1a1b1e"; + const RADIANCE_FILM_GRAIN_SIZE = 1.0; + const MAX_DPR = 2; + const TIME_ORIGIN_KEY = "radianceLanguageTimeOrigin"; + const MAX_TEXTURE_CACHE_ITEMS = 24; + const TAU = Math.PI * 2; + // GRAIN-4: how hard the colour field is stacked before it masks the film. + // 12 brings the film to ~80% by 12% colour and ~93% by 20% - the texture + // carries through faint colour the way Home's hero does - while the bare + // surface (under ~0.5% colour) keeps under ~6% of it. v1 used 4. + const GRAIN_MASK_SATURATION = 12; + // The mask is the blurred colour field, so it is smooth: it is built at a + // quarter of the canvas resolution and upscaled. The film stays full-res. + const MASK_SCALE = 0.25; + // F1 - the film stack per theme (built on Home's hero, as SpotterX and + // Liveboard carry it): grain strength, the dark dither, the fine noise layer + // and its blend, and the tone lift. The renderer draws all of it, masked to + // the colour field - consumers still add no CSS filter (BLEND-3). This is + // the language's one film per theme: every surface, template or product, + // draws exactly this grain (GRAIN-6). Light is at 1.0's full strength and + // dark at 0.76, so the grain still reads where the colour is subtle (the + // admin's 2.0 review). + const FILM = { + light: { grain: 1, dither: 0, overlay: 0.22, overlayBlend: "multiply", saturate: 1.16, contrast: 1.06 }, + dark: { grain: 0.76, dither: 0.42 * 0.76, overlay: 0.27, overlayBlend: "screen", saturate: 1.2, contrast: 1.08 } + }; + // The fine noise layer: SVG fractal noise rendered by the browser at the + // surface's pixel density and tiled every 56 CSS px - the same layer + // Home's hero draws over its canvas. + const FILM_OVERLAY_TILE = 56; + const FILM_OVERLAY_SVG = { + light: "", + dark: "" + }; + // F2 - every blob breathes: size and brightness swell a few per cent on the + // blob's own rhythm (ms at speed 1; the tempo follows the square root of the + // speed, so a fast pattern breathes a little quicker, never frantically). + const BREATH = { size: 0.05, glow: 0.05, periodMs: [5000, 8000] }; + + // Percentage adjustments. 100% is always the pattern's shipped value, so a + // surface that sets none of these is byte-identical to one that sets 100%. + // Ranges are what the language still reads as itself; outside them the + // renderer warns (RULES.md ADJUST-2). + const ADJUST_RANGES = { + prominence: { min: 0.5, max: 1.5, rule: "ADJUST-3" }, + spread: { min: 0.75, max: 1.25, rule: "ADJUST-4" }, + speed: { min: 0.5, max: 1.5, rule: "ADJUST-5" } + }; + + // Accepts "120%", "120" or "1.2" — all mean the same thing. + function parseAdjustment(raw) { + if (raw === undefined || raw === null || raw === "") return 1; + const text = String(raw).trim(); + const value = Number(text.replace("%", "").trim()); + if (!Number.isFinite(value) || value <= 0) return 1; + if (text.includes("%") || value > 5) return value / 100; + return value; + } + + // ------------------------------------------------------------------ + // Named patterns. These five are the only sanctioned entry points into + // the language; every Radiance surface starts from one of them. + // Canonical values are mirrored in radiance.tokens.json — change both or + // neither. See RULES.md (PLACE-1, MOTION-6). + // ------------------------------------------------------------------ + const RADIANCE_PATTERNS = { + "right-wash": { layout: "right-wash", speeds: { slow: 0.62, fast: 1.02 } }, + "left-wash": { layout: "left-wash", speeds: { slow: 0.62, fast: 1.02 } }, + "neutral": { layout: "neutral", speeds: { slow: 0.86, fast: 1.34 } }, + "top-wash": { layout: "top-wash", speeds: { slow: 0.92, fast: 1.72 } }, + "bottom-wash": { layout: "bottom-wash", speeds: { slow: 0.92, fast: 1.72 } } + }; + + const PLACEMENT_ALIASES = { + right: "right-wash", + left: "left-wash", + top: "top-wash", + bottom: "bottom-wash", + neutral: "neutral", + modal: "neutral", + developer: "neutral" + }; + + // Shorthand fallbacks are the product-safe values, not the legacy + // attribute defaults. Agents still spell the full four-part name out. + const PATTERN_FALLBACKS = { intensity: "subtle", motion: "dynamic", speed: "slow" }; + + // ------------------------------------------------------------------ + // Product patterns (RULES.md section 12). Fixed, admin-owned patterns for + // ThoughtSpot's finished product screens. They take no adjustment, no + // override and no base colour from the page: every value is locked here, + // and only the Radiance admin changes them, in this repository. + // "template" products are a locked template configuration; + // "spotter" products run the Spotter radiance engine (below). + // Mirrored in radiance.tokens.json and products/manifest.json. + // ------------------------------------------------------------------ + const PRODUCT_PATTERNS = { + signup: { + name: "Sign up", + engine: "template", + layout: "right-wash", + intensity: "prominent", + speed: { light: 1.02, dark: 1.02 }, + seed: "signin-v2", + film: "renderer", + // Under reduced motion Sign up shows right-wash's curated static + // frame, as the product always has (MOTION-7). + reducedMotion: "static", + base: { light: "#ffffff", dark: "#1a1b1e" } + }, + home: { + name: "Home page", + engine: "template", + layout: "top-wash", + intensity: "subtle", + speed: { light: 1.86, dark: 1.72 }, + seed: "home-hero", + // Home's page recipe carries the fine noise and the tone lift + // (products/home/radiance-home.css); the renderer draws the grain over + // the whole hero field, as Home was built. Home's colour sits at the + // hero's strength (76% light / 66% dark over the base), drawn here so + // the grain on top is the language's one grain at full value (GRAIN-6). + film: "page", + fieldOpacity: { light: 0.76, dark: 0.66 }, + base: { light: "#ffffff", dark: "#131416" } + }, + spotterx: { + name: "SpotterX", + engine: "spotter", + // The page recipe (products//radiance-.css) carries the film. + film: "recipe", + base: { light: "#ffffff", dark: "#131416" } + }, + liveboard: { + name: "Liveboard", + engine: "spotter", + // The page recipe (products//radiance-.css) carries the film. + film: "recipe", + base: { light: "#ffffff", dark: "#131416" } + } + }; + // data-radiance-state on a spotter product: [reasoning energy, after-answer calm]. + const PRODUCT_STATES = { idle: [0, 0], reasoning: [1, 0], answered: [0, 1] }; + // Everything a product pattern ignores (PRODUCT-2). + const PRODUCT_LOCKED_ATTRIBUTES = [ + ["radianceProminence", "data-radiance-prominence"], + ["radianceSpread", "data-radiance-spread"], + ["radianceSpeedScale", "data-radiance-speed-scale"], + ["radianceSpeed", "data-radiance-speed"], + ["radianceBase", "data-radiance-base"], + ["radianceIntensity", "data-radiance-intensity"], + ["radianceLayout", "data-radiance-layout"], + ["radianceVariant", "data-radiance-variant"], + ["radianceMotion", "data-radiance-motion"], + ["radianceDarkGlow", "data-radiance-dark-glow"], + ["radianceSeed", "data-radiance-seed"] + ]; + // The Spotter engine's locked tuning: the values SpotterX and Liveboard ship. + const SBG_TUNING = { gain: 1, lift: 0, spread: 1, wash: 1, flow: 2.5, breath: 1, calmGain: 1.5, pace: 1 }; + // The Radiance admin's Spotter lab (spotter-lab/) previews other values on + // one surface through RadianceLanguageRenderer.admin; nothing else sets them. + const ADMIN_SPOTTER = new WeakMap(); + + /* + * The Spotter radiance engine - product patterns "spotterx" and "liveboard" + * (formerly the RADIANCE-OVERRIDE proposal "Spotter radiance BG" v5). + * Radiance blobs gathered along the product's top bar, spilling soft light + * below it - drifting organically at rest, breathing while reasoning, and + * retreating to a faint leak at the top after an answer: + * + * - Blobs: ~6.4 across the view (radius 1.6 spacings, hanging 2x taller + * than wide), drifting across the width so no colour owns a region. The + * colour sequence is a random walk along the wheel (see SBG_PATH), so + * neighbours are wheel-neighbours and overlaps stay clean tints; a blob + * that wraps off-screen is reborn, so the sequence never recurs. + * - Motion that never loops (MOTION-2): every blob's position, size, + * stretch and tilt is a sum of 2-3 sines at incommensurate per-blob + * frequencies, on top of a drift whose own speed swells and eases. + * - Breathing: every blob breathes - swells and brightens - on its own + * random rhythm, so many regions inhale and exhale out of step, never in + * one spot. Barely there at rest; while reasoning the swings deepen and + * quicken (1.8-3.4s), the whole glow breathes along (3.2s, starting + * exhaled at ignition), and a second stream of light flows the other way + * along the edge, taking the colour of the light beneath it - so the + * crossings brighten colours instead of muddying them. + * - States: ONE surface; data-radiance-state = idle | reasoning | answered + * (reasoning energy, and the calm after an answer). Both ease + * on critically damped springs; the clock is INTEGRATED (clock += dt * + * speed), so every speed change is live and phase-continuous. Clock rate + * per unit of Motion energy (2.5 by default): default 1.15 (2.88), + * reasoning 1.7 (4.25), after an answer 0.32 (0.8 - a slow, visible + * drift). + * - After an answer the colour drops to a faint leak (x0.5) and the blobs + * rise behind the bar; the page contracts its CSS fade toward the top, so + * colour and grain retreat together. + * - Shape: the vertical fade is the wrapper's CSS mask (the page builds it + * from the rig), exactly as on Home - colour, grain and overlay fade + * together. The renderer adds only reasoning's extra brightness, confined + * to the top band: reasoning never brings colour further down. + * - Grain: the language's one grain per theme (FILM, GRAIN-6), over the + * whole lit canvas, under the page's CSS fine noise and tone filter. + * - Rendering: blobs at quarter resolution with the canonical blur + * (BLEND-2, scaled), padded past every edge so the blur never darkens an + * edge, upscaled onto a dpr-1 canvas shown pixelated, so the 1.0px grain + * stays crisp (GRAIN-1/3). + * + * Sanctioned product exceptions (RULES.md PRODUCT-3): state-bound energy + * (MOTION-1), an integrated per-surface clock (MOTION-4), speeds above 2.0 + * (MOTION-5), per-load randomness (IMPL-4), and the page-level film in + * products//radiance-.css (GRAIN-4/5, BLEND-3). Everything is + * locked: the values below are the only ones these products ever run. + */ + const SBG_PALETTE = { + light: { pink: [255, 120, 160], violet: [140, 100, 255], blue: [40, 140, 255], peach: [255, 180, 100], mint: [80, 220, 180] }, + dark: { pink: [255, 93, 142], violet: [138, 93, 255], blue: [39, 140, 255], peach: [255, 180, 90], mint: [45, 220, 177] } + }; + /* The colour sequence is a random walk with momentum along the wheel - + mint, blue, violet, pink, peach - so neighbours are always + wheel-neighbours (blue never meets peach, pink never meets mint: every + blend a clean tint). Cool colour always leads (COLOR-4): the walk heads + into peach only 40% of the time it reaches pink, must pass back through + violet before any second peach, never runs more than 3-4 warm blobs, + and after a warm run stays cool for at least two - so every six-blob + screenful holds at least two blues/violets and nothing ever sits warm + (the yellow-red cast pink + peach makes in dark). A blob that wraps + off-screen is reborn with the next step of the walk and fresh size, + timing and shape, so the sequence never recurs. Long-run balance + (simulated over 1M steps): blue 29%, violet 35%, pink 24%, peach 7% + (warmth), mint 5% (quiet support). */ + const SBG_PATH = ["mint", "blue", "violet", "pink", "peach"]; + /* Peach and mint stay compact accents so their glow never reaches a hue + two steps away (peach + violet = mauve, the muddiest blend). */ + const SBG_ROLE = { blue: 1.04, violet: 0.84, pink: 0.92, peach: 0.85, mint: 0.5 }; + const SBG_SIZE = { blue: 1.05, violet: 0.96, pink: 0.98, peach: 0.84, mint: 0.78 }; + /* Blob centre opacity at rest and while reasoning (before the page's + saturate/contrast filter, which carries dark a little further); `calm` + is the after-answer leak as a fraction of rest (x the rig's After-answer + intensity, 1.5 by default). + `floor` is what reasoning keeps below its bright top band; light's rest + was raised on its own, so its reasoning keeps the earlier floor and + reads exactly as before. */ + const SBG_STATES = { + // 2.0: reasoning +15% (0.235 -> 0.27, floor 0.14 -> 0.155), calm +10% (0.5 -> 0.55). + light: { rest: 0.165, reason: 0.27, calm: 0.55, floor: 0.155 }, + dark: { rest: 0.12, reason: 0.28, calm: 0.5, floor: 0.12 } + }; + const SBG_MOTION = { + speedDefault: 1.15, // clock rate per unit of Motion energy (x2.5 = 2.88) + speedReason: 1.7, // x2.5 = 4.25 + speedSettled: 0.32, // x2.5 = 0.8 - the calm after an answer: a slow, visible drift + speedCap: 8, + flow: 0.016, // drift, px per clock-ms: ~46 px/s default, ~68 reasoning, ~13 calm + wanderReason: 0.6, // blobs wander 1.6x as far while reasoning + /* Each blob breathes on its own rhythm (ms, random per blob in these + ranges) with these size / brightness swings - rest, reasoning, calm. */ + breathMs: { rest: [5000, 8000], reason: [1800, 3400], calm: [5500, 8500] }, + breathSize: { rest: 0.05, reason: 0.22, calm: 0.06 }, + breathGlow: { rest: 0.05, reason: 0.2, calm: 0.06 }, + /* While reasoning the whole glow breathes along ... */ + chorusMs: 3200, + chorusSize: 0.06, + chorusGlow: 0.08, + /* ... and a stream of light flows the other way along the edge. */ + streamFlow: -1.6, + streamGlow: 0.7, + rise: 3.6, // spring rates (rad/s): ~1.1s into reasoning, + fall: 1.45, // ~2.7s back out, + settle: 1.3 // ~3s between the default and the after-answer calm + }; + const SBG_CALM_RISE = 0.1; // after an answer the blobs rise behind the bar (x radius) + /* The fade (mirrored by the page's CSS mask builder): a short fall - the + edge light, "spread" - plus a long faint tail - "wash coverage". The + reasoning gain lives only in the top `band` px. */ + const SBG_ENVELOPE = { spread: 70, wash: 320, tail: 0.45, band: 80 }; + const SBG_TALL = 2.0; + const SBG_BASE_LIFT = -8; + const SBG_BLUR = { light: 40, dark: 64 }; + const SBG_SCALE = 0.25; + const SBG_PAD = 96; + + + const warnedElements = new WeakMap(); + + function warnOnce(element, code, message) { + let codes = warnedElements.get(element); + if (!codes) { + codes = new Set(); + warnedElements.set(element, codes); + } + if (codes.has(code)) return; + codes.add(code); + console.warn(`[Radiance ${code}] ${message}`); + } + + function resolveRadiancePattern(raw) { + const tokens = String(raw || "").toLowerCase().split(/[^a-z]+/).filter(Boolean); + if (!tokens.length) return null; + + let layout = null; + for (const token of tokens) { + if (PLACEMENT_ALIASES[token]) { + layout = PLACEMENT_ALIASES[token]; + break; + } + } + if (!layout) return null; + + const has = (token) => tokens.includes(token); + const intensity = has("prominent") ? "prominent" : (has("subtle") ? "subtle" : PATTERN_FALLBACKS.intensity); + const motion = (has("static") || has("still")) ? "static" : PATTERN_FALLBACKS.motion; + const speedName = has("fast") ? "fast" : (has("slow") ? "slow" : PATTERN_FALLBACKS.speed); + const appearance = has("dark") ? "dark" : (has("light") ? "light" : null); + + return { + name: `${layout}-${intensity}-${motion}-${speedName}`, + layout, + intensity, + motion, + speedName, + speed: RADIANCE_PATTERNS[layout].speeds[speedName], + appearance + }; + } + + const reducedMotionQuery = typeof window.matchMedia === "function" + ? window.matchMedia("(prefers-reduced-motion: reduce)") + : null; + let prefersReducedMotion = reducedMotionQuery ? reducedMotionQuery.matches : false; + + const LIGHT_BLOBS = [ + { anchorX: 0.9, anchorY: 0.4, color: [255, 120, 160], radius: 0.4, opacity: 0.6, orbitX: 60, orbitY: 80, freqX: 0.0007, freqY: 0.0005, stretchFreq: 0.001 }, + { anchorX: 0.85, anchorY: 0.7, color: [80, 220, 180], radius: 0.36, opacity: 0.32, orbitX: -70, orbitY: -90, freqX: 0.0008, freqY: 0.0006, stretchFreq: 0.0012 }, + { anchorX: 0.95, anchorY: 0.5, color: [140, 100, 255], radius: 0.45, opacity: 0.6, orbitX: 50, orbitY: 100, freqX: 0.0005, freqY: 0.0009, stretchFreq: 0.0008 }, + { anchorX: 0.75, anchorY: 0.3, color: [255, 180, 100], radius: 0.3, opacity: 0.6, orbitX: -60, orbitY: 120, freqX: 0.0009, freqY: 0.0007, stretchFreq: 0.0015 }, + { anchorX: 0.8, anchorY: 0.6, color: [40, 140, 255], radius: 0.4, opacity: 0.6, orbitX: 90, orbitY: -80, freqX: 0.0008, freqY: 0.0011, stretchFreq: 0.0009 }, + { anchorX: 0.3, anchorY: 0.3, color: [200, 220, 255], radius: 0.7, opacity: 0.15, orbitX: 100, orbitY: 50, freqX: 0.0003, freqY: 0.0004, stretchFreq: 0.0005 }, + { anchorX: 0.2, anchorY: 0.7, color: [255, 200, 220], radius: 0.8, opacity: 0.15, orbitX: -80, orbitY: -100, freqX: 0.0004, freqY: 0.0003, stretchFreq: 0.0006 }, + { anchorX: 0.5, anchorY: 0.6, color: [255, 240, 180], radius: 0.6, opacity: 0.15, orbitX: 120, orbitY: -60, freqX: 0.0005, freqY: 0.0004, stretchFreq: 0.0007 } + ]; + + function scaleBlobSet(blobs, opacityScale, orbitScale) { + return blobs.map((blob) => ({ + ...blob, + opacity: blob.opacity * opacityScale, + orbitX: (blob.orbitX || 0) * orbitScale, + orbitY: (blob.orbitY || 0) * orbitScale + })); + } + + function mirrorBlobSet(blobs) { + return blobs.map((blob) => ({ + ...blob, + anchorX: 1 - blob.anchorX, + orbitX: -(blob.orbitX || 0) + })); + } + + function topBlobSet(blobs) { + return blobs.map((blob) => ({ + ...blob, + anchorX: clamp(blob.anchorY, 0.08, 0.94), + anchorY: clamp(1 - blob.anchorX, -0.04, 0.34), + orbitX: (blob.orbitY || 0) * 1.18, + orbitY: -(blob.orbitX || 0) * 0.58, + radius: blob.radius * 1.06 + })); + } + + function bottomBlobSet(blobs) { + return topBlobSet(blobs).map((blob) => ({ + ...blob, + anchorY: 1 - blob.anchorY, + orbitY: -(blob.orbitY || 0) + })); + } + + function lockBlobSet(blobs) { + return blobs.map((blob) => ({ + ...blob, + orbitX: 0, + orbitY: 0, + freqX: 0, + freqY: 0, + stretchFreq: 0, + locked: true + })); + } + + function neutralBlobSet(blobs) { + return blobs.map((blob) => ({ + ...blob, + surfaceScaled: true + })); + } + + function clamp(value, min, max) { + return Math.min(max, Math.max(min, value)); + } + + const mix = (a, b, t) => a + (b - a) * t; + const wave = (phase) => 0.5 - 0.5 * Math.cos(phase); + + // SURFACE-1: a base colour is any opaque CSS colour. Parsed once through a + // canvas, so every syntax the browser accepts works. + const colourCache = new Map(); + let colourProbe = null; + + function parseColour(value) { + const text = String(value || "").trim(); + if (!text) return null; + if (colourCache.has(text)) return colourCache.get(text); + colourProbe = colourProbe || document.createElement("canvas").getContext("2d"); + let rgb = null; + for (const sentinel of ["#010203", "#fefdfc"]) { + colourProbe.fillStyle = sentinel; + colourProbe.fillStyle = text; + const normal = String(colourProbe.fillStyle); + if (normal === sentinel) continue; + if (normal.startsWith("#")) { + rgb = [1, 3, 5].map((i) => parseInt(normal.slice(i, i + 2), 16)); + } else { + const parts = (normal.match(/rgba?\(([^)]+)\)/) || [])[1]; + const values = parts ? parts.split(",").map((part) => Number(part.trim())) : []; + if (values.length >= 3 && (values.length < 4 || values[3] >= 0.99)) rgb = values.slice(0, 3).map(Math.round); + } + break; + } + if (!rgb && text.toLowerCase() === "#010203") rgb = [1, 2, 3]; + colourCache.set(text, rgb); + return rgb; + } + + function hashSeed(value) { + let hash = 2166136261; + + for (let index = 0; index < value.length; index += 1) { + hash ^= value.charCodeAt(index); + hash = Math.imul(hash, 16777619); + } + + return hash >>> 0; + } + + function createSeededRandom(seed) { + let state = hashSeed(seed) || 1; + + return () => { + state += 0x6d2b79f5; + let result = state; + result = Math.imul(result ^ (result >>> 15), result | 1); + result ^= result + Math.imul(result ^ (result >>> 7), result | 61); + return ((result ^ (result >>> 14)) >>> 0) / 4294967296; + }; + } + + function getAnimationTimeOrigin() { + const now = Date.now(); + + try { + const storedOrigin = Number(window.sessionStorage.getItem(TIME_ORIGIN_KEY)); + if (Number.isFinite(storedOrigin) && storedOrigin > 0) return storedOrigin; + + window.sessionStorage.setItem(TIME_ORIGIN_KEY, String(now)); + } catch { + return now; + } + + return now; + } + + function getBlobSurfaceScale(config, width, height) { + if (!config.surfaceScaled) return { radius: 1, orbitX: 1, orbitY: 1 }; + + const minSide = Math.max(1, Math.min(width, height)); + const maxSide = Math.max(width, height); + const aspect = maxSide / minSide; + const compactBoost = clamp((480 - minSide) / 280, 0, 1); + const fieldBoost = clamp((maxSide - 760) / 720, 0, 1); + + return { + radius: 1.06 + clamp(aspect - 1, 0, 1.1) * 0.13 + compactBoost * 0.14 + fieldBoost * 0.05, + orbitX: clamp(width / 920, 0.28, 1.38), + orbitY: clamp(height / 680, 0.28, 1.38) + }; + } + + const LIGHT_SUBTLE_BLOBS = scaleBlobSet(LIGHT_BLOBS, 0.44, 0.62); + + const STATIC_LIGHT_BLOBS = [ + { anchorX: 1.02, anchorY: 0.14, color: [255, 120, 160], radius: 0.48, opacity: 0.58, locked: true }, + { anchorX: 0.96, anchorY: 0.42, color: [140, 100, 255], radius: 0.54, opacity: 0.6, locked: true }, + { anchorX: 0.8, anchorY: 0.62, color: [40, 140, 255], radius: 0.54, opacity: 0.58, locked: true }, + { anchorX: 0.78, anchorY: 0.28, color: [255, 180, 100], radius: 0.36, opacity: 0.44, locked: true }, + { anchorX: 1.02, anchorY: 0.82, color: [80, 220, 180], radius: 0.38, opacity: 0.1, locked: true }, + { anchorX: 0.34, anchorY: 0.34, color: [200, 220, 255], radius: 0.76, opacity: 0.1, locked: true }, + { anchorX: 0.2, anchorY: 0.74, color: [255, 200, 220], radius: 0.84, opacity: 0.075, locked: true }, + { anchorX: 0.52, anchorY: 0.62, color: [255, 240, 180], radius: 0.62, opacity: 0.075, locked: true } + ]; + + const STATIC_LIGHT_SUBTLE_BLOBS = scaleBlobSet(STATIC_LIGHT_BLOBS, 0.48, 1); + + const NEUTRAL_LIGHT_BLOBS = neutralBlobSet([ + { anchorX: 0.12, anchorY: 0.12, color: [255, 180, 100], radius: 0.39, opacity: 0.34, orbitX: 90, orbitY: 68, freqX: 0.00072, freqY: 0.00056, stretchFreq: 0.00108 }, + { anchorX: 0.28, anchorY: 0.28, color: [255, 120, 160], radius: 0.46, opacity: 0.5, orbitX: -118, orbitY: 84, freqX: 0.00086, freqY: 0.00068, stretchFreq: 0.00118 }, + { anchorX: 0.14, anchorY: 0.78, color: [40, 140, 255], radius: 0.54, opacity: 0.56, orbitX: 126, orbitY: -110, freqX: 0.00074, freqY: 0.00092, stretchFreq: 0.00102 }, + { anchorX: 0.44, anchorY: 0.18, color: [140, 100, 255], radius: 0.45, opacity: 0.48, orbitX: 106, orbitY: 92, freqX: 0.00064, freqY: 0.00086, stretchFreq: 0.00112 }, + { anchorX: 0.68, anchorY: 0.32, color: [40, 140, 255], radius: 0.49, opacity: 0.54, orbitX: 108, orbitY: -92, freqX: 0.00084, freqY: 0.00064, stretchFreq: 0.00114 }, + { anchorX: 0.84, anchorY: 0.18, color: [255, 120, 160], radius: 0.42, opacity: 0.45, orbitX: -98, orbitY: 98, freqX: 0.00078, freqY: 0.00088, stretchFreq: 0.00106 }, + { anchorX: 0.88, anchorY: 0.62, color: [140, 100, 255], radius: 0.56, opacity: 0.58, orbitX: -122, orbitY: -104, freqX: 0.00058, freqY: 0.00094, stretchFreq: 0.00098 }, + { anchorX: 0.68, anchorY: 0.86, color: [40, 140, 255], radius: 0.54, opacity: 0.54, orbitX: 108, orbitY: -110, freqX: 0.0009, freqY: 0.00072, stretchFreq: 0.0012 }, + { anchorX: 0.36, anchorY: 0.84, color: [255, 120, 160], radius: 0.42, opacity: 0.38, orbitX: 98, orbitY: -88, freqX: 0.0007, freqY: 0.00082, stretchFreq: 0.00104 }, + { anchorX: 0.48, anchorY: 0.48, color: [80, 220, 180], radius: 0.3, opacity: 0.04, orbitX: 78, orbitY: -72, freqX: 0.00068, freqY: 0.00072, stretchFreq: 0.00092 } + ]); + + const NEUTRAL_LIGHT_SUBTLE_BLOBS = scaleBlobSet(NEUTRAL_LIGHT_BLOBS, 0.52, 0.86); + const STATIC_NEUTRAL_LIGHT_BLOBS = lockBlobSet(NEUTRAL_LIGHT_BLOBS); + const STATIC_NEUTRAL_LIGHT_SUBTLE_BLOBS = lockBlobSet(NEUTRAL_LIGHT_SUBTLE_BLOBS); + + const DARK_SUBTLE_BLOBS = [ + { anchorX: 0.9, anchorY: 0.4, color: [255, 93, 142], radius: 0.42, opacity: 0.34, orbitX: 60, orbitY: 80, freqX: 0.0007, freqY: 0.0005, stretchFreq: 0.001 }, + { anchorX: 0.86, anchorY: 0.72, color: [45, 220, 177], radius: 0.38, opacity: 0.12, orbitX: -70, orbitY: -90, freqX: 0.0008, freqY: 0.0006, stretchFreq: 0.0012 }, + { anchorX: 0.95, anchorY: 0.5, color: [138, 93, 255], radius: 0.48, opacity: 0.36, orbitX: 50, orbitY: 100, freqX: 0.0005, freqY: 0.0009, stretchFreq: 0.0008 }, + { anchorX: 0.74, anchorY: 0.3, color: [255, 180, 90], radius: 0.29, opacity: 0.2, orbitX: -60, orbitY: 120, freqX: 0.0009, freqY: 0.0007, stretchFreq: 0.0015 }, + { anchorX: 0.8, anchorY: 0.62, color: [39, 140, 255], radius: 0.42, opacity: 0.32, orbitX: 90, orbitY: -80, freqX: 0.0008, freqY: 0.0011, stretchFreq: 0.0009 }, + { anchorX: 0.3, anchorY: 0.3, color: [160, 196, 255], radius: 0.62, opacity: 0.055, orbitX: 100, orbitY: 50, freqX: 0.0003, freqY: 0.0004, stretchFreq: 0.0005 }, + { anchorX: 0.2, anchorY: 0.72, color: [255, 170, 210], radius: 0.66, opacity: 0.055, orbitX: -80, orbitY: -100, freqX: 0.0004, freqY: 0.0003, stretchFreq: 0.0006 }, + { anchorX: 0.5, anchorY: 0.6, color: [255, 232, 150], radius: 0.52, opacity: 0.045, orbitX: 120, orbitY: -60, freqX: 0.0005, freqY: 0.0004, stretchFreq: 0.0007 } + ]; + + const DARK_PROMINENT_BLOBS = [ + { anchorX: 0.9, anchorY: 0.4, color: [255, 93, 142], radius: 0.46, opacity: 0.44, orbitX: 60, orbitY: 80, freqX: 0.0007, freqY: 0.0005, stretchFreq: 0.001 }, + { anchorX: 0.86, anchorY: 0.72, color: [45, 220, 177], radius: 0.42, opacity: 0.18, orbitX: -70, orbitY: -90, freqX: 0.0008, freqY: 0.0006, stretchFreq: 0.0012 }, + { anchorX: 0.95, anchorY: 0.5, color: [138, 93, 255], radius: 0.52, opacity: 0.46, orbitX: 50, orbitY: 100, freqX: 0.0005, freqY: 0.0009, stretchFreq: 0.0008 }, + { anchorX: 0.74, anchorY: 0.3, color: [255, 180, 90], radius: 0.32, opacity: 0.28, orbitX: -60, orbitY: 120, freqX: 0.0009, freqY: 0.0007, stretchFreq: 0.0015 }, + { anchorX: 0.8, anchorY: 0.62, color: [39, 140, 255], radius: 0.46, opacity: 0.42, orbitX: 90, orbitY: -80, freqX: 0.0008, freqY: 0.0011, stretchFreq: 0.0009 }, + { anchorX: 0.3, anchorY: 0.3, color: [160, 196, 255], radius: 0.78, opacity: 0.12, orbitX: 100, orbitY: 50, freqX: 0.0003, freqY: 0.0004, stretchFreq: 0.0005 }, + { anchorX: 0.2, anchorY: 0.72, color: [255, 170, 210], radius: 0.82, opacity: 0.12, orbitX: -80, orbitY: -100, freqX: 0.0004, freqY: 0.0003, stretchFreq: 0.0006 }, + { anchorX: 0.5, anchorY: 0.6, color: [255, 232, 150], radius: 0.64, opacity: 0.1, orbitX: 120, orbitY: -60, freqX: 0.0005, freqY: 0.0004, stretchFreq: 0.0007 } + ]; + + const STATIC_DARK_PROMINENT_BLOBS = [ + { anchorX: 1.02, anchorY: 0.14, color: [255, 93, 142], radius: 0.5, opacity: 0.42, locked: true }, + { anchorX: 0.96, anchorY: 0.44, color: [138, 93, 255], radius: 0.56, opacity: 0.46, locked: true }, + { anchorX: 0.8, anchorY: 0.64, color: [39, 140, 255], radius: 0.56, opacity: 0.42, locked: true }, + { anchorX: 0.76, anchorY: 0.28, color: [255, 180, 90], radius: 0.36, opacity: 0.24, locked: true }, + { anchorX: 1.02, anchorY: 0.84, color: [45, 220, 177], radius: 0.38, opacity: 0.07, locked: true }, + { anchorX: 0.34, anchorY: 0.34, color: [160, 196, 255], radius: 0.76, opacity: 0.08, locked: true }, + { anchorX: 0.2, anchorY: 0.74, color: [255, 170, 210], radius: 0.82, opacity: 0.075, locked: true }, + { anchorX: 0.52, anchorY: 0.62, color: [255, 232, 150], radius: 0.62, opacity: 0.055, locked: true } + ]; + + const STATIC_DARK_SUBTLE_BLOBS = scaleBlobSet(STATIC_DARK_PROMINENT_BLOBS, 0.54, 1); + + const NEUTRAL_DARK_PROMINENT_BLOBS = neutralBlobSet([ + { anchorX: 0.12, anchorY: 0.12, color: [255, 180, 90], radius: 0.39, opacity: 0.22, orbitX: 90, orbitY: 68, freqX: 0.00072, freqY: 0.00056, stretchFreq: 0.00108 }, + { anchorX: 0.28, anchorY: 0.28, color: [255, 93, 142], radius: 0.46, opacity: 0.36, orbitX: -118, orbitY: 84, freqX: 0.00086, freqY: 0.00068, stretchFreq: 0.00118 }, + { anchorX: 0.14, anchorY: 0.78, color: [39, 140, 255], radius: 0.54, opacity: 0.4, orbitX: 126, orbitY: -110, freqX: 0.00074, freqY: 0.00092, stretchFreq: 0.00102 }, + { anchorX: 0.44, anchorY: 0.18, color: [138, 93, 255], radius: 0.45, opacity: 0.36, orbitX: 106, orbitY: 92, freqX: 0.00064, freqY: 0.00086, stretchFreq: 0.00112 }, + { anchorX: 0.68, anchorY: 0.32, color: [39, 140, 255], radius: 0.49, opacity: 0.38, orbitX: 108, orbitY: -92, freqX: 0.00084, freqY: 0.00064, stretchFreq: 0.00114 }, + { anchorX: 0.84, anchorY: 0.18, color: [255, 93, 142], radius: 0.42, opacity: 0.32, orbitX: -98, orbitY: 98, freqX: 0.00078, freqY: 0.00088, stretchFreq: 0.00106 }, + { anchorX: 0.88, anchorY: 0.62, color: [138, 93, 255], radius: 0.56, opacity: 0.42, orbitX: -122, orbitY: -104, freqX: 0.00058, freqY: 0.00094, stretchFreq: 0.00098 }, + { anchorX: 0.68, anchorY: 0.86, color: [39, 140, 255], radius: 0.54, opacity: 0.4, orbitX: 108, orbitY: -110, freqX: 0.0009, freqY: 0.00072, stretchFreq: 0.0012 }, + { anchorX: 0.36, anchorY: 0.84, color: [255, 93, 142], radius: 0.42, opacity: 0.28, orbitX: 98, orbitY: -88, freqX: 0.0007, freqY: 0.00082, stretchFreq: 0.00104 }, + { anchorX: 0.48, anchorY: 0.48, color: [45, 220, 177], radius: 0.3, opacity: 0.024, orbitX: 78, orbitY: -72, freqX: 0.00068, freqY: 0.00072, stretchFreq: 0.00092 } + ]); + + const NEUTRAL_DARK_SUBTLE_BLOBS = scaleBlobSet(NEUTRAL_DARK_PROMINENT_BLOBS, 0.52, 0.86); + const STATIC_NEUTRAL_DARK_PROMINENT_BLOBS = lockBlobSet(NEUTRAL_DARK_PROMINENT_BLOBS); + const STATIC_NEUTRAL_DARK_SUBTLE_BLOBS = lockBlobSet(NEUTRAL_DARK_SUBTLE_BLOBS); + + const NEUTRAL_VEIL_BLOBS = [ + { anchorX: 0.08, anchorY: 0.18, radius: 0.56, opacity: 0.28, orbitX: 52, orbitY: 44, freqX: 0.00048, freqY: 0.0004, phase: 0.32 }, + { anchorX: 0.52, anchorY: 0.08, radius: 0.48, opacity: 0.2, orbitX: -56, orbitY: 38, freqX: 0.00038, freqY: 0.00046, phase: 1.18 }, + { anchorX: 0.94, anchorY: 0.26, radius: 0.54, opacity: 0.24, orbitX: -48, orbitY: 54, freqX: 0.00044, freqY: 0.00036, phase: 2.42 }, + { anchorX: 0.22, anchorY: 0.82, radius: 0.6, opacity: 0.22, orbitX: 62, orbitY: -46, freqX: 0.00034, freqY: 0.00042, phase: 3.36 }, + { anchorX: 0.74, anchorY: 0.78, radius: 0.58, opacity: 0.24, orbitX: -64, orbitY: -52, freqX: 0.00042, freqY: 0.00038, phase: 4.72 }, + { anchorX: 0.48, anchorY: 0.5, radius: 0.72, opacity: 0.16, orbitX: 46, orbitY: -42, freqX: 0.0003, freqY: 0.00034, phase: 5.58 } + ]; + + const surfaces = new Set(); + const surfaceByElement = new WeakMap(); + const textureCache = new Map(); + const timeOrigin = getAnimationTimeOrigin(); + let isDocumentVisible = document.visibilityState !== "hidden"; + let mutationObserver; + let raf = 0; + + function getTimelineTime() { + return Math.max(0, Date.now() - timeOrigin); + } + + function rememberTexture(key, texture) { + if (textureCache.has(key)) return textureCache.get(key); + textureCache.set(key, texture); + + if (textureCache.size > MAX_TEXTURE_CACHE_ITEMS) { + const oldestKey = textureCache.keys().next().value; + textureCache.delete(oldestKey); + } + + return texture; + } + + class RadianceBlob { + constructor(config, random) { + this.config = config; + this.phaseX = random() * Math.PI * 2; + this.phaseY = random() * Math.PI * 2; + this.phaseStretch = random() * Math.PI * 2; + this.phaseDrift = random() * Math.PI * 2; + // F2: the extra sines' ratios and phases, a slow tilt, and the blob's + // own breath - all seeded (IMPL-4), so a surface is stable on reload. + this.phases = Array.from({ length: 8 }, () => random() * TAU); + this.ratios = [ + 1.52 + random() * 0.2, + 2.3 + random() * 0.3, + 1.6 + random() * 0.3, + 1.4 + random() * 0.3, + 1.5 + random() * 0.3, + 1.5 + random() * 0.3, + 1.6 + random() * 0.3 + ]; + this.tiltFreq = 0.00022 + random() * 0.00022; + this.breathMs = BREATH.periodMs[0] + random() * (BREATH.periodMs[1] - BREATH.periodMs[0]); + this.breathPhase = random() * TAU; + this.x = 0; + this.y = 0; + this.r = 0; + this.stretchX = 1; + this.stretchY = 1; + this.tilt = 0; + this.hasState = false; + } + + update(t, width, height, mouse, breathT = 0) { + const config = this.config; + const baseX = width * config.anchorX; + const baseY = height * config.anchorY; + const minSide = Math.min(width, height); + const surfaceScale = getBlobSurfaceScale(config, width, height); + const baseRadius = minSide * config.radius * surfaceScale.radius; + + if (config.locked) { + this.x = baseX; + this.y = baseY; + this.r = baseRadius; + this.stretchX = 1; + this.stretchY = 1; + this.tilt = 0; + this.opacity = config.opacity; + this.hasState = true; + return; + } + + const freqX = config.freqX || 0.00022; + const freqY = config.freqY || 0.00022; + const stretchFreq = config.stretchFreq || 0.00032; + let targetX; + let targetY; + let targetR; + let targetStretchX; + let targetStretchY; + + // F2 (MOTION-2): each motion is 2-3 sines at incommensurate per-blob + // ratios - the same reach as v1's single sines, but a path that + // never retraces - and the blob breathes on its own rhythm. + const p = this.phases; + const k = this.ratios; + const orbitX = (config.orbitX || 0) * surfaceScale.orbitX; + const orbitY = (config.orbitY || 0) * surfaceScale.orbitY; + const breath = wave(TAU * breathT / this.breathMs + this.breathPhase); + targetX = baseX + orbitX * ( + 0.72 * Math.sin(t * freqX + this.phaseX) + + 0.2 * Math.sin(t * freqX * k[0] + p[0]) + + 0.08 * Math.sin(t * freqX * k[1] + p[1])); + targetY = baseY + orbitY * ( + 0.78 * Math.cos(t * freqY + this.phaseY) + + 0.22 * Math.sin(t * freqY * k[2] + p[2])); + targetR = baseRadius + * (1 + 0.1 * Math.sin(t * 0.001 + this.phaseX) + 0.05 * Math.sin(t * 0.001 * k[3] + p[3])) + * (1 + BREATH.size * (breath - 0.4)); + targetStretchX = 1 + 0.3 * (0.72 * Math.sin(t * stretchFreq + this.phaseX) + 0.28 * Math.sin(t * stretchFreq * k[4] + p[4])); + targetStretchY = 1 + 0.3 * (0.72 * Math.cos(t * stretchFreq + this.phaseY) + 0.28 * Math.sin(t * stretchFreq * k[5] + p[5])); + this.tilt = 0.16 * Math.sin(t * this.tiltFreq + p[6]) + 0.08 * Math.sin(t * this.tiltFreq * k[6] + p[7]); + this.opacity = config.opacity * (1 + BREATH.glow * (breath - 0.5)); + + const ease = 1; + this.x += (targetX - this.x) * ease; + this.y += (targetY - this.y) * ease; + this.r += (targetR - this.r) * ease; + this.stretchX += (targetStretchX - this.stretchX) * ease; + this.stretchY += (targetStretchY - this.stretchY) * ease; + this.hasState = true; + } + + draw(ctx) { + const [r, g, b] = this.config.color; + const opacity = this.opacity ?? this.config.opacity; + ctx.save(); + ctx.translate(this.x, this.y); + if (this.tilt) ctx.rotate(this.tilt); + ctx.scale(this.stretchX, this.stretchY); + const gradient = ctx.createRadialGradient(0, 0, 0, 0, 0, this.r); + gradient.addColorStop(0, `rgba(${r},${g},${b},${opacity})`); + gradient.addColorStop(1, `rgba(${r},${g},${b},0)`); + ctx.fillStyle = gradient; + ctx.beginPath(); + ctx.arc(0, 0, this.r, 0, Math.PI * 2); + ctx.fill(); + ctx.restore(); + } + } + + class RadianceSurface { + constructor(element) { + this.element = element; + this.canvas = document.createElement("canvas"); + this.ctx = this.canvas.getContext("2d", { alpha: false }); + this.mouse = { x: -9999, y: -9999 }; + this.width = 0; + this.height = 0; + this.dpr = 1; + this.textureKey = ""; + this.ready = false; + this.isInViewport = true; + this.needsResize = true; + this.staticFrameKey = ""; + this.blobCanvas = document.createElement("canvas"); + this.blobCtx = this.blobCanvas.getContext("2d"); + this.fieldCanvas = document.createElement("canvas"); + this.fieldCtx = this.fieldCanvas.getContext("2d"); + this.grainCanvas = document.createElement("canvas"); + this.grainMaskCtx = this.grainCanvas.getContext("2d"); + this.maskCanvas = document.createElement("canvas"); + this.maskCtx = this.maskCanvas.getContext("2d"); + this.liftCanvas = document.createElement("canvas"); + this.liftCtx = this.liftCanvas.getContext("2d"); + this.blobs = []; + this.lastConfigKey = ""; + this.appliedPatternSource = null; + this.product = null; + this.productName = ""; + this.cssBase = ""; + this.baseKey = ""; + this.baseRgb = [255, 255, 255]; + this.baseFill = LIGHT_SURFACE; + this.element.appendChild(this.canvas); + this.element.dataset.radianceReady = "false"; + + if ("ResizeObserver" in window) { + this.resizeObserver = new ResizeObserver(() => { + this.needsResize = true; + }); + this.resizeObserver.observe(this.element); + } + + if ("IntersectionObserver" in window) { + this.intersectionObserver = new IntersectionObserver((entries) => { + this.isInViewport = entries.some((entry) => entry.isIntersecting); + if (this.isInViewport) startLoop(); + }); + this.intersectionObserver.observe(this.element); + } + } + + destroy() { + this.resizeObserver?.disconnect(); + this.intersectionObserver?.disconnect(); + this.canvas.remove(); + } + + get appearance() { + return this.element.dataset.radianceAppearance === "dark" ? "dark" : "light"; + } + + // A template product pattern (signup, home), or null. + get productTemplate() { + return this.product && this.product.engine === "template" ? this.product : null; + } + + get isSpotter() { + return Boolean(this.product && this.product.engine === "spotter"); + } + + get speed() { + const product = this.productTemplate; + if (product) return product.speed[this.appearance]; + const value = Number(this.element.dataset.radianceSpeed || "1"); + const base = Number.isFinite(value) ? value : 1; + return base * this.adjustment("speed", this.element.dataset.radianceSpeedScale); + } + + // ADJUST-1: every adjustment is a percentage of the pattern's own value, + // never an absolute. 100% means "exactly what the pattern ships". + adjustment(kind, raw) { + const scale = parseAdjustment(raw); + const range = ADJUST_RANGES[kind]; + if (range && (scale < range.min || scale > range.max)) { + warnOnce( + this.element, + range.rule, + `${kind} adjusted to ${Math.round(scale * 100)}% — the Radiance range is ` + + `${Math.round(range.min * 100)}%-${Math.round(range.max * 100)}%. ` + + "Outside it this surface stops matching the rest of the product. See RULES.md." + ); + } + return scale; + } + + get prominenceScale() { + if (this.product) return 1; + return this.adjustment("prominence", this.element.dataset.radianceProminence); + } + + get spreadScale() { + if (this.product) return 1; + return this.adjustment("spread", this.element.dataset.radianceSpread); + } + + get variant() { + const product = this.productTemplate; + if (product) { + const motion = prefersReducedMotion && product.reducedMotion === "static" ? "static" : "dynamic"; + return `${motion}-${product.intensity}`; + } + return this.element.dataset.radianceVariant || ""; + } + + get darkGlow() { + const product = this.productTemplate; + if (product) return product.intensity; + return this.element.dataset.radianceDarkGlow || "subtle"; + } + + get seed() { + const product = this.productTemplate; + if (product) return product.seed; + return this.element.dataset.radianceSeed || ""; + } + + // "renderer": the v2 film stack (F1). "page": the product's own page + // recipe carries the film; the renderer draws plain full-surface grain. + get filmMode() { + const product = this.productTemplate; + return product ? product.film : "renderer"; + } + + get layout() { + const product = this.productTemplate; + if (product) return product.layout; + const layout = this.element.dataset.radianceLayout || "right-wash"; + if (layout === "left" || layout === "left-wash") return "left-wash"; + if (layout === "top" || layout === "top-wash") return "top-wash"; + if (layout === "bottom" || layout === "bottom-wash") return "bottom-wash"; + if (layout === "neutral" || layout === "home-corners" || layout === "modal-balanced" || layout === "developer-sides") return "neutral"; + return "right-wash"; + } + + get isSubtle() { + const product = this.productTemplate; + if (product) return product.intensity === "subtle"; + return this.variant.endsWith("subtle") || this.element.dataset.radianceIntensity === "subtle"; + } + + get isDark() { + return this.appearance === "dark"; + } + + get isStill() { + // MOTION-7: a reduced-motion request freezes the surface at its + // resting frame. Same pattern, same composition, no drift. + if (prefersReducedMotion) return true; + if (this.product) return false; + return this.element.dataset.radianceMotion === "still" || this.variant.startsWith("static"); + } + + applyPatternShorthand() { + const raw = (this.element.dataset.radiancePattern || "").trim(); + if (raw === this.appliedPatternSource) { + if (this.product) this.guardProduct(); + return; + } + this.appliedPatternSource = raw; + + // PRODUCT-1: a product name selects that product's fixed pattern. + const productKey = raw.toLowerCase(); + if (Object.prototype.hasOwnProperty.call(PRODUCT_PATTERNS, productKey)) { + this.product = PRODUCT_PATTERNS[productKey]; + this.productName = productKey; + this.needsResize = true; + this.lastConfigKey = ""; + this.staticFrameKey = ""; + this.baseKey = ""; + this.guardProduct(); + return; + } + if (this.product) { + this.product = null; + this.productName = ""; + this.needsResize = true; + this.lastConfigKey = ""; + this.baseKey = ""; + } + if (!raw) return; + + const pattern = resolveRadiancePattern(raw); + if (!pattern) { + warnOnce( + this.element, + "PLACE-1", + `Unknown pattern "${raw}". Templates are: ${Object.keys(RADIANCE_PATTERNS).join(", ")}; ` + + `product patterns are: ${Object.keys(PRODUCT_PATTERNS).join(", ")}. ` + + "Keeping the data-radiance-* attributes already on this element." + ); + return; + } + + const data = this.element.dataset; + data.radianceLayout = pattern.layout; + data.radianceIntensity = pattern.intensity; + data.radianceDarkGlow = pattern.intensity; + data.radianceVariant = `${pattern.motion}-${pattern.intensity}`; + data.radianceSpeed = String(pattern.speed); + if (pattern.appearance) data.radianceAppearance = pattern.appearance; + if (pattern.motion === "static") data.radianceMotion = "still"; + else delete data.radianceMotion; + } + + // PRODUCT-2: a product pattern takes no adjustment or override. The + // attributes stay on the element (the page owns them) but are ignored. + guardProduct() { + const data = this.element.dataset; + const present = PRODUCT_LOCKED_ATTRIBUTES.filter(([key]) => data[key] !== undefined).map(([, attr]) => attr); + if (!present.length) return; + warnOnce( + this.element, + "PRODUCT-2", + `data-radiance-pattern="${this.productName}" is a fixed product pattern, so ${present.join(", ")} ` + + `${present.length === 1 ? "is" : "are"} ignored. Product patterns take no adjustment or override; ` + + "only the Radiance admin changes them. See RULES.md section 12." + ); + } + + // SURFACE-1: the base is the host's own background colour. Product + // patterns lock theirs; templates take data-radiance-base, then the + // --radiance-base custom property, then the language default. + resolveBase() { + const theme = this.appearance; + const raw = this.product + ? this.product.base[theme] + : (this.element.dataset.radianceBase || this.cssBase || ""); + const key = `${theme}|${raw}`; + if (key === this.baseKey) return this.baseRgb; + this.baseKey = key; + let rgb = raw ? parseColour(raw) : null; + if (raw && !rgb) { + warnOnce( + this.element, + "SURFACE-1", + `base colour "${raw}" is not an opaque colour, so the default ${theme} base is used. ` + + "Set data-radiance-base (or --radiance-base) to the exact, opaque background of the area this surface sits in." + ); + } + if (!rgb) rgb = theme === "dark" ? [26, 27, 30] : [255, 255, 255]; + this.baseRgb = rgb; + this.baseFill = `rgb(${rgb[0]},${rgb[1]},${rgb[2]})`; + this.staticFrameKey = ""; + return rgb; + } + + get baseTone() { + return `${this.baseRgb[0]},${this.baseRgb[1]},${this.baseRgb[2]}`; + } + + checkConsistency() { + const data = this.element.dataset; + if (this.product) return; + + if (data.radianceIntensity && data.radianceDarkGlow && data.radianceIntensity !== data.radianceDarkGlow) { + warnOnce( + this.element, + "INT-3", + `data-radiance-dark-glow="${data.radianceDarkGlow}" does not match ` + + `data-radiance-intensity="${data.radianceIntensity}". Dark mode draws a different falloff ` + + "when these disagree, so the surface will not match the rest of the product. Set both to the same value." + ); + } + + // MOTION-5 is an absolute guardrail: it applies to the EFFECTIVE speed, + // after any data-radiance-speed-scale percentage has been applied. + const effective = this.speed; + if (Number.isFinite(effective) && (effective < 0.4 || effective > 2)) { + const scale = parseAdjustment(data.radianceSpeedScale); + const via = scale === 1 + ? "" + : ` (${data.radianceSpeed} x ${Math.round(scale * 100)}%)`; + warnOnce( + this.element, + "MOTION-5", + `effective speed ${Math.round(effective * 1000) / 1000}${via} is outside the Radiance ` + + "range 0.4-2.0. Below 0.4 the drift reads as dead, above 2.0 it reads as nervous. " + + "See RULES.md (MOTION-5)." + ); + } + } + + isRenderable() { + if (!isDocumentVisible || !this.element.isConnected || !this.isInViewport) return false; + if (document.documentElement.dataset.radiancePaused === "true" || document.body?.classList.contains("is-proof-paused")) return false; + const slide = this.element.closest(".slide"); + if (slide && !slide.classList.contains("is-active")) return false; + const proofView = this.element.closest(".proof-view"); + if (proofView && !proofView.classList.contains("is-active")) return false; + const style = window.getComputedStyle(this.element); + if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) return false; + this.cssBase = style.getPropertyValue("--radiance-base").trim(); + const rect = this.element.getBoundingClientRect(); + return rect.width > 2 && rect.height > 2; + } + + getConfig() { + const layout = this.layout; + + if (!this.isDark) { + if (layout === "neutral") { + if (this.variant.startsWith("static")) return this.isSubtle ? STATIC_NEUTRAL_LIGHT_SUBTLE_BLOBS : STATIC_NEUTRAL_LIGHT_BLOBS; + return this.isSubtle ? NEUTRAL_LIGHT_SUBTLE_BLOBS : NEUTRAL_LIGHT_BLOBS; + } + const base = this.variant.startsWith("static") + ? (this.isSubtle ? STATIC_LIGHT_SUBTLE_BLOBS : STATIC_LIGHT_BLOBS) + : (this.isSubtle ? LIGHT_SUBTLE_BLOBS : LIGHT_BLOBS); + if (layout === "top-wash") return topBlobSet(base); + if (layout === "bottom-wash") return bottomBlobSet(base); + return layout === "left-wash" ? mirrorBlobSet(base) : base; + } + + if (layout === "neutral") { + if (this.variant.startsWith("static")) return this.isSubtle ? STATIC_NEUTRAL_DARK_SUBTLE_BLOBS : STATIC_NEUTRAL_DARK_PROMINENT_BLOBS; + return this.isSubtle ? NEUTRAL_DARK_SUBTLE_BLOBS : NEUTRAL_DARK_PROMINENT_BLOBS; + } + const base = this.variant.startsWith("static") + ? (this.isSubtle ? STATIC_DARK_SUBTLE_BLOBS : STATIC_DARK_PROMINENT_BLOBS) + : (this.darkGlow === "subtle" || this.isSubtle ? DARK_SUBTLE_BLOBS : DARK_PROMINENT_BLOBS); + if (layout === "top-wash") return topBlobSet(base); + if (layout === "bottom-wash") return bottomBlobSet(base); + return layout === "left-wash" ? mirrorBlobSet(base) : base; + } + + ensureSize() { + if (this.resizeObserver && !this.needsResize && this.width > 0 && this.height > 0) return; + + const rect = this.element.getBoundingClientRect(); + const nextWidth = Math.max(1, Math.round(this.element.clientWidth || rect.width)); + const nextHeight = Math.max(1, Math.round(this.element.clientHeight || rect.height)); + // The spotter engine renders one canvas pixel per CSS pixel and is + // shown pixelated, so its 1.0px film stays crisp (GRAIN-1/3). + const nextDpr = this.isSpotter ? 1 : Math.min(window.devicePixelRatio || 1, MAX_DPR); + this.canvas.style.imageRendering = this.isSpotter ? "pixelated" : ""; + + if (nextWidth === this.width && nextHeight === this.height && nextDpr === this.dpr) { + this.needsResize = false; + return; + } + + this.width = nextWidth; + this.height = nextHeight; + this.dpr = nextDpr; + this.canvas.width = Math.max(1, Math.floor(this.width * this.dpr)); + this.canvas.height = Math.max(1, Math.floor(this.height * this.dpr)); + this.canvas.style.width = `${this.width}px`; + this.canvas.style.height = `${this.height}px`; + this.ctx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + this.ctx.imageSmoothingEnabled = true; + this.ctx.imageSmoothingQuality = "high"; + this.textureKey = ""; + this.staticFrameKey = ""; + this.needsResize = false; + } + + ensureBlobs() { + const configKey = this.product + ? [this.appearance, this.productName, this.variant].join(":") + : [ + this.appearance, + this.darkGlow, + this.element.dataset.radianceLayout || "default", + this.element.dataset.radianceIntensity || "default", + this.variant || "default", + this.element.dataset.radianceMotion || "dynamic", + this.element.dataset.radianceProminence || "100%", + this.element.dataset.radianceSpread || "100%" + ].join(":"); + if (configKey === this.lastConfigKey && this.blobs.length) return; + this.lastConfigKey = configKey; + this.checkConsistency(); + this.staticFrameKey = ""; + const seed = this.seed || configKey; + const random = createSeededRandom(`radiance-blobs:${seed}`); + const prominence = this.prominenceScale; + const spread = this.spreadScale; + const configs = (prominence === 1 && spread === 1) + ? this.getConfig() + : this.getConfig().map((config) => ({ + ...config, + opacity: config.opacity * prominence, + radius: config.radius * spread + })); + this.blobs = configs.map((config) => new RadianceBlob(config, random)); + } + + createGrain(mode) { + const texture = document.createElement("canvas"); + texture.width = Math.max(1, Math.floor(this.width)); + texture.height = Math.max(1, Math.floor(this.height)); + const grainCtx = texture.getContext("2d"); + const isDark = mode === "dark"; + + const rawTexture = document.createElement("canvas"); + const rawWidth = Math.max(1, Math.ceil(texture.width / RADIANCE_FILM_GRAIN_SIZE)); + const rawHeight = Math.max(1, Math.ceil(texture.height / RADIANCE_FILM_GRAIN_SIZE)); + rawTexture.width = rawWidth; + rawTexture.height = rawHeight; + const rawCtx = rawTexture.getContext("2d"); + const image = rawCtx.createImageData(rawWidth, rawHeight); + const lightFilmBright = [ + [232, 248, 252], + [244, 229, 253], + [253, 228, 240], + [253, 244, 212], + [235, 241, 248] + ]; + const lightFilmChroma = [ + [120, 208, 230], + [194, 132, 232], + [244, 132, 196], + [246, 204, 104], + [116, 154, 246], + [128, 218, 194] + ]; + const lightFilmMid = [ + [174, 214, 220], + [204, 177, 224], + [224, 178, 202], + [224, 206, 150], + [184, 196, 210] + ]; + const lightFilmDark = [ + [122, 150, 156], + [150, 124, 168], + [168, 126, 148], + [150, 140, 116], + [132, 138, 146] + ]; + const darkFilmColors = [ + [76, 116, 164], + [122, 82, 140], + [148, 78, 112], + [118, 112, 92], + [132, 138, 148] + ]; + const darkFilmShadows = [ + [10, 12, 16], + [14, 15, 18], + [18, 16, 23], + [16, 18, 24] + ]; + + const writeFilmGrain = (data, alphaMultiplier, random) => { + for (let i = 0; i < data.length; i += 4) { + let color; + let alpha; + let sharedJitter; + let channelJitter; + + if (isDark) { + const toneRoll = random(); + const useShadowFleck = toneRoll < 0.16; + color = useShadowFleck + ? darkFilmShadows[Math.floor(random() * darkFilmShadows.length)] + : darkFilmColors[Math.floor(random() * darkFilmColors.length)]; + alpha = useShadowFleck + ? 7 + Math.floor(random() * 9) + : 14 + Math.floor(random() * 14); + sharedJitter = Math.floor((random() - 0.5) * (useShadowFleck ? 10 : 38)); + channelJitter = useShadowFleck ? 5 : 12; + } else { + const toneRoll = random(); + const palette = toneRoll < 0.68 + ? lightFilmBright + : toneRoll < 0.9 + ? lightFilmMid + : toneRoll < 0.97 + ? lightFilmChroma + : lightFilmDark; + color = palette[Math.floor(random() * palette.length)]; + alpha = toneRoll < 0.68 + ? 44 + Math.floor(random() * 28) + : toneRoll < 0.9 + ? 28 + Math.floor(random() * 22) + : toneRoll < 0.97 + ? 22 + Math.floor(random() * 20) + : 10 + Math.floor(random() * 14); + sharedJitter = Math.floor((random() - 0.5) * (toneRoll < 0.9 ? 28 : 16)); + channelJitter = toneRoll < 0.97 ? 12 : 8; + } + + data[i] = Math.max(0, Math.min(255, color[0] + sharedJitter + Math.floor((random() - 0.5) * channelJitter))); + data[i + 1] = Math.max(0, Math.min(255, color[1] + sharedJitter + Math.floor((random() - 0.5) * channelJitter))); + data[i + 2] = Math.max(0, Math.min(255, color[2] + sharedJitter + Math.floor((random() - 0.5) * channelJitter))); + data[i + 3] = Math.max(0, Math.min(255, Math.round(alpha * alphaMultiplier))); + } + }; + + writeFilmGrain( + image.data, + isDark ? 1.18 : 1.16, + createSeededRandom(`radiance-grain:${mode}:macro:${texture.width}x${texture.height}`) + ); + rawCtx.putImageData(image, 0, 0); + + grainCtx.save(); + grainCtx.imageSmoothingEnabled = false; + grainCtx.drawImage(rawTexture, 0, 0, texture.width, texture.height); + grainCtx.restore(); + + const microTexture = document.createElement("canvas"); + microTexture.width = texture.width; + microTexture.height = texture.height; + const microCtx = microTexture.getContext("2d"); + const microImage = microCtx.createImageData(texture.width, texture.height); + writeFilmGrain( + microImage.data, + isDark ? 0.36 : 0.3, + createSeededRandom(`radiance-grain:${mode}:micro:${texture.width}x${texture.height}`) + ); + microCtx.putImageData(microImage, 0, 0); + grainCtx.drawImage(microTexture, 0, 0); + + return texture; + } + + createDarkDither() { + const texture = document.createElement("canvas"); + texture.width = Math.max(1, Math.floor(this.width * this.dpr)); + texture.height = Math.max(1, Math.floor(this.height * this.dpr)); + const ditherCtx = texture.getContext("2d"); + const image = ditherCtx.createImageData(texture.width, texture.height); + const data = image.data; + const random = createSeededRandom(`radiance-dither:${texture.width}x${texture.height}`); + + for (let i = 0; i < data.length; i += 4) { + const isLightSpeck = random() > 0.44; + const alpha = isLightSpeck + ? 6 + Math.floor(random() * 8) + : 4 + Math.floor(random() * 5); + + data[i] = isLightSpeck ? 255 : 10; + data[i + 1] = isLightSpeck ? 255 : 12; + data[i + 2] = isLightSpeck ? 255 : 16; + data[i + 3] = alpha; + } + + ditherCtx.putImageData(image, 0, 0); + return texture; + } + + drawLightRightEdgeSupport(t) { + const ctx = this.ctx; + const w = this.width; + const h = this.height; + ctx.save(); + ctx.globalCompositeOperation = "source-over"; + + const intensity = (this.isSubtle ? 0.58 : 1) * this.prominenceScale; + const pulse = (0.92 + 0.08 * Math.sin(t * 0.0005)) * intensity; + const rightWash = ctx.createLinearGradient(w * 0.36, 0, w, 0); + rightWash.addColorStop(0, "rgba(255,255,255,0)"); + rightWash.addColorStop(0.42, `rgba(200,220,255,${0.045 * pulse})`); + rightWash.addColorStop(0.66, `rgba(140,100,255,${0.075 * pulse})`); + rightWash.addColorStop(0.84, `rgba(255,120,160,${0.085 * pulse})`); + rightWash.addColorStop(1, `rgba(40,140,255,${0.11 * pulse})`); + ctx.fillStyle = rightWash; + ctx.fillRect(0, 0, w, h); + + const supportRadius = Math.max(w, h) * 0.42; + const supportGlows = [ + { x: w * 1.02, y: h * 0.12, radius: supportRadius, color: [255, 120, 160], alpha: 0.18 }, + { x: w * 0.96, y: h * 0.42, radius: supportRadius * 1.05, color: [140, 100, 255], alpha: 0.16 }, + { x: w * 1.02, y: h * 0.86, radius: supportRadius * 1.08, color: [40, 140, 255], alpha: 0.18 }, + { x: w * 0.84, y: h * 0.98, radius: supportRadius * 0.9, color: [80, 220, 180], alpha: 0.035 } + ]; + + for (const glow of supportGlows) { + const [r, g, b] = glow.color; + const grd = ctx.createRadialGradient(glow.x, glow.y, 0, glow.x, glow.y, glow.radius); + grd.addColorStop(0, `rgba(${r},${g},${b},${glow.alpha * pulse})`); + grd.addColorStop(0.58, `rgba(${r},${g},${b},${glow.alpha * 0.3 * pulse})`); + grd.addColorStop(1, `rgba(${r},${g},${b},0)`); + ctx.fillStyle = grd; + ctx.fillRect(0, 0, w, h); + } + + ctx.restore(); + } + + drawDarkRightEdgeSupport(t) { + const ctx = this.ctx; + const w = this.width; + const h = this.height; + ctx.save(); + ctx.globalCompositeOperation = "screen"; + + const intensity = (this.isSubtle ? 0.58 : 1) * this.prominenceScale; + const pulse = (0.86 + 0.14 * Math.sin(t * 0.00062)) * intensity; + const rightWash = ctx.createLinearGradient(w * 0.5, 0, w, 0); + rightWash.addColorStop(0, "rgba(0,0,0,0)"); + rightWash.addColorStop(0.56, `rgba(138,93,255,${0.035 * pulse})`); + rightWash.addColorStop(0.82, `rgba(39,140,255,${0.05 * pulse})`); + rightWash.addColorStop(1, `rgba(255,93,142,${0.055 * pulse})`); + ctx.fillStyle = rightWash; + ctx.fillRect(0, 0, w, h); + + const cornerGlowRadius = Math.max(w, h) * 0.44; + const cornerGlows = [ + { x: w * 1.03, y: h * 0.06, radius: cornerGlowRadius, color: [255, 93, 142], alpha: 0.14 }, + { x: w * 1.04, y: h * 0.92, radius: cornerGlowRadius * 1.05, color: [39, 140, 255], alpha: 0.15 }, + { x: w * 0.9, y: h * 1.02, radius: cornerGlowRadius * 0.82, color: [45, 220, 177], alpha: 0.03 } + ]; + + for (const glow of cornerGlows) { + const [r, g, b] = glow.color; + const grd = ctx.createRadialGradient(glow.x, glow.y, 0, glow.x, glow.y, glow.radius); + grd.addColorStop(0, `rgba(${r},${g},${b},${glow.alpha * pulse})`); + grd.addColorStop(0.58, `rgba(${r},${g},${b},${glow.alpha * 0.28 * pulse})`); + grd.addColorStop(1, `rgba(${r},${g},${b},0)`); + ctx.fillStyle = grd; + ctx.fillRect(0, 0, w, h); + } + + ctx.restore(); + } + + drawLightTopSupport(t) { + const ctx = this.ctx; + const w = this.width; + const h = this.height; + ctx.save(); + ctx.globalCompositeOperation = "source-over"; + + const intensity = (this.isSubtle ? 0.64 : 1) * this.prominenceScale; + const pulse = (0.9 + 0.1 * Math.sin(t * 0.0007)) * intensity; + const topWash = ctx.createLinearGradient(0, 0, 0, h); + topWash.addColorStop(0, `rgba(200,220,255,${0.105 * pulse})`); + topWash.addColorStop(0.18, `rgba(140,100,255,${0.062 * pulse})`); + topWash.addColorStop(0.34, `rgba(255,120,160,${0.052 * pulse})`); + topWash.addColorStop(0.58, `rgba(255,200,220,${0.024 * pulse})`); + topWash.addColorStop(1, "rgba(255,255,255,0)"); + ctx.fillStyle = topWash; + ctx.fillRect(0, 0, w, h); + + const supportRadius = Math.max(w, h) * 0.42; + const supportGlows = [ + { x: w * 0.16, y: h * -0.04, radius: supportRadius, color: [255, 120, 160], alpha: 0.13 }, + { x: w * 0.36, y: h * -0.05, radius: supportRadius * 1.04, color: [140, 100, 255], alpha: 0.13 }, + { x: w * 0.64, y: h * -0.02, radius: supportRadius * 1.08, color: [40, 140, 255], alpha: 0.15 }, + { x: w * 0.86, y: h * 0.02, radius: supportRadius * 1.12, color: [80, 220, 180], alpha: 0.06 } + ]; + + for (const glow of supportGlows) { + const [r, g, b] = glow.color; + const grd = ctx.createRadialGradient(glow.x, glow.y, 0, glow.x, glow.y, glow.radius); + grd.addColorStop(0, `rgba(${r},${g},${b},${glow.alpha * pulse})`); + grd.addColorStop(0.52, `rgba(${r},${g},${b},${glow.alpha * 0.28 * pulse})`); + grd.addColorStop(1, `rgba(${r},${g},${b},0)`); + ctx.fillStyle = grd; + ctx.fillRect(0, 0, w, h); + } + + ctx.restore(); + } + + drawDarkTopSupport(t) { + const ctx = this.ctx; + const w = this.width; + const h = this.height; + ctx.save(); + ctx.globalCompositeOperation = "screen"; + + const intensity = (this.isSubtle ? 0.68 : 1) * this.prominenceScale; + const pulse = (0.86 + 0.14 * Math.sin(t * 0.00072)) * intensity; + const topWash = ctx.createLinearGradient(0, 0, 0, h); + topWash.addColorStop(0, `rgba(138,93,255,${0.082 * pulse})`); + topWash.addColorStop(0.18, `rgba(39,140,255,${0.058 * pulse})`); + topWash.addColorStop(0.34, `rgba(255,93,142,${0.043 * pulse})`); + topWash.addColorStop(0.58, `rgba(255,170,210,${0.018 * pulse})`); + topWash.addColorStop(1, "rgba(0,0,0,0)"); + ctx.fillStyle = topWash; + ctx.fillRect(0, 0, w, h); + + const supportRadius = Math.max(w, h) * 0.42; + const supportGlows = [ + { x: w * 0.18, y: h * -0.04, radius: supportRadius, color: [255, 93, 142], alpha: 0.105 }, + { x: w * 0.34, y: h * -0.05, radius: supportRadius * 1.04, color: [138, 93, 255], alpha: 0.12 }, + { x: w * 0.62, y: h * -0.02, radius: supportRadius * 1.08, color: [39, 140, 255], alpha: 0.13 }, + { x: w * 0.86, y: h * 0.02, radius: supportRadius * 1.12, color: [45, 220, 177], alpha: 0.035 } + ]; + + for (const glow of supportGlows) { + const [r, g, b] = glow.color; + const grd = ctx.createRadialGradient(glow.x, glow.y, 0, glow.x, glow.y, glow.radius); + grd.addColorStop(0, `rgba(${r},${g},${b},${glow.alpha * pulse})`); + grd.addColorStop(0.54, `rgba(${r},${g},${b},${glow.alpha * 0.3 * pulse})`); + grd.addColorStop(1, `rgba(${r},${g},${b},0)`); + ctx.fillStyle = grd; + ctx.fillRect(0, 0, w, h); + } + + ctx.restore(); + } + + drawNeutralSupport(t) { + const ctx = this.ctx; + const w = this.width; + const h = this.height; + const cycle = t * 0.00044; + const focusX = w * (0.5 + Math.sin(cycle) * 0.04); + const focusY = h * (0.48 + Math.cos(cycle * 0.86) * 0.035); + const radius = Math.max(w, h) * 0.74; + const washAlpha = (this.isSubtle ? 1.18 : 0.88) / this.prominenceScale; + + ctx.save(); + ctx.globalCompositeOperation = "source-over"; + + const tone = this.baseTone; + const centerWash = ctx.createRadialGradient(focusX, focusY, radius * 0.06, focusX, focusY, radius); + if (this.isDark) { + centerWash.addColorStop(0, `rgba(${tone},${0.18 * washAlpha})`); + centerWash.addColorStop(0.48, `rgba(${tone},${0.08 * washAlpha})`); + centerWash.addColorStop(1, `rgba(${tone},0)`); + } else { + centerWash.addColorStop(0, `rgba(${tone},${0.34 * washAlpha})`); + centerWash.addColorStop(0.46, `rgba(${tone},${0.18 * washAlpha})`); + centerWash.addColorStop(1, `rgba(${tone},0)`); + } + ctx.fillStyle = centerWash; + ctx.fillRect(0, 0, w, h); + + const crossWash = ctx.createLinearGradient(0, h * 0.1, w, h * 0.92); + if (this.isDark) { + crossWash.addColorStop(0, `rgba(${tone},${0.08 * washAlpha})`); + crossWash.addColorStop(0.52, `rgba(${tone},0)`); + crossWash.addColorStop(1, `rgba(${tone},${0.065 * washAlpha})`); + } else { + crossWash.addColorStop(0, `rgba(${tone},${0.08 * washAlpha})`); + crossWash.addColorStop(0.5, `rgba(${tone},0)`); + crossWash.addColorStop(1, `rgba(${tone},${0.07 * washAlpha})`); + } + ctx.fillStyle = crossWash; + ctx.fillRect(0, 0, w, h); + + const minSide = Math.min(w, h); + const veilAlpha = (this.isSubtle ? 1.34 : 0.32) / this.prominenceScale; + const veilTone = tone; + + for (const veil of NEUTRAL_VEIL_BLOBS) { + const x = w * veil.anchorX + Math.sin(t * veil.freqX + veil.phase) * veil.orbitX; + const y = h * veil.anchorY + Math.cos(t * veil.freqY + veil.phase) * veil.orbitY; + const veilRadius = minSide * veil.radius; + const alpha = veil.opacity * veilAlpha; + const neutralBlob = ctx.createRadialGradient(x, y, veilRadius * 0.06, x, y, veilRadius); + neutralBlob.addColorStop(0, `rgba(${veilTone},${alpha})`); + neutralBlob.addColorStop(0.54, `rgba(${veilTone},${alpha * 0.42})`); + neutralBlob.addColorStop(1, `rgba(${veilTone},0)`); + ctx.fillStyle = neutralBlob; + ctx.fillRect(0, 0, w, h); + } + ctx.restore(); + } + + // GRAIN-4 (experiment): keep grain inside the colour field. + // The draw methods all write to this.ctx, so swap it for the offscreen + // field context rather than threading a target through every method. + renderColourField(t) { + const realCtx = this.ctx; + this.fieldCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + this.fieldCtx.clearRect(0, 0, this.width, this.height); + + this.fieldCtx.save(); + this.fieldCtx.filter = `blur(${this.layout === "neutral" ? 22 : 40}px)`; + for (const blob of this.blobs) { + blob.update(t, this.width, this.height, this.mouse, this.breathT); + blob.draw(this.fieldCtx); + } + this.fieldCtx.restore(); + + this.ctx = this.fieldCtx; + try { + this.drawSupport(t); + } finally { + this.ctx = realCtx; + } + } + + // Dark keeps its own colour compositing (each layer screened onto the + // base separately). This pass exists only to collect the field's ALPHA, + // so the colours it produces here are never shown. + renderDarkColourField(t) { + const realCtx = this.ctx; + this.fieldCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + this.fieldCtx.globalCompositeOperation = "source-over"; + this.fieldCtx.clearRect(0, 0, this.width, this.height); + + this.fieldCtx.save(); + this.fieldCtx.filter = `blur(${this.layout === "neutral" ? 40 : 64}px)`; + this.fieldCtx.drawImage(this.blobCanvas, 0, 0, this.width, this.height); + this.fieldCtx.restore(); + + this.ctx = this.fieldCtx; + try { + this.drawSupport(t); + } finally { + this.ctx = realCtx; + } + } + + // Stack the colour field onto itself so the mask reads closer to + // present/absent than to the field's own opacity. Without this the + // texture would be thinned everywhere in proportion to colour strength. + buildColourMask(saturation) { + const maskCtx = this.maskCtx; + const mw = this.maskCanvas.width; + const mh = this.maskCanvas.height; + maskCtx.setTransform(1, 0, 0, 1, 0, 0); + maskCtx.globalCompositeOperation = "source-over"; + maskCtx.imageSmoothingEnabled = true; + maskCtx.clearRect(0, 0, mw, mh); + // Stacking n copies gives 1 - (1 - a)^n; drawing the mask onto itself + // squares that, so 3 copies doubled twice is exactly the 12th power. + let power = saturation; + let doublings = 0; + while (power % 2 === 0 && power > 3) { + power /= 2; + doublings += 1; + } + for (let pass = 0; pass < power; pass += 1) { + maskCtx.drawImage(this.fieldCanvas, 0, 0, mw, mh); + } + for (let pass = 0; pass < doublings; pass += 1) { + maskCtx.drawImage(this.maskCanvas, 0, 0); + } + } + + // GRAIN-4: draw a texture through the colour mask, so it never lands on + // the bare surface. Call buildColourMask() first. + drawMaskedTexture(texture, alpha = 1) { + const grainCtx = this.grainMaskCtx; + grainCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + grainCtx.globalCompositeOperation = "source-over"; + grainCtx.clearRect(0, 0, this.width, this.height); + grainCtx.imageSmoothingEnabled = false; + grainCtx.drawImage(texture, 0, 0, this.width, this.height); + grainCtx.globalCompositeOperation = "destination-in"; + grainCtx.imageSmoothingEnabled = true; + grainCtx.drawImage(this.maskCanvas, 0, 0, this.width, this.height); + grainCtx.globalCompositeOperation = "source-over"; + + this.ctx.save(); + this.ctx.globalAlpha = alpha; + this.ctx.imageSmoothingEnabled = false; + this.ctx.drawImage(this.grainCanvas, 0, 0, this.width, this.height); + this.ctx.restore(); + } + + // F1: the fine noise layer, through the colour mask (GRAIN-4). + drawMaskedOverlay(theme) { + const pattern = getOverlayPattern(theme, this.dpr, this.grainMaskCtx); + if (!pattern) return; + const film = FILM[theme]; + const grainCtx = this.grainMaskCtx; + grainCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + grainCtx.globalCompositeOperation = "source-over"; + grainCtx.clearRect(0, 0, this.width, this.height); + grainCtx.fillStyle = pattern; + grainCtx.fillRect(0, 0, this.width, this.height); + grainCtx.globalCompositeOperation = "destination-in"; + grainCtx.imageSmoothingEnabled = true; + grainCtx.drawImage(this.maskCanvas, 0, 0, this.width, this.height); + grainCtx.globalCompositeOperation = "source-over"; + + this.ctx.save(); + this.ctx.globalAlpha = film.overlay; + this.ctx.globalCompositeOperation = film.overlayBlend; + this.ctx.imageSmoothingEnabled = false; + this.ctx.drawImage(this.grainCanvas, 0, 0, this.width, this.height); + this.ctx.restore(); + } + + // F1: the tone lift (Home's saturate/contrast), applied to the colour + // field only - the bare surface keeps the host's exact base colour. + applyToneLift(theme) { + const film = FILM[theme]; + const liftCtx = this.liftCtx; + const w = this.canvas.width; + const h = this.canvas.height; + liftCtx.setTransform(1, 0, 0, 1, 0, 0); + liftCtx.globalCompositeOperation = "copy"; + liftCtx.filter = `saturate(${film.saturate}) contrast(${film.contrast})`; + liftCtx.drawImage(this.canvas, 0, 0); + liftCtx.filter = "none"; + liftCtx.globalCompositeOperation = "destination-in"; + liftCtx.imageSmoothingEnabled = true; + liftCtx.drawImage(this.maskCanvas, 0, 0, w, h); + liftCtx.globalCompositeOperation = "source-over"; + + this.ctx.save(); + this.ctx.setTransform(1, 0, 0, 1, 0, 0); + this.ctx.globalAlpha = 1; + this.ctx.globalCompositeOperation = "source-over"; + this.ctx.drawImage(this.liftCanvas, 0, 0); + this.ctx.restore(); + } + + drawSupport(t) { + if (this.layout === "neutral") { + this.drawNeutralSupport(t); + return; + } + + if (this.layout === "top-wash") { + if (this.isDark) this.drawDarkTopSupport(t); + else this.drawLightTopSupport(t); + return; + } + + if (this.layout === "bottom-wash") { + this.ctx.save(); + this.ctx.translate(0, this.height); + this.ctx.scale(1, -1); + if (this.isDark) this.drawDarkTopSupport(t); + else this.drawLightTopSupport(t); + this.ctx.restore(); + return; + } + + const draw = () => { + if (this.isDark) { + this.drawDarkRightEdgeSupport(t); + } else { + this.drawLightRightEdgeSupport(t); + } + }; + + if (this.layout === "left-wash") { + this.ctx.save(); + this.ctx.translate(this.width, 0); + this.ctx.scale(-1, 1); + draw(); + this.ctx.restore(); + } else { + draw(); + } + } + + drawDarkFalloff() { + const ctx = this.ctx; + if (this.layout === "top-wash" || this.layout === "bottom-wash") { + const startY = this.layout === "bottom-wash" ? this.height : 0; + const endY = this.layout === "bottom-wash" ? 0 : this.height; + const verticalFalloff = ctx.createLinearGradient(0, startY, 0, endY); + const tone = this.baseTone; + verticalFalloff.addColorStop(0, `rgba(${tone},0.26)`); + verticalFalloff.addColorStop(0.28, `rgba(${tone},0.16)`); + verticalFalloff.addColorStop(0.58, `rgba(${tone},0.06)`); + verticalFalloff.addColorStop(1, `rgba(${tone},0)`); + ctx.fillStyle = verticalFalloff; + ctx.fillRect(0, 0, this.width, this.height); + return; + } + const startX = this.layout === "left-wash" ? this.width : 0; + const endX = this.layout === "left-wash" ? 0 : this.width; + const falloff = ctx.createLinearGradient(startX, 0, endX, this.height); + const falloffTone = this.baseTone; + falloff.addColorStop(0, `rgba(${falloffTone},0.38)`); + falloff.addColorStop(0.42, `rgba(${falloffTone},0.2)`); + falloff.addColorStop(0.78, `rgba(${falloffTone},0.04)`); + falloff.addColorStop(1, `rgba(${falloffTone},0)`); + ctx.fillStyle = falloff; + ctx.fillRect(0, 0, this.width, this.height); + } + + ensureTextures() { + const nextKey = `${this.width}x${this.height}@${this.dpr}:${this.appearance}`; + if (nextKey === this.textureKey) return; + this.textureKey = nextKey; + + if (this.isDark) { + this.lightGrain = undefined; + this.darkGrain = this.getCachedTexture("dark-grain", () => this.createGrain("dark")); + this.darkDither = this.getCachedTexture("dark-dither", () => this.createDarkDither()); + } else { + this.lightGrain = this.getCachedTexture("light-grain", () => this.createGrain("light")); + this.darkGrain = undefined; + this.darkDither = undefined; + } + + this.blobCanvas.width = Math.max(1, Math.floor(this.width * this.dpr)); + this.blobCanvas.height = Math.max(1, Math.floor(this.height * this.dpr)); + this.blobCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + for (const target of [this.fieldCanvas, this.grainCanvas, this.liftCanvas]) { + target.width = this.blobCanvas.width; + target.height = this.blobCanvas.height; + } + this.maskCanvas.width = Math.max(1, Math.ceil(this.blobCanvas.width * MASK_SCALE)); + this.maskCanvas.height = Math.max(1, Math.ceil(this.blobCanvas.height * MASK_SCALE)); + this.fieldCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + this.grainMaskCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + this.staticFrameKey = ""; + } + + getCachedTexture(kind, factory) { + const key = `${kind}:${this.width}x${this.height}@${this.dpr}`; + const cachedTexture = textureCache.get(key); + if (cachedTexture) return cachedTexture; + return rememberTexture(key, factory()); + } + + // "page" film (the Home product): the full-surface grain Home was built + // on; its page recipe fades and tones it. + /* A product whose colour sits below full strength (Home's hero) mixes it + toward the base here, before the grain, so the grain keeps its one + value (GRAIN-6). */ + drawFieldOpacity() { + const opacity = this.product && this.product.fieldOpacity ? this.product.fieldOpacity[this.isDark ? "dark" : "light"] : 1; + if (!(opacity < 1)) return; + this.ctx.save(); + this.ctx.globalCompositeOperation = "source-over"; + this.ctx.globalAlpha = 1 - opacity; + this.ctx.fillStyle = this.baseFill; + this.ctx.fillRect(0, 0, this.width, this.height); + this.ctx.restore(); + } + + drawPlainTexture(texture, alpha) { + if (!texture) return; + this.ctx.save(); + this.ctx.globalAlpha = alpha; + this.ctx.imageSmoothingEnabled = false; + this.ctx.drawImage(texture, 0, 0, this.width, this.height); + this.ctx.restore(); + } + + /* ---- the Spotter radiance engine (product patterns spotterx, liveboard) ---- */ + + /* Locked: the values SpotterX and Liveboard ship (SBG_TUNING). Only the + state comes from the page; the admin lab may preview other values on + one surface (RadianceLanguageRenderer.admin). */ + get sbgTuning() { + const raw = (this.element.dataset.radianceState || "idle").trim().toLowerCase(); + let state = PRODUCT_STATES[raw]; + if (!state) { + warnOnce(this.element, "PRODUCT-4", `data-radiance-state="${raw}" is not a state. Use idle, reasoning or answered.`); + state = PRODUCT_STATES.idle; + } + const tuning = { ...SBG_TUNING }; + const admin = ADMIN_SPOTTER.get(this.element); + if (admin) { + Object.keys(SBG_TUNING).forEach((key) => { + if (Number.isFinite(admin[key])) tuning[key] = admin[key]; + }); + } + return { energy: state[0], settled: state[1], ...tuning }; + } + + /* The state levels for a theme: SBG_STATES, or the admin lab's preview. */ + sbgLevels(theme) { + const admin = ADMIN_SPOTTER.get(this.element); + const levels = admin && admin.levels && admin.levels[theme]; + return levels ? { ...SBG_STATES[theme], ...levels } : SBG_STATES[theme]; + } + + /* The grain strength for a theme: the language's one grain (FILM, + GRAIN-6), or the admin lab's preview of a new one. */ + sbgGrainStrength(theme) { + const admin = ADMIN_SPOTTER.get(this.element); + const grain = admin && admin.grain && admin.grain[theme]; + return Number.isFinite(grain) ? clamp(grain, 0, 1) : FILM[theme].grain; + } + + ensureSbg(tune) { + const key = `${this.width}x${this.height}`; + if (this.sbg && this.sbg.key === key) return this.sbg; + const prev = this.sbg; + const W = this.width; + const H = this.height; + const spacing = clamp(W / 6.4, 170, 300); + const radius = spacing * 1.6; + /* A blob wraps from one edge to the other only when fully out of + view: widest horizontal extent of the tilted, stretched, breathing + ellipse (~2.4 radii) + wander + blur. */ + const reachX = radius * 2.4 + spacing * 0.5 + 80; + const count = Math.max(6, Math.ceil((W + reachX * 2) / spacing)); + const band = count * spacing; + const rand = (lo, hi) => lo + Math.random() * (hi - lo); + const blobs = []; + let walk = { i: 1, d: 1, hold: false, cool: false, warm: 0, run: 1 }; + for (let i = 0; i < count; i += 1) { + const blob = { slot: i, lap: null }; + RadianceSurface.reseedBlob(blob, walk, spacing, band, W); + blobs.push(blob); + walk = RadianceSurface.walkHue(walk); + } + /* The reasoning stream: fewer, smaller lights flowing the other way. */ + const streamSpacing = spacing * 1.7; + const streamCount = Math.max(4, Math.ceil((W + reachX * 2) / streamSpacing)); + const streamBand = streamCount * streamSpacing; + const stream = []; + for (let i = 0; i < streamCount; i += 1) { + stream.push({ + x0: -(streamBand - W) / 2 + (i + 0.5 + rand(-0.25, 0.25)) * streamSpacing, + sig: rand(0.8, 1.2), + f: [rand(0.0006, 0.001), rand(0.0011, 0.0017), rand(0.0005, 0.0011), rand(0.0007, 0.0013)], + p: [rand(0, TAU), rand(0, TAU), rand(0, TAU), rand(0, TAU)], + bp: rand(0, TAU), + bMs: rand(1500, 2800) + }); + } + const lw = Math.ceil((W + SBG_PAD * 2) * SBG_SCALE); + const lh = Math.ceil((H + SBG_PAD) * SBG_SCALE); + const layer = () => { + const canvas = document.createElement("canvas"); + canvas.width = lw; + canvas.height = lh; + return { canvas, ctx: canvas.getContext("2d") }; + }; + this.sbg = { + key, W, H, spacing, radius, band, blobs, lw, lh, + margin: (band - W) / 2, + stream, streamSpacing, streamBand, + streamMargin: (streamBand - W) / 2, + ax: new Float32Array(count), + ah: new Array(count), + blob: layer(), + field: layer(), + grainKey: "", grain: null, + clock: prev ? prev.clock : rand(0, 600000), + chorus: prev ? prev.chorus : 0, + energy: prev ? prev.energy : tune.energy, + vel: prev ? prev.vel : 0, + target: prev ? prev.target : tune.energy, + settled: prev ? prev.settled : tune.settled, + settledVel: prev ? prev.settledVel : 0, + last: 0, + cost: prev ? prev.cost : 0, + drawnH: H, + drawnTheme: "" + }; + return this.sbg; + } + + /* Home's hero grain: the canonical passes at the hero's opacity. */ + sbgGrain(S) { + const strength = this.sbgGrainStrength(this.isDark ? "dark" : "light"); + const key = `${S.W}x${S.H}:${this.appearance}:${strength}`; + if (S.grainKey === key && S.grain) return S.grain; + const texture = document.createElement("canvas"); + texture.width = S.W; + texture.height = S.H; + const tctx = texture.getContext("2d"); + tctx.imageSmoothingEnabled = false; + if (this.isDark) { + tctx.globalAlpha = 0.42 * strength; + tctx.drawImage(this.darkDither, 0, 0, S.W, S.H); + tctx.globalAlpha = strength; + tctx.drawImage(this.darkGrain, 0, 0, S.W, S.H); + } else { + tctx.globalAlpha = strength; + tctx.drawImage(this.lightGrain, 0, 0, S.W, S.H); + } + S.grain = texture; + S.grainKey = key; + return texture; + } + + /* One step of the colour walk (see SBG_PATH). State: i (index on the + path), d (direction), hold (repeat once), cool (peach seen - no second + peach before violet), warm / run (length of the current warm / cool + stretch). */ + static walkHue(state) { + const isWarm = (index) => index >= 3; + let next; + if (SBG_PATH[state.i] === "pink" && state.warm >= 3) { + next = { i: 2, d: -1, hold: false, cool: true }; + } else if (!isWarm(state.i) && state.run >= 5) { + next = { i: state.i + 1, d: 1, hold: false, cool: false }; + } else { + next = RadianceSurface.walkStep(state); + if (!isWarm(state.i) && isWarm(next.i) && state.run < 2) { + next = { i: 1, d: -1, hold: false, cool: next.cool }; + } + } + next.warm = isWarm(next.i) ? (isWarm(state.i) ? state.warm + 1 : 1) : 0; + next.run = isWarm(next.i) ? 0 : (isWarm(state.i) ? 1 : state.run + 1); + return next; + } + + static walkStep(state) { + const { i, hold } = state; + let { d, cool } = state; + if (hold) return { i: i + d, d, hold: false, cool }; + const roll = Math.random(); + const hue = SBG_PATH[i]; + if (hue === "peach") return { i: i - 1, d: -1, hold: false, cool: true }; + if (hue === "mint") return { i: i + 1, d: 1, hold: false, cool }; + if (hue === "blue") { + if (d === -1) { + if (roll < 0.3) return { i: i - 1, d: -1, hold: false, cool }; + if (roll < 0.72) return { i, d: 1, hold: true, cool }; + return { i: i + 1, d: 1, hold: false, cool }; + } + if (roll < 0.1) return { i: i - 1, d: -1, hold: false, cool }; + if (roll < 0.18) return { i, d, hold: false, cool }; + return { i: i + 1, d, hold: false, cool }; + } + if (hue === "violet") { + cool = false; + if (roll < 0.14) d = -d; + else if (roll < 0.22) return { i, d, hold: false, cool }; + return { i: i + d, d, hold: false, cool }; + } + if (d === 1 && !cool) { + if (roll < 0.4) return { i: i + 1, d: 1, hold: false, cool }; + if (roll < 0.5) return { i, d, hold: false, cool }; + return { i: i - 1, d: -1, hold: false, cool }; + } + if (roll < 0.1) return { i, d: -1, hold: false, cool }; + return { i: i - 1, d: -1, hold: false, cool }; + } + + /* A blob's identity: hue, slot jitter, size, and per-blob frequencies + (rad per clock-ms) - every motion is 2-3 sines at incommensurate + ratios, so no blob ever retraces a path. */ + static reseedBlob(blob, walk, spacing, band, W) { + const rand = (lo, hi) => lo + Math.random() * (hi - lo); + const wx = rand(0.00045, 0.0008); + const wy = rand(0.0004, 0.0009); + const wr = rand(0.0006, 0.0011); + const ws = rand(0.0005, 0.0012); + const wt = rand(0.0005, 0.0012); + const wq = rand(0.00025, 0.0005); + blob.walk = walk; + blob.hue = SBG_PATH[walk.i]; + blob.x0 = -(band - W) / 2 + (blob.slot + 0.5 + rand(-0.18, 0.18)) * spacing; + blob.sig = rand(0.92, 1.08); + blob.amp = rand(0.9, 1.1); + blob.f = [ + wx, wx * rand(1.52, 1.72), wx * rand(2.3, 2.6), + wy, wy * rand(1.6, 1.9), + wr, wr * rand(1.4, 1.7), + ws, ws * rand(1.5, 1.8), + wt, wt * rand(1.5, 1.8), + wq, wq * rand(1.6, 1.9) + ]; + blob.p = Array.from({ length: 13 }, () => rand(0, TAU)); + const B = SBG_MOTION.breathMs; + blob.bRest = rand(B.rest[0], B.rest[1]); + blob.bReason = rand(B.reason[0], B.reason[1]); + blob.bCalm = rand(B.calm[0], B.calm[1]); + blob.bp = rand(0, TAU); + } + + /* Exact solution of a critically damped spring step: stable at any dt. */ + static spring(value, velocity, target, omega, dt) { + const e0 = value - target; + const k = velocity + omega * e0; + const decay = Math.exp(-omega * dt); + return [target + (e0 + k * dt) * decay, (velocity - omega * k * dt) * decay]; + } + + renderSbg(timestamp) { + const started = performance.now(); + const tune = this.sbgTuning; + const S = this.ensureSbg(tune); + const theme = this.isDark ? "dark" : "light"; + const still = this.isStill; + const M = SBG_MOTION; + + const dtMs = S.last ? clamp(timestamp - S.last, 0, 250) : 0; + S.last = timestamp; + const dt = dtMs / 1000; + if (tune.energy > 0.5 && S.target <= 0.5) S.chorus = 0; + S.target = tune.energy; + [S.energy, S.vel] = RadianceSurface.spring(S.energy, S.vel, tune.energy, + (tune.energy > S.energy ? M.rise : M.fall) / tune.pace, dt); + [S.settled, S.settledVel] = RadianceSurface.spring(S.settled, S.settledVel, tune.settled, M.settle / tune.pace, dt); + const E = clamp(S.energy, 0, 1); + const calm = clamp(S.settled, 0, 1); + + const m = tune.flow; + const rateRest = mix(M.speedDefault, M.speedSettled, calm) * m; + const rate = Math.min(M.speedCap, mix(rateRest, M.speedReason * m, E)); + const tempo = Math.sqrt(Math.max(m, 0.05) / 2.5); + if (!still) { + S.clock += dtMs * rate; + S.chorus += (TAU * dtMs / M.chorusMs) * tempo * (1 + 0.06 * Math.sin(S.clock * 0.00013)); + } + const t = S.clock; + const breath = still ? 0 : tune.breath; + const sizeSwing = mix(mix(M.breathSize.rest, M.breathSize.calm, calm), M.breathSize.reason, E) * breath; + const glowSwing = mix(mix(M.breathGlow.rest, M.breathGlow.calm, calm), M.breathGlow.reason, E) * breath; + const chorus = wave(S.chorus); + const chorusSize = 1 + M.chorusSize * E * breath * (chorus - 0.3); + const chorusGlow = 1 + M.chorusGlow * E * breath * (chorus - 0.5); + const state = this.sbgLevels(theme); + const restLevel = mix(state.rest, Math.min(1, state.calm * tune.calmGain) * state.rest, calm); + const level = mix(restLevel, state.reason, E); + const alphaNow = level * tune.gain; + const boost = level / mix(restLevel, state.floor, E); + const palette = SBG_PALETTE[theme]; + const W = S.W; + const H = S.H; + const baseLift = SBG_BASE_LIFT + tune.lift; + const lift = baseLift - S.radius * SBG_CALM_RISE * calm; + const wander = S.spacing * (1 + M.wanderReason * E); + + /* Blobs, at quarter resolution, in CSS-pixel coordinates. The drift's + own speed swells and eases on two slow sines (never reversing). */ + const bctx = S.blob.ctx; + bctx.setTransform(1, 0, 0, 1, 0, 0); + bctx.globalCompositeOperation = "source-over"; + bctx.clearRect(0, 0, S.lw, S.lh); + bctx.setTransform(SBG_SCALE, 0, 0, SBG_SCALE, SBG_PAD * SBG_SCALE, SBG_PAD * SBG_SCALE); + const flowX = t * M.flow + S.spacing * (0.5 * Math.sin(t * 0.000061) + 0.3 * Math.sin(t * 0.000097 + 1.3)); + /* A blob that has just wrapped (it is off-screen, entering on the + left) is reborn: the next step of the colour walk from its + right-hand neighbour, fresh size, timing and shape. */ + for (const blob of S.blobs) { + const lap = Math.floor((blob.x0 + flowX + S.margin) / S.band); + if (blob.lap !== null && lap !== blob.lap) { + const right = S.blobs[(blob.slot + 1) % S.blobs.length]; + RadianceSurface.reseedBlob(blob, RadianceSurface.walkHue(right.walk), S.spacing, S.band, W); + blob.lap = Math.floor((blob.x0 + flowX + S.margin) / S.band); + } else { + blob.lap = lap; + } + } + const draw = (x, y, r, sx, sy, tilt, rgb, opacity) => { + bctx.save(); + bctx.translate(x, y); + bctx.rotate(tilt); + bctx.scale(sx, sy); + const gradient = bctx.createRadialGradient(0, 0, 0, 0, 0, r); + gradient.addColorStop(0, `rgba(${rgb[0]},${rgb[1]},${rgb[2]},${opacity})`); + gradient.addColorStop(1, `rgba(${rgb[0]},${rgb[1]},${rgb[2]},0)`); + bctx.fillStyle = gradient; + bctx.beginPath(); + bctx.arc(0, 0, r, 0, TAU); + bctx.fill(); + bctx.restore(); + }; + let placed = 0; + for (const blob of S.blobs) { + const f = blob.f; + const q = blob.p; + let x = (blob.x0 + flowX + S.margin) % S.band; + if (x < 0) x += S.band; + x -= S.margin; + x += wander * (0.24 * Math.sin(t * f[0] + q[0]) + 0.13 * Math.sin(t * f[1] + q[1]) + 0.07 * Math.sin(t * f[2] + q[2])); + S.ax[placed] = x; + S.ah[placed] = blob.hue; + placed += 1; + if (!still) blob.bp += (TAU * dtMs / mix(mix(blob.bRest, blob.bCalm, calm), blob.bReason, E)) * tempo; + const own = wave(blob.bp); + const r = S.radius * SBG_SIZE[blob.hue] * blob.sig + * (1 + 0.1 * Math.sin(t * f[5] + q[5]) + 0.05 * Math.sin(t * f[6] + q[6])) + * (1 + sizeSwing * (own - 0.4)) * chorusSize; + const sx = 1 + 0.16 * Math.sin(t * f[7] + q[7]) + 0.06 * Math.sin(t * f[8] + q[8]); + const sy = SBG_TALL * (1 + 0.18 * Math.cos(t * f[9] + q[9]) + 0.07 * Math.sin(t * f[10] + q[10])); + const tilt = 0.3 * Math.sin(t * f[11] + q[11]) + 0.16 * Math.sin(t * f[12] + q[12]); + const cos = Math.cos(tilt); + const sin = Math.sin(tilt); + const extent = r * Math.sqrt(sx * sx * cos * cos + sy * sy * sin * sin); + if (x + extent < -SBG_PAD || x - extent > W + SBG_PAD) continue; + const y = lift + S.radius * (-0.1 + 0.05 * Math.cos(t * f[3] + q[3]) + 0.03 * Math.sin(t * f[4] + q[4])); + const opacity = Math.min(1, alphaNow * SBG_ROLE[blob.hue] * blob.amp * (1 + glowSwing * (own - 0.5)) * chorusGlow); + draw(x, y, r, sx, sy, tilt, palette[blob.hue], opacity); + } + + /* The reasoning stream: lights flowing the other way along the edge, + each taking the colour of the light beneath it (never a new hue, + so crossings brighten instead of muddying). */ + if (E > 0.01) { + const flowS = t * M.flow * M.streamFlow + S.streamSpacing * 0.4 * Math.sin(t * 0.00011 + 0.7); + const reach = S.spacing * 0.9; + for (const light of S.stream) { + const f = light.f; + const q = light.p; + let x = (light.x0 + flowS + S.streamMargin) % S.streamBand; + if (x < 0) x += S.streamBand; + x -= S.streamMargin; + x += S.streamSpacing * (0.2 * Math.sin(t * f[0] + q[0]) + 0.1 * Math.sin(t * f[1] + q[1])); + if (!still) light.bp += (TAU * dtMs / light.bMs) * tempo; + const lb = wave(light.bp); + const r = S.spacing * 0.8 * light.sig * (1 + 0.2 * lb); + const sx = 1.1 + 0.15 * Math.sin(t * f[2] + q[2]); + const sy = 1.4 + 0.2 * Math.cos(t * f[3] + q[3]); + if (x + r * sx < -SBG_PAD || x - r * sx > W + SBG_PAD) continue; + let cr = 0, cg = 0, cb = 0, cw = 0; + for (let k = 0; k < placed; k += 1) { + const u = (x - S.ax[k]) / reach; + if (u > 3 || u < -3) continue; + const w = Math.exp(-u * u); + const rgb = palette[S.ah[k]]; + cr += w * rgb[0]; + cg += w * rgb[1]; + cb += w * rgb[2]; + cw += w; + } + if (cw < 1e-4) continue; + const y = lift + r * (-0.2 + 0.1 * Math.cos(t * f[2] + q[3])); + const opacity = Math.min(1, alphaNow * M.streamGlow * E * (0.55 + 0.45 * lb)); + draw(x, y, r, sx, sy, 0, [Math.round(cr / cw), Math.round(cg / cw), Math.round(cb / cw)], opacity); + } + } + + /* Blur (BLEND-2); while reasoning, fold the extra brightness back to + the resting level below the top band. */ + const fctx = S.field.ctx; + fctx.setTransform(1, 0, 0, 1, 0, 0); + fctx.globalCompositeOperation = "source-over"; + fctx.clearRect(0, 0, S.lw, S.lh); + fctx.filter = `blur(${SBG_BLUR[theme] * SBG_SCALE}px)`; + fctx.drawImage(S.blob.canvas, 0, 0); + fctx.filter = "none"; + if (boost > 1.001) { + fctx.setTransform(SBG_SCALE, 0, 0, SBG_SCALE, SBG_PAD * SBG_SCALE, SBG_PAD * SBG_SCALE); + fctx.globalCompositeOperation = "destination-in"; + const band = fctx.createLinearGradient(0, 0, 0, SBG_ENVELOPE.band * 5); + for (let i = 0; i <= 10; i += 1) { + const y = (i / 10) * SBG_ENVELOPE.band * 5; + band.addColorStop(i / 10, `rgba(0,0,0,${(1 + (boost - 1) * Math.exp(-y / SBG_ENVELOPE.band)) / boost})`); + } + fctx.fillStyle = band; + fctx.fillRect(-SBG_PAD, -SBG_PAD, W + SBG_PAD * 2, H + SBG_PAD); + fctx.globalCompositeOperation = "source-over"; + } + + /* Compose: base -> field (BLEND-1) -> grain. Only the rows the page's + fade reaches change; below them the canvas is bare base, left as + drawn (a theme change repaints it once). */ + const y0 = Math.max(0, baseLift); + const litH = Math.min(H, Math.ceil(y0 + SBG_ENVELOPE.wash * tune.wash * 4.5 + 8)); + const paintKey = `${this.appearance}|${this.baseKey}`; + const drawH = S.drawnTheme === paintKey ? Math.max(litH, S.drawnH) : H; + S.drawnTheme = paintKey; + const inv = 1 / SBG_SCALE; + const ctx = this.ctx; + ctx.setTransform(1, 0, 0, 1, 0, 0); + ctx.globalAlpha = 1; + ctx.save(); + ctx.beginPath(); + ctx.rect(0, 0, W, drawH); + ctx.clip(); + ctx.globalCompositeOperation = "source-over"; + ctx.fillStyle = this.baseFill; + ctx.fillRect(0, 0, W, drawH); + ctx.imageSmoothingEnabled = true; + ctx.imageSmoothingQuality = "low"; + ctx.globalCompositeOperation = this.isDark ? "screen" : "source-over"; + ctx.drawImage(S.field.canvas, 0, 0, S.lw, S.lh, -SBG_PAD, -SBG_PAD, S.lw * inv, S.lh * inv); + ctx.globalCompositeOperation = "source-over"; + ctx.imageSmoothingEnabled = false; + ctx.drawImage(this.sbgGrain(S), 0, 0, W, drawH, 0, 0, W, drawH); + ctx.restore(); + S.drawnH = litH; + + S.cost = S.cost ? S.cost * 0.92 + (performance.now() - started) * 0.08 : performance.now() - started; + } + + markReady() { + if (this.ready) return; + this.ready = true; + this.element.dataset.radianceReady = "true"; + this.element.dispatchEvent(new CustomEvent("radiance-local-ready", { bubbles: true })); + } + + getFrameKey() { + return [ + this.textureKey, + this.lastConfigKey, + this.baseKey, + overlayGeneration, + this.width, + this.height, + this.dpr, + prefersReducedMotion ? "reduced" : "full" + ].join(":"); + } + + render(timestamp) { + if (!this.isRenderable()) return; + this.applyPatternShorthand(); + this.ensureSize(); + if (this.isSpotter) { + this.ensureTextures(); + this.resolveBase(); + this.renderSbg(timestamp || performance.now()); + this.markReady(); + return; + } + this.ensureBlobs(); + this.ensureTextures(); + this.resolveBase(); + + const frameKey = this.getFrameKey(); + if (this.isStill && this.staticFrameKey === frameKey) return; + + const time = this.isStill ? 0 : getTimelineTime(); + const t = time * this.speed; + // F2: breathing runs on the shared timeline at sqrt(speed). + this.breathT = time * Math.sqrt(Math.max(this.speed, 0.05)); + const ctx = this.ctx; + ctx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + ctx.globalAlpha = 1; + ctx.globalCompositeOperation = "source-over"; + ctx.fillStyle = this.baseFill; + ctx.fillRect(0, 0, this.width, this.height); + const theme = this.isDark ? "dark" : "light"; + const film = FILM[theme]; + const pageFilm = this.filmMode === "page"; + + if (this.isDark) { + this.blobCtx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0); + this.blobCtx.clearRect(0, 0, this.width, this.height); + for (const blob of this.blobs) { + blob.update(t, this.width, this.height, this.mouse, this.breathT); + blob.draw(this.blobCtx); + } + + ctx.save(); + ctx.filter = `blur(${this.layout === "neutral" ? 40 : 64}px)`; + ctx.globalCompositeOperation = "screen"; + ctx.drawImage(this.blobCanvas, 0, 0, this.width, this.height); + ctx.restore(); + + this.drawSupport(t); + + if (this.darkGlow === "subtle") { + this.drawDarkFalloff(); + } + + if (pageFilm) { + this.drawFieldOpacity(); + this.drawPlainTexture(this.darkDither, film.dither); + this.drawPlainTexture(this.darkGrain, film.grain); + } else { + this.renderDarkColourField(t); + this.buildColourMask(GRAIN_MASK_SATURATION); + this.drawMaskedTexture(this.darkDither, film.dither); + this.drawMaskedTexture(this.darkGrain, film.grain); + this.drawMaskedOverlay(theme); + this.applyToneLift(theme); + } + } else { + this.renderColourField(t); + ctx.drawImage(this.fieldCanvas, 0, 0, this.width, this.height); + if (pageFilm) { + this.drawFieldOpacity(); + this.drawPlainTexture(this.lightGrain, film.grain); + } else { + this.buildColourMask(GRAIN_MASK_SATURATION); + this.drawMaskedTexture(this.lightGrain, film.grain); + this.drawMaskedOverlay(theme); + this.applyToneLift(theme); + } + } + + this.markReady(); + if (this.isStill) this.staticFrameKey = frameKey; + } + } + + // F1: the fine noise layer, rasterised once per theme and pixel density. + // The SVG loads asynchronously; surfaces repaint once it is ready. + const overlaySources = {}; + const overlayPatterns = new Map(); + let overlayGeneration = 0; + + function getOverlaySource(theme) { + if (overlaySources[theme]) return overlaySources[theme]; + const image = new Image(); + const entry = { image, ready: false }; + image.onload = () => { + entry.ready = true; + overlayGeneration += 1; + surfaces.forEach((surface) => { + surface.staticFrameKey = ""; + }); + }; + image.src = `data:image/svg+xml,${encodeURIComponent(FILM_OVERLAY_SVG[theme])}`; + overlaySources[theme] = entry; + return entry; + } + + function getOverlayPattern(theme, dpr, ctx) { + const key = `${theme}@${dpr}`; + if (overlayPatterns.has(key)) return overlayPatterns.get(key); + const source = getOverlaySource(theme); + if (!source.ready) return null; + const tile = document.createElement("canvas"); + const size = Math.max(1, Math.round(FILM_OVERLAY_TILE * dpr)); + tile.width = size; + tile.height = size; + tile.getContext("2d").drawImage(source.image, 0, 0, size, size); + const pattern = ctx.createPattern(tile, "repeat"); + if (pattern && pattern.setTransform && typeof DOMMatrix === "function") { + pattern.setTransform(new DOMMatrix().scaleSelf(1 / dpr, 1 / dpr)); + } + overlayPatterns.set(key, pattern); + return pattern; + } + + function scan(root = document) { + root.querySelectorAll?.(".radiance-local").forEach((element) => { + if (surfaceByElement.has(element)) return; + const surface = new RadianceSurface(element); + surfaceByElement.set(element, surface); + surfaces.add(surface); + }); + + surfaces.forEach((surface) => { + if (surface.element.isConnected) return; + surface.destroy(); + surfaces.delete(surface); + }); + + startLoop(); + } + + function frame(timestamp) { + if (!isDocumentVisible) { + raf = 0; + return; + } + + surfaces.forEach((surface) => surface.render(timestamp)); + raf = window.requestAnimationFrame(frame); + } + + function startLoop() { + if (raf || !isDocumentVisible) return; + raf = window.requestAnimationFrame(frame); + } + + function stopLoop() { + if (!raf) return; + window.cancelAnimationFrame(raf); + raf = 0; + } + + function handleVisibilityChange() { + isDocumentVisible = document.visibilityState !== "hidden"; + if (isDocumentVisible) { + startLoop(); + } else { + stopLoop(); + } + } + + function observeDomChanges() { + if (mutationObserver || !document.body || !("MutationObserver" in window)) return; + mutationObserver = new MutationObserver((mutations) => { + const needsScan = mutations.some((mutation) => ( + [...mutation.addedNodes].some((node) => node.nodeType === Node.ELEMENT_NODE) + || [...mutation.removedNodes].some((node) => node.nodeType === Node.ELEMENT_NODE) + )); + if (needsScan) scan(); + }); + mutationObserver.observe(document.body, { childList: true, subtree: true }); + } + + function renderGrainPreview(canvas, mode = "light") { + if (!(canvas instanceof HTMLCanvasElement)) return; + const safeMode = mode === "dark" ? "dark" : "light"; + const rect = canvas.getBoundingClientRect(); + const maxWidth = Number(canvas.dataset.grainPreviewMaxWidth || "0"); + const maxHeight = Number(canvas.dataset.grainPreviewMaxHeight || "0"); + const measuredWidth = Math.max(1, Math.round(rect.width || canvas.clientWidth || canvas.width || 280)); + const measuredHeight = Math.max(1, Math.round(rect.height || canvas.clientHeight || canvas.height || 120)); + const width = maxWidth > 0 ? Math.min(measuredWidth, maxWidth) : measuredWidth; + const height = maxHeight > 0 ? Math.min(measuredHeight, maxHeight) : measuredHeight; + const dpr = Math.min(window.devicePixelRatio || 1, MAX_DPR); + const ctx = canvas.getContext("2d"); + if (!ctx) return; + + canvas.width = Math.max(1, Math.floor(width * dpr)); + canvas.height = Math.max(1, Math.floor(height * dpr)); + canvas.style.width = `${width}px`; + canvas.style.height = `${height}px`; + + ctx.setTransform(dpr, 0, 0, dpr, 0, 0); + ctx.fillStyle = safeMode === "dark" ? DARK_SURFACE : "#ffffff"; + ctx.fillRect(0, 0, width, height); + + if (safeMode === "dark") { + const dither = RadianceSurface.prototype.createDarkDither.call({ width, height, dpr: 1 }); + ctx.save(); + ctx.globalAlpha = 0.42; + ctx.imageSmoothingEnabled = false; + ctx.drawImage(dither, 0, 0, width, height); + ctx.restore(); + } + + const grain = RadianceSurface.prototype.createGrain.call({ width, height }, safeMode); + ctx.save(); + ctx.imageSmoothingEnabled = false; + ctx.drawImage(grain, 0, 0, width, height); + ctx.restore(); + } + + function handleReducedMotionChange(event) { + prefersReducedMotion = event.matches; + surfaces.forEach((surface) => { + surface.staticFrameKey = ""; + }); + startLoop(); + } + + /* Read-only snapshot of every surface (tests and tooling). */ + function inspect() { + return [...surfaces].map((surface) => ({ + pattern: surface.productName || surface.element.dataset.radiancePattern || surface.layout, + product: surface.productName || null, + engine: surface.product ? surface.product.engine : "template", + appearance: surface.appearance, + base: surface.baseFill, + width: surface.width, + height: surface.height, + energy: surface.sbg ? surface.sbg.energy : null, + settled: surface.sbg ? surface.sbg.settled : null, + clock: surface.sbg ? surface.sbg.clock : null, + costMs: surface.sbg ? surface.sbg.cost : null + })); + } + + window.RadianceLanguageRenderer = { + version: RADIANCE_VERSION, + refresh() { + scan(); + startLoop(); + }, + renderGrainPreview, + grainSize: RADIANCE_FILM_GRAIN_SIZE, + patterns: RADIANCE_PATTERNS, + products: PRODUCT_PATTERNS, + resolvePattern: resolveRadiancePattern, + inspect, + /* For the Radiance admin's Spotter lab (spotter-lab/) and nothing else: + preview a change to the Spotter engine on one surface before it is + made in this file. Product patterns stay fixed (PRODUCT-2), nothing + persists, and the linter fails any use outside spotter-lab/ (PRODUCT-5). */ + admin: Object.freeze({ + spotterDefaults() { + return JSON.parse(JSON.stringify({ ...SBG_TUNING, levels: SBG_STATES, grain: { light: FILM.light.grain, dark: FILM.dark.grain } })); + }, + tuneSpotter(element, values) { + if (element) ADMIN_SPOTTER.set(element, JSON.parse(JSON.stringify(values || {}))); + }, + resetSpotter(element) { + if (element) ADMIN_SPOTTER.delete(element); + } + }), + get prefersReducedMotion() { + return prefersReducedMotion; + } + }; + + scan(); + observeDomChanges(); + document.addEventListener("visibilitychange", handleVisibilityChange); + reducedMotionQuery?.addEventListener?.("change", handleReducedMotionChange); + window.addEventListener("beforeunload", () => { + stopLoop(); + mutationObserver?.disconnect(); + surfaces.forEach((surface) => surface.destroy()); + surfaces.clear(); + textureCache.clear(); + }); +})(); From f6797962eb970646b29e078bc89887045cf18f22 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 14 Oct 2026 13:56:15 +0530 Subject: [PATCH 071/169] removed highlight markers --- modules/ROOT/pages/deploy-with-tml-apis.adoc | 26 +- .../ROOT/pages/intro-thoughtspot-objects.adoc | 14 +- modules/ROOT/pages/object-id.adoc | 228 +++++++++--------- 3 files changed, 134 insertions(+), 134 deletions(-) diff --git a/modules/ROOT/pages/deploy-with-tml-apis.adoc b/modules/ROOT/pages/deploy-with-tml-apis.adoc index dfb327bf2..4e0d2c2a5 100644 --- a/modules/ROOT/pages/deploy-with-tml-apis.adoc +++ b/modules/ROOT/pages/deploy-with-tml-apis.adoc @@ -117,11 +117,11 @@ Once you have decided on the appropriate `obj_id` for all the objects in your de You only have to do this process for existing objects *one time*, and from that point forward, you can update objects in any Org using TML with obj_ids rather than GUIDs. [#adopting-obj-id-in-deployment-pipeline] -==== ##Adopting obj_id in a deployment pipeline## -##You can move an existing GUID-based deployment pipeline to `obj_id` one step at a time. Existing GUID-based workflows continue to work while you migrate, and you can start with the objects you deploy most often.## +==== Adopting obj_id in a deployment pipeline +You can move an existing GUID-based deployment pipeline to `obj_id` one step at a time. Existing GUID-based workflows continue to work while you migrate, and you can start with the objects you deploy most often. -. ##*Confirm that Object ID is enabled* on every ThoughtSpot instance in your pipeline. For more information, see## xref:object-id.adoc#_enable_object_id[Enable Object ID]. -. ##*Define a naming convention.* Choose stable, readable identifiers that do not depend on the object's display name or GUID, for example, `--`:## +. *Confirm that Object ID is enabled* on every ThoughtSpot instance in your pipeline. For more information, see xref:object-id.adoc#_enable_object_id[Enable Object ID]. +. *Define a naming convention.* Choose stable, readable identifiers that do not depend on the object's display name or GUID, for example, `--`: + ---- sales-liveboard-prod @@ -129,19 +129,19 @@ sales-model-prod hubspot-contacts-table ---- + -##The values must follow the## xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format]. -. ##*Assign `obj_id` values in the dev Org.* Use the `metadata/update-obj-id` endpoint or edit the `obj_id` in the object's TML. Replace automatically generated values such as `RetailSalesRAD-KPIs-c1e4043a`: they include part of the GUID, so copies of the same object in different Orgs receive different generated values.## -. ##*Align existing copies in the other Orgs.* Give each existing copy of an object the same `obj_id` as the original in the dev Org. See <<_implementing_obj_id_in_existing_environments,Implementing obj_id in existing environments>>.## -. ##*Export the release TML* with `include_obj_id` and `include_obj_id_ref` set to `true`. See <<_obj_id_or_guid,obj_id or guid>>.## -. ##*Deploy for the first time.* Import the TML into the target Org without a `guid` property. If the object does not exist in the target Org, ThoughtSpot creates it and assigns a new GUID in that Org.## -. ##*Deploy subsequent releases.* Import the same TML. ThoughtSpot finds the existing object by its `obj_id` and updates it.## -. ##*Check the import response* for each file to confirm that it created or updated the expected object.## +The values must follow the xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format]. +. *Assign `obj_id` values in the dev Org.* Use the `metadata/update-obj-id` endpoint or edit the `obj_id` in the object's TML. Replace automatically generated values such as `RetailSalesRAD-KPIs-c1e4043a`: they include part of the GUID, so copies of the same object in different Orgs receive different generated values. +. *Align existing copies in the other Orgs.* Give each existing copy of an object the same `obj_id` as the original in the dev Org. See <<_implementing_obj_id_in_existing_environments,Implementing obj_id in existing environments>>. +. *Export the release TML* with `include_obj_id` and `include_obj_id_ref` set to `true`. See <<_obj_id_or_guid,obj_id or guid>>. +. *Deploy for the first time.* Import the TML into the target Org without a `guid` property. If the object does not exist in the target Org, ThoughtSpot creates it and assigns a new GUID in that Org. +. *Deploy subsequent releases.* Import the same TML. ThoughtSpot finds the existing object by its `obj_id` and updates it. +. *Check the import response* for each file to confirm that it created or updated the expected object. // TODO: confirm with engineering whether an obj_id that matches no object falls back to the GUID with a WARNING status (object-id.adoc) or creates a new object ("Rules for create vs. update operations" on this page). If the WARNING fallback is correct, add: "A WARNING status means the obj_id did not match an object and ThoughtSpot matched by GUID instead." -. ##*Retire your GUID mapping.* Once every deployed object has a consistent `obj_id` in all Orgs, you no longer need to maintain a GUID mapping file.## +. *Retire your GUID mapping.* Once every deployed object has a consistent `obj_id` in all Orgs, you no longer need to maintain a GUID mapping file. [NOTE] ==== -##Visualizations and Liveboard tabs do not have an `obj_id`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, still use a GUID that is different in each Org. For more information, see## xref:object-id.adoc#_objects_that_do_not_support_obj_id[Objects that do not support obj_id]. +Visualizations and Liveboard tabs do not have an `obj_id`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, still use a GUID that is different in each Org. For more information, see xref:object-id.adoc#_objects_that_do_not_support_obj_id[Objects that do not support obj_id]. ==== [#linkBuildRelease] diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index ed55cffc5..dc97770ae 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -19,22 +19,22 @@ image::./images/object_model_hierarchy.png[Object Model Hierarchy] == Object identifiers [#object-identifiers] -Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. ##Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID.## +Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID. [#_supported_object_types] Supported objects also have an Object ID (`obj_id`) property that is *user-settable* and *unique per Org*. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID. The `obj_id` appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. [#_obj_id_format_and_constraints] -Because you choose the `obj_id`, related copies of an object in different Orgs and instances can share the same value. This allows ThoughtSpot to match objects during TML import without manual GUID mapping, ##and allows you to reference objects in REST API requests and ThoughtSpot URLs with the same identifier in every environment.## +Because you choose the `obj_id`, related copies of an object in different Orgs and instances can share the same value. This allows ThoughtSpot to match objects during TML import without manual GUID mapping, and allows you to reference objects in REST API requests and ThoughtSpot URLs with the same identifier in every environment. [#_obj_id_resolution] -##For more information, see the following pages:## +For more information, see the following pages: [#_setting_and_updating_obj_id] * xref:object-id.adoc[Object ID (obj_id)] + -##Supported object types, `obj_id` format and constraints, how identifiers are resolved, and how to set or update an `obj_id`.## +Supported object types, `obj_id` format and constraints, how identifiers are resolved, and how to set or update an `obj_id`. * xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs] + -##Use an `obj_id` instead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs.## +Use an `obj_id` instead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs. == Data modeling @@ -118,7 +118,7 @@ The `POST /api/rest/2.0/metadata/search` REST API v2.0 endpoint returns the foll * `metadata_id` + GUID of the object. Unique within a given ThoughtSpot instance. * `metadata_obj_id` + -User-defined string identifier for the object (`obj_id`). Unique within a given Org. ##For more information, see xref:object-id.adoc[Object ID (obj_id)].## +User-defined string identifier for the object (`obj_id`). Unique within a given Org. For more information, see xref:object-id.adoc[Object ID (obj_id)]. * `metadata_name` + Name of the object. * `metadata_type` + @@ -157,7 +157,7 @@ Object type names in ThoughtSpot REST API v2.0 differ from the names shown in th * *Tags*: `TAG` * *Users*: `USER` * *Groups*: `USER_GROUP` -* ##*Collections*: `COLLECTION`## +* *Collections*: `COLLECTION` For the `LOGICAL_TABLE` type, you can also specify the following values in the `subtypes` attribute to filter the results: diff --git a/modules/ROOT/pages/object-id.adoc b/modules/ROOT/pages/object-id.adoc index c2af6c62c..60f23204a 100644 --- a/modules/ROOT/pages/object-id.adoc +++ b/modules/ROOT/pages/object-id.adoc @@ -6,24 +6,24 @@ :page-pageid: object-id :page-description: Learn how to set and use a stable, user-defined Object ID (obj_id) to identify ThoughtSpot objects consistently across instances, Orgs, and environments. Use Object ID (obj_id) to reference ThoughtSpot objects by a stable, user-defined identifier across Orgs and instances -##Every object in ThoughtSpot has a system-generated GUID. GUIDs are minted per instance, so the same Liveboard promoted from a development environment to a production environment has a different GUID in each one.## +Every object in ThoughtSpot has a system-generated GUID. GUIDs are minted per instance, so the same Liveboard promoted from a development environment to a production environment has a different GUID in each one. -An Object ID (`obj_id`) is a customer-defined, human-readable identifier that you assign to an object in addition to its GUID. ##An `obj_id` survives renames, TML export and import, and moves between Orgs and instances.## Because you choose the value, related copies of an object in different Orgs can share the same `obj_id`, ##and your deployment scripts, Git-based CI/CD pipelines, and host application can reference the object without maintaining a GUID mapping for each environment.## +An Object ID (`obj_id`) is a customer-defined, human-readable identifier that you assign to an object in addition to its GUID. An `obj_id` survives renames, TML export and import, and moves between Orgs and instances. Because you choose the value, related copies of an object in different Orgs can share the same `obj_id`, and your deployment scripts, Git-based CI/CD pipelines, and host application can reference the object without maintaining a GUID mapping for each environment. -##Object ID is generally available from ThoughtSpot Cloud 26.9.0.cl.## +Object ID is generally available from ThoughtSpot Cloud 26.9.0.cl. == Overview * `obj_id` is *user-settable* and *unique per Org*. Each Org can have only one object with a particular `obj_id`. -* The combination of Org ID and `obj_id` is the uniqueness key, ##so the same `obj_id` in two Orgs refers to two different objects. This is by design.## +* The combination of Org ID and `obj_id` is the uniqueness key, so the same `obj_id` in two Orgs refers to two different objects. This is by design. * The `obj_id` of an object is returned as `metadata_obj_id` in the `POST /api/rest/2.0/metadata/search` API response, and as `obj_id` in TML. -* ##Object ID is the key that TML-based deployment, xref:publishing-overview.adoc[publishing], and xref:git-provider-integration.adoc[Git provider integration] build on.## +* Object ID is the key that TML-based deployment, xref:publishing-overview.adoc[publishing], and xref:git-provider-integration.adoc[Git provider integration] build on. == Enable Object ID -Object ID must be enabled on your ThoughtSpot instance ##before `obj_id` participates in TML export, TML import, and metadata search. Until it is enabled, ThoughtSpot continues to resolve objects by GUID and name.## +Object ID must be enabled on your ThoughtSpot instance before `obj_id` participates in TML export, TML import, and metadata search. Until it is enabled, ThoughtSpot continues to resolve objects by GUID and name. -##To use `obj_id` in ThoughtSpot URLs, an additional setting is required. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs].## +To use `obj_id` in ThoughtSpot URLs, an additional setting is required. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. == Supported object types @@ -31,88 +31,88 @@ The following object types support `obj_id`: [cols="2,4", options="header"] |=== -|Object type |##In TML## - -|Liveboard |##`liveboard`## + -##Exported in TML and resolved first on import.## -|Answer |##`answer`## -|Model |##`model`## + -##Includes Worksheets.## -|Table |##`table`## -|##SQL View## |##`sql_view`## -|##Column## |##None## + -##Supported on columns within Tables and Models.## -|##Connection## |##`connection`## -|Collection |##None## -|##Custom action## |##None## + -##Supported for custom actions managed through the API or the server.## -|Personalized View |##None## + -##For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import].## -|Variable |##None## + -##Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl.## -|##Memory## |##None## + -##Carries an Object ID through the Model it is tagged to.## -|##Group## |##None## -|Role |##None## +|Object type |In TML + +|Liveboard |`liveboard` + +Exported in TML and resolved first on import. +|Answer |`answer` +|Model |`model` + +Includes Worksheets. +|Table |`table` +|SQL View |`sql_view` +|Column |None + +Supported on columns within Tables and Models. +|Connection |`connection` +|Collection |None +|Custom action |None + +Supported for custom actions managed through the API or the server. +|Personalized View |None + +For information about importing Personalized Views with `obj_id`, see xref:tml-import.adoc[TML import]. +|Variable |None + +Supported from 26.10.0.cl. Template variables can also reference Object IDs from 26.10.0.cl. +|Memory |None + +Carries an Object ID through the Model it is tagged to. +|Group |None +|Role |None |=== [IMPORTANT] ==== -##The `obj_id` field appears in the TML of every object kind, but TML import honors it only for the supported object types. The presence of `obj_id` in a TML file does not mean that the object type supports Object ID.## +The `obj_id` field appears in the TML of every object kind, but TML import honors it only for the supported object types. The presence of `obj_id` in a TML file does not mean that the object type supports Object ID. ==== -=== ##Objects that do not support obj_id## +=== Objects that do not support obj_id -##The following objects do not have an `obj_id`:## +The following objects do not have an `obj_id`: [cols="2,5", options="header"] |=== -|##Object## |##Behavior## +|Object |Behavior -|##Visualization on a Liveboard## -|##In TML, a visualization is identified only by `viz_guid`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, depend on a GUID that differs between Orgs.## +|Visualization on a Liveboard +|In TML, a visualization is identified only by `viz_guid`. Objects that reference a visualization, such as Monitor alerts, Liveboard schedules, and related links, depend on a GUID that differs between Orgs. -|##Liveboard tab## -|##A tab is identified only by its `id`, which is a GUID.## +|Liveboard tab +|A tab is identified only by its `id`, which is a GUID. -|##Monitor alert (KPI alert)## -|##The alert has no `obj_id` of its own. Its TML includes `pinboard_obj_id` and `answer_obj_id`, which resolve on import, but the visualization reference is a GUID that must already exist in the target environment.## +|Monitor alert (KPI alert) +|The alert has no `obj_id` of its own. Its TML includes `pinboard_obj_id` and `answer_obj_id`, which resolve on import, but the visualization reference is a GUID that must already exist in the target environment. -|##Schedule## -|##Liveboard schedules reference visualizations through `included_viz_id`, which is a GUID.## +|Schedule +|Liveboard schedules reference visualizations through `included_viz_id`, which is a GUID. -|##Webhook## -|##The `obj_id` field is present in webhook TML but is ignored on import.## +|Webhook +|The `obj_id` field is present in webhook TML but is ignored on import. -|##Parameter## -|##Parameters have no `obj_id` and do not migrate by name.## +|Parameter +|Parameters have no `obj_id` and do not migrate by name. -|##Semantic integration## -|##Semantic integrations have no `obj_id` and do not migrate by name.## +|Semantic integration +|Semantic integrations have no `obj_id` and do not migrate by name. -|##User## -|##Users are identified by name in TML and migrate without an `obj_id`.## +|User +|Users are identified by name in TML and migrate without an `obj_id`. -|##Tag## -|##Tags are identified by name in TML and migrate without an `obj_id`.## +|Tag +|Tags are identified by name in TML and migrate without an `obj_id`. -|##Org## -|##Orgs are part of the uniqueness key (Org ID + `obj_id`), so they do not have an `obj_id` themselves.## +|Org +|Orgs are part of the uniqueness key (Org ID + `obj_id`), so they do not have an `obj_id` themselves. |=== -=== ##TML kinds that ignore obj_id on import## +=== TML kinds that ignore obj_id on import -##The `obj_id` field is present in the following TML kinds but is ignored during import:## +The `obj_id` field is present in the following TML kinds but is ignored during import: -* ##`Join`## -* ##`user_object`## -* ##`webhook`## -* ##`column_security_rules`## -* ##`nl_instruction`## -* ##`column_alias`## -* ##`nls_feedback`## -* ##`cohort`## -* ##`monitor_alert`## +* `Join` +* `user_object` +* `webhook` +* `column_security_rules` +* `nl_instruction` +* `column_alias` +* `nls_feedback` +* `cohort` +* `monitor_alert` == obj_id format and constraints @@ -122,31 +122,31 @@ An `obj_id` value must meet the following requirements: |=== |Constraint |Requirement -|Length |##1 to## 64 characters -|Allowed characters |##Letters, digits, and the special characters hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`). Spaces are not allowed.## +|Length |1 to 64 characters +|Allowed characters |Letters, digits, and the special characters hyphen (`-`), underscore (`_`), period (`.`), and tilde (`~`). Spaces are not allowed. |Uniqueness |Unique within an Org |=== -*Valid examples:* ##`sales-weekly-performance`, `finance_ledger.prod`, `retail~kpis-v2`## +*Valid examples:* `sales-weekly-performance`, `finance_ledger.prod`, `retail~kpis-v2` [TIP] ==== -##Do not use a value that has the same format as a GUID. When ThoughtSpot resolves an identifier in a URL, a GUID-shaped value is always tried as a GUID first, so a GUID-shaped `obj_id` might not resolve as expected.## +Do not use a value that has the same format as a GUID. When ThoughtSpot resolves an identifier in a URL, a GUID-shaped value is always tried as a GUID first, so a GUID-shaped `obj_id` might not resolve as expected. ==== -== ##How objects get an obj_id## +== How objects get an obj_id -* ##New objects are assigned an `obj_id` when they are created.## -* ##Objects that existed before Object ID was enabled are not assigned an `obj_id` retroactively.## They receive an automatically generated `obj_id` the first time the object is updated ##or imported through TML##. -* ##You can assign or change the `obj_id` of any supported object at any time. For more information, see <<_setting_and_updating_obj_id,Setting and updating obj_id>>.## +* New objects are assigned an `obj_id` when they are created. +* Objects that existed before Object ID was enabled are not assigned an `obj_id` retroactively. They receive an automatically generated `obj_id` the first time the object is updated or imported through TML. +* You can assign or change the `obj_id` of any supported object at any time. For more information, see <<_setting_and_updating_obj_id,Setting and updating obj_id>>. An automatically generated `obj_id` appends the first segment of the object's GUID to the object name. For example, `RetailSalesRAD-KPIs-c1e4043a`. If the `metadata_obj_id` property in the `/metadata/search` API response is `null`, the object has not been updated since Object ID was enabled. == obj_id resolution -##How ThoughtSpot resolves an identifier depends on where you use it.## +How ThoughtSpot resolves an identifier depends on where you use it. -=== ##REST API endpoints## +=== REST API endpoints When an identifier is passed to a REST API v2.0 endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: @@ -156,33 +156,33 @@ When an identifier is passed to a REST API v2.0 endpoint that accepts an `object This allows `obj_id` to be used anywhere a GUID or name is accepted in those fields. Existing integrations that use GUIDs or names continue to work. -##The `POST /api/rest/2.0/metadata/search` endpoint and the metadata update endpoints also accept an `obj_identifier` field. When you use `obj_identifier`, ThoughtSpot resolves the value strictly as an `obj_id`, without falling back to the object name.## +The `POST /api/rest/2.0/metadata/search` endpoint and the metadata update endpoints also accept an `obj_identifier` field. When you use `obj_identifier`, ThoughtSpot resolves the value strictly as an `obj_id`, without falling back to the object name. -##In the `/metadata/search` API, `obj_identifier` is supported for the following object types:## +In the `/metadata/search` API, `obj_identifier` is supported for the following object types: -* ##`LIVEBOARD`## -* ##`ANSWER`## -* ##`LOGICAL_TABLE`## -* ##`LOGICAL_COLUMN`## -* ##`CONNECTION`## -* ##`USER_GROUP`## -* ##`COLLECTION`## +* `LIVEBOARD` +* `ANSWER` +* `LOGICAL_TABLE` +* `LOGICAL_COLUMN` +* `CONNECTION` +* `USER_GROUP` +* `COLLECTION` -##Other object types, such as Roles and Personalized Views, can have an `obj_id`, but you cannot search for them by `obj_identifier`. To find these objects, search by GUID or name and read the `metadata_obj_id` value in the response.## +Other object types, such as Roles and Personalized Views, can have an `obj_id`, but you cannot search for them by `obj_identifier`. To find these objects, search by GUID or name and read the `metadata_obj_id` value in the response. -=== ##TML import## +=== TML import -##During TML import, ThoughtSpot matches the TML to an existing object in the following order:## +During TML import, ThoughtSpot matches the TML to an existing object in the following order: -. ##`obj_id`## -. ##GUID## -. ##Name## +. `obj_id` +. GUID +. Name -##If the `obj_id` in the TML does not match any object in the target Org, ThoughtSpot falls back to the GUID in the TML and updates that object. The import returns a `WARNING` status in this case. It does not create a duplicate object or fail the import.## +If the `obj_id` in the TML does not match any object in the target Org, ThoughtSpot falls back to the GUID in the TML and updates that object. The import returns a `WARNING` status in this case. It does not create a duplicate object or fail the import. -=== ##ThoughtSpot URLs## +=== ThoughtSpot URLs -##In ThoughtSpot URLs, a GUID is always tried first, and object names are never resolved. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs].## +In ThoughtSpot URLs, a GUID is always tried first, and object names are never resolved. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. [NOTE] ==== @@ -191,25 +191,25 @@ This allows `obj_id` to be used anywhere a GUID or name is accepted in those fie == Setting and updating obj_id -You can set or change the `obj_id` of an object by using the REST API ##or by editing the object's TML##. +You can set or change the `obj_id` of an object by using the REST API or by editing the object's TML. === Using the update-obj-id API -The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. ##The endpoint uses the metadata header update mechanism to apply the change.## +The `POST /api/rest/2.0/metadata/update-obj-id` endpoint updates the `obj_id` of one or more objects. The endpoint uses the metadata header update mechanism to apply the change. -##Required privileges##:: -##`DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*). If Role-Based Access Control (RBAC) is enabled, the `ORG_ADMINISTRATION` (*Can manage Orgs*) privilege is also required.## +Required privileges:: +`DATAMANAGEMENT` (*Can manage data*) or `ADMINISTRATION` (*Can administer ThoughtSpot*). If Role-Based Access Control (RBAC) is enabled, the `ORG_ADMINISTRATION` (*Can manage Orgs*) privilege is also required. -##Request parameters##:: -##For each object in the `metadata` array:## +Request parameters:: +For each object in the `metadata` array: + -* ##Identify the object by using either `current_obj_id` alone, or `metadata_identifier`.## -* ##`metadata_identifier` accepts the object's GUID or name. If you use the name, you must also specify the object `type`, for example, `ANSWER` or `LOGICAL_TABLE`.## -* ##`new_obj_id` is always required. The value must follow the## xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format] ##and be unique within the Org.## +* Identify the object by using either `current_obj_id` alone, or `metadata_identifier`. +* `metadata_identifier` accepts the object's GUID or name. If you use the name, you must also specify the object `type`, for example, `ANSWER` or `LOGICAL_TABLE`. +* `new_obj_id` is always required. The value must follow the xref:object-id.adoc#_obj_id_format_and_constraints[obj_id format] and be unique within the Org. [TIP] ==== -##Before updating Object IDs, export the TML of the objects as a backup.## +Before updating Object IDs, export the TML of the objects as a backup. ==== Using the GUID: @@ -240,7 +240,7 @@ Using the current `obj_id`: } ---- -##Using the object name and type:## +Using the object name and type: [source,json] ---- @@ -255,7 +255,7 @@ Using the current `obj_id`: } ---- -The request accepts an array, so you can update multiple objects in a single API call. ##Each object in the array can use a different identification method:## +The request accepts an array, so you can update multiple objects in a single API call. Each object in the array can use a different identification method: [source,json] ---- @@ -274,24 +274,24 @@ The request accepts an array, so you can update multiple objects in a single API } ---- -=== ##Using the metadata headers update API## +=== Using the metadata headers update API -##The `POST /api/rest/2.0/metadata/headers/update` endpoint also sets the `obj_id` in an object's header.## From 26.10.0.cl, this endpoint and the `update-obj-id` endpoint support the `ROLE` and `TEMPLATE_VARIABLE` types. +The `POST /api/rest/2.0/metadata/headers/update` endpoint also sets the `obj_id` in an object's header. From 26.10.0.cl, this endpoint and the `update-obj-id` endpoint support the `ROLE` and `TEMPLATE_VARIABLE` types. === Using TML Set the `obj_id` property in the object's TML and import the TML. For examples, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs]. -== ##Behavior and limitations## +== Behavior and limitations -##Renaming an obj_id##:: -##After you change an object's `obj_id`, the previous value no longer resolves. Integrations, scripts, and URLs that use the old value must be updated to use the new value.## +Renaming an obj_id:: +After you change an object's `obj_id`, the previous value no longer resolves. Integrations, scripts, and URLs that use the old value must be updated to use the new value. -##Org scope##:: -##The same `obj_id` in two Orgs resolves to two different objects. Make sure requests are made in the context of the Org where the `obj_id` is set.## +Org scope:: +The same `obj_id` in two Orgs resolves to two different objects. Make sure requests are made in the context of the Org where the `obj_id` is set. -##Delete operations##:: -##The `POST /api/rest/2.0/metadata/delete` endpoint does not accept `obj_identifier`. Use GUIDs when deleting objects in automation scripts.## +Delete operations:: +The `POST /api/rest/2.0/metadata/delete` endpoint does not accept `obj_identifier`. Use GUIDs when deleting objects in automation scripts. == Related resources From 6c05d26db8ccc6f2ff04136c6f255dec33979b93 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 14 Oct 2026 14:31:05 +0530 Subject: [PATCH 072/169] edits for obj id url --- modules/ROOT/pages/whats-new.adoc | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index ef3a056b7..432d4a5ff 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -63,7 +63,13 @@ For more information, see xref:link-customization-api.adoc[Link Customization AP [discrete] ==== Input Table APIs [.version-badge.new]#New# + -Five new REST API v2.0 endpoints allow you to create and manage input tables — user-editable tables stored in an external CDW and linked to a ThoughtSpot model. +These REST API v2.0 endpoints allow you to create and manage input tables programmatically. An input table is a table that users can edit, stored in an external Cloud Data Warehouse (CDW) and linked to a ThoughtSpot model. + +* `POST /api/rest/2.0/input-tables/create` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` For more information, see xref:input-table-api.adoc[Input Table APIs]. @@ -82,6 +88,12 @@ For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data AP ==== Share Analyst API The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. +[discrete] +==== Object ID in ThoughtSpot URLs [earlyAccess eaBackground]#Early Access# +You can now use an object ID (`obj_id`) instead of a GUID in ThoughtSpot URLs for Liveboards, Answers, Collections, Models, Worksheets, Tables, Views, and Connections. Because you assign the same `obj_id` to an object in every environment, links built by your host application open the correct object when switching environments. You no longer need a GUID mapping for each environment. Existing GUID-based URLs continue to work. + +For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. For guidance on moving a GUID-based deployment pipeline to `obj_id`, see xref:deploy-with-tml-apis.adoc#adopting-obj-id-in-deployment-pipeline[Adopting obj_id in a deployment pipeline]. + [discrete] ==== Default RBAC enablement for new clusters Starting with 26.11.0.cl, Role-Based Access Control (RBAC) is enabled by default on all new ThoughtSpot Cloud clusters. Existing clusters are not affected. For more information about RBAC, see xref:rbac.adoc[Role-based access control]. From d064f0d7baadf9ad3ba9d672c8bab0f3a8ccddf6 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:31:48 +0530 Subject: [PATCH 073/169] docs: restore full customize-spotter-embed.adoc content; link to new SpotterX page --- .../ROOT/pages/customize-spotter-embed.adoc | 199 ++++++++++++++---- 1 file changed, 160 insertions(+), 39 deletions(-) diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc index 375d07132..62854c7c2 100644 --- a/modules/ROOT/pages/customize-spotter-embed.adoc +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -1,42 +1,163 @@ ---- CITABLE SOURCE --- -File: modules/ROOT/pages/customize-spotter-embed.adoc -Branch: docs/scal-26-11-0-cl-doc-updates -URL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc -To cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc#L{line_number} ---- - -{ - "path": "modules/ROOT/pages/customize-spotter-embed.adoc", - "name": "customize-spotter-embed.adoc", - "size": 9216, - "content": "--- CITABLE SOURCE ---\nFile: modules/ROOT/pages/customize-spotter-embed.adoc\nBranch: docs/scal-26-11-0-cl-doc-updates\nURL: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc\nTo cite a specific line: https://github.com/thoughtspot/developer-docs/blob/docs/scal-26-11-0-cl-doc-updates/modules/ROOT/pages/customize-spotter-embed.adoc#L{line_number}\n---\n\n{\n \"path\": \"modules/ROOT/pages/customize-spotter-embed.adoc\",\n \"name\": \"customize-spotter-embed.adoc\",\n \"size\": 7865,\n \"content\": \"= Customize the Spotter embed view\\n:toc: true\\n:toclevels: 2\\n\\n:page-title: Customizing the Spotter embed view\\n:page-pageid: customize-spotter-embed\\n:page-description: You can customize the SpotterEmbed experience using the customization options available in the Visual Embed SDK.\\n\\nThe Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users.\\n\\n== Spotter interface in the embedded view\\nWhen 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 varies depending on the Spotter version used for embedding.\\n\\n=== Default experience\\nThe default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session.\\n+\\nIf Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available.\\n+\\n[.widthAuto]\\n[.bordered]\\nimage::./images/spotter-default-interface.png[Default Spotter interface]\\n\\n=== Spotter 3 experience\\nIf your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK.\\n\\n[source,JavaScript]\\n----\\nconst spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), {\\n worksheetId: '', // Replace with GUID of the data source\\n // Enable the updated Spotter chat prompt experience.\\n updatedSpotterChatPrompt: true,\\n // Show chat history panel\\n spotterSidebarConfig: {\\n enablePastConversationsSidebar: true,\\n },\\n // ...other embed configuration attributes\\n});\\n----\\n\\n[.widthAuto]\\n[.bordered]\\nimage::./images/spotter3-interface.png[Spotter 3 experience]\\n\\n=== New Spotter 3 visual experience\\nOn instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration.\\n\\n[source,JavaScript]\\n----\\nconst spotterEmbed = new SpotterEmbed('#ts-embed', {\\n worksheetId: '', // Replace with GUID of the data source\\n // Enable Spotter 3 chat experience.\\n updatedSpotterChatPrompt: true,\\n // Enable new Spotter visual experience\\n updatedSpotterExperience: true,\\n // Show chat history panel\\n spotterSidebarConfig: {\\n enablePastConversationsSidebar: true,\\n },\\n // ...other embed configuration attributes\\n});\\n----\\n\\n[.widthAuto]\\n[.bordered]\\nimage::./images/spotter-new-experience.png[New Spotter experience]\\n\\nIn the new experience, the + icon displays a menu with the following options:\\n\\n* **Add files** from local directory\\n* **Connectors** to select available connectors\\n* **Deep analysis** toggle to switch between the quick search and research mode.\\n\\nYou can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience].\\n\\n== Customizing Spotter experience\\nIf you want to customize specific features or UI elements, refer to the following documentation:\\n\\n* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +\\nFor information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding.\\n* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +\\nFor information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions.\\n* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +\\nFor information on customizing the conversation sharing experience, sharing links, and app interactions.\\n* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] +\\nFor information on customizing the Spotter Analysts panel and dashboard.\\n\\n== Customizing styles and interface elements using CSS variables\\nThe Visual Embed SDK provides a comprehensive style customization framework for overriding icons, text strings, and the appearance of UI elements.\\n\\nThe `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.\\n\\n[#SpotterCSS]\\n=== CSS variables for style customization\\nYou 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].\\n\\nIf 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.\\n\\n[source,JavaScript]\\n----\\n// Initialize the SDK with CSS variables with custom style definitions\\ninit({\\n // ...\\n customizations: {\\n style: {\\n // Use CSS variables to customize styles\\n customCSS: {\\n variables: {\\n \\\"--ts-var-button--primary-background\\\": \\\"#008000\\\",\\n \\\"--ts-var-spotter-prompt-background\\\": \\\"#F0EBFF\\\",\\n \\\"--ts-var-root-color\\\": \\\"#E3D9FC\\\",\\n \\\"--ts-var-root-background\\\": \\\"#F7F5FF\\\",\\n },\\n },\\n },\\n },\\n});\\n----\\n\\n=== Customizing text strings\\nTo replace text strings, you can use the `stringIDs` and `strings` properties in the content customization object.\\n\\nThe following example shows how to replace \\\"Spotter\\\" and other text strings on the Spotter interface.\\n\\n[source,JavaScript]\\n----\\n// Initialize the SDK with custom text string replacements\\ninit({\\n // ...\\n customizations: {\\n content: {\\n // Use the strings object to replace the visible UI text with custom labels.\\n - -... [truncated, 10,241 chars total] - === SpotterX experience - [.version-badge.new]#26.11.0.cl# - - SpotterX is the next-generation Spotter experience in embedded views. To enable SpotterX, set the `spotterVersion` property to `SpotterVersion.SpotterX` in your embed configuration. - - [source,JavaScript] - ---- - const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { - spotterVersion: SpotterVersion.SpotterX, - worksheetId: 'your-worksheet-id', - //...other attributes - }); - ---- - - SpotterX provides a redesigned conversational interface with the following features: - - * Improved chat layout and user interaction flow - * Enhanced branding controls for text, labels, and icons - * Instance-level branding behavior controls - * Consistent configuration across Spotter, Liveboard, and full app embed contexts - * Full support for `EmbedEvent` and `HostEvent` lifecycle controls - - [NOTE] += Customize 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. + +The Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users. + +[NOTE] ==== - SpotterX is opt-in. Existing Spotter embeds are unaffected unless you explicitly set `spotterVersion` to `SpotterVersion.SpotterX`. To roll back, set `spotterVersion` to `SpotterVersion.Spotter3` and re-render the component. + [.version-badge.new]#26.11.0.cl# Looking for SpotterX? SpotterX, the next-generation Spotter experience, has its own embedding and customization documentation. See xref:embed-spotterx.adoc[Embed SpotterX experience]. ==== - \ No newline at end of file + == Spotter interface in the embedded view +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 varies depending on the Spotter version used for embedding. + +=== Default experience +The default experience in embedded view is the classic Spotter interface with an initial page that includes a prompt bar for user input, a data source selector, and the UI options to preview data and reset a Spotter session. ++ +If Spotter 2 is enabled on your ThoughtSpot instance, additional controls such as Quick search and Deep analysis toggle switch, and the automatic data model selection option are available. ++ +[.widthAuto] +[.bordered] +image::./images/spotter-default-interface.png[Default Spotter interface] + +=== Spotter 3 experience +If your ThoughtSpot instance has Spotter 3 experience enabled, you can enable the same experience in your embed, which includes additional options to add files, connectors, and improved conversational experience. To enable Spotter 3 experience, set `updatedSpotterChatPrompt` to `true` in the SDK. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + worksheetId: '', // Replace with GUID of the data source + // Enable the updated Spotter chat prompt experience. + updatedSpotterChatPrompt: true, + // Show chat history panel + spotterSidebarConfig: { + enablePastConversationsSidebar: true, + }, + // ...other embed configuration attributes +}); +---- + +[.widthAuto] +[.bordered] +image::./images/spotter3-interface.png[Spotter 3 experience] + +=== New Spotter 3 visual experience +On instances with ThoughtSpot Cloud 26.9.0.cl, the new redesigned Spotter experience is enabled by default. The new Spotter experience includes the updated conversation layout and starter-prompt pills. To enable the new visual experience, set `updatedSpotterExperience` to `true` in the `SpotterEmbed` configuration. + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#ts-embed', { + worksheetId: '', // Replace with GUID of the data source + // Enable Spotter 3 chat experience. + updatedSpotterChatPrompt: true, + // Enable new Spotter visual experience + updatedSpotterExperience: true, + // Show chat history panel + spotterSidebarConfig: { + enablePastConversationsSidebar: true, + }, + // ...other embed configuration attributes +}); +---- + +[.widthAuto] +[.bordered] +image::./images/spotter-new-experience.png[New Spotter experience] + +In the new experience, the + icon displays a menu with the following options: + +* **Add files** from local directory +* **Connectors** to select available connectors +* **Deep analysis** toggle to switch between the quick search and research mode. + +You can customize the chat panel and conversational experience further. For more information, see xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience]. + +== Customizing Spotter experience +If you want to customize specific features or UI elements, refer to the following documentation: + +* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] + +For information on customizing the chat panel, data model selection, starter prompts, file uploads, MCP connectors, and Spotter branding. +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] + +For information on customizing the sidebar panel and the chat history panel, including menu actions and app interactions. +* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] + +For information on customizing the conversation sharing experience, sharing links, and app interactions. +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] + +For information on customizing the Spotter Analysts panel and dashboard. + +== Customizing styles and interface elements using CSS variables +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", + }, + }, + }, + }, +}); +---- + +=== Customizing text strings +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 "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 a comprehensive list of supported actions, see the xref:Action.adoc[Action reference documentation]. +//// + + +== Additional resources +* xref:customize-spotter-chat-experience.adoc[Customizing the Spotter chat experience] +* xref:customize-spotter-sidebar.adoc[Customizing the Spotter sidebar panel] +* xref:customize-spotter-sharing.adoc[Customizing Spotter conversation sharing] +* xref:customize-spotter-analysts.adoc[Customizing Spotter Analysts in the embedded view] +* link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods] +* link:https://developers.thoughtspot.com/docs/Interface_SpotterEmbedViewConfig[Configuration options for Spotter interface customization] +* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-embed[Developer examples, window=_blank] +* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Product Documentation] From 14134433af16f2654b109248df52accc0f52eae5 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:31:52 +0530 Subject: [PATCH 074/169] docs: restore full customize-spotter-embed.adoc content; link to new SpotterX page From df797267ac916458cf680faf62051e5f442680b5 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:32:51 +0530 Subject: [PATCH 075/169] docs: fix NOTE block indentation in customize-spotter-embed.adoc --- modules/ROOT/pages/customize-spotter-embed.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/customize-spotter-embed.adoc b/modules/ROOT/pages/customize-spotter-embed.adoc index 62854c7c2..d4d7e0bac 100644 --- a/modules/ROOT/pages/customize-spotter-embed.adoc +++ b/modules/ROOT/pages/customize-spotter-embed.adoc @@ -9,11 +9,11 @@ The Visual Embed SDK provides a vast set of configuration settings and object properties to customize the Spotter UI and chat experience for your embedding application users. [NOTE] - ==== - [.version-badge.new]#26.11.0.cl# Looking for SpotterX? SpotterX, the next-generation Spotter experience, has its own embedding and customization documentation. See xref:embed-spotterx.adoc[Embed SpotterX experience]. - ==== +==== +[.version-badge.new]#26.11.0.cl# Looking for SpotterX? SpotterX, the next-generation Spotter experience, has its own embedding and customization documentation. See xref:embed-spotterx.adoc[Embed SpotterX experience]. +==== - == Spotter interface in the embedded view +== Spotter interface in the embedded view 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 varies depending on the Spotter version used for embedding. === Default experience From 6eda94041a231bdc10b5a9a13c1972dbd015e303 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:33:26 +0530 Subject: [PATCH 076/169] docs: add dedicated SpotterX embed page with Spotter on Liveboards support --- modules/ROOT/pages/embed-spotterx.adoc | 166 +++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 modules/ROOT/pages/embed-spotterx.adoc diff --git a/modules/ROOT/pages/embed-spotterx.adoc b/modules/ROOT/pages/embed-spotterx.adoc new file mode 100644 index 000000000..a3e91c486 --- /dev/null +++ b/modules/ROOT/pages/embed-spotterx.adoc @@ -0,0 +1,166 @@ += Embed SpotterX experience +:toc: true +:toclevels: 2 + +:page-title: Embed SpotterX +:page-pageid: embed-spotterx +:page-description: SpotterX is the next-generation Spotter experience. You can enable SpotterX in standalone Spotter, Liveboard, and full app embeds using the Visual Embed SDK. + +[.version-badge.new]#26.11.0.cl# + +SpotterX is the next-generation Spotter experience in ThoughtSpot. It provides a redesigned conversational interface with an improved chat layout, enhanced white-label and branding controls, and a consistent configuration surface across all supported embed contexts. + +SpotterX is opt-in. Existing Spotter embeds remain unchanged unless you explicitly enable SpotterX in your embed configuration. + +// SOURCE: SCAL-326037 + +== Before you begin + +To embed SpotterX, you need the following access and setup: + +* Access to a ThoughtSpot instance running 26.11.0.cl or later, with SpotterX enabled. To enable SpotterX on your instance, contact your ThoughtSpot administrator. +* Your host application domain added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists]. +* Visual Embed SDK v1.54.0 or later. +// TODO: verify with engineering — confirm the minimum SDK version required for SpotterX + +== Supported embed contexts + +You can enable SpotterX in the following embed contexts: + +[width="100%", cols="2,4"] +[options='header'] +|=== +|Embed context|Description + +|Standalone Spotter (`SpotterEmbed`) +|The full SpotterX conversational experience embedded as a standalone component. + +|Liveboard (`LiveboardEmbed`) +|SpotterX available within an embedded Liveboard. See <>. + +|Full app (`AppEmbed`) +|SpotterX available across the full embedded ThoughtSpot application experience. +|=== + +Configuration behavior is consistent across all three contexts — the same configuration surface applies whether SpotterX runs standalone, in a Liveboard, or in a full app embed. + +== Enable SpotterX + +To enable SpotterX, set the `spotterVersion` property to `SpotterVersion.SpotterX` in your embed configuration. + +// TODO: verify with engineering — confirm the exact enum and property names published in the SDK for SpotterX enablement + +**Code sample for embedding the SpotterX experience** + +[source,JavaScript] +---- +import { + SpotterEmbed, + AuthType, + init, + EmbedEvent, + HostEvent, + SpotterVersion +} from '@thoughtspot/visual-embed-sdk'; + +// Initialize the ThoughtSpot Visual Embed SDK +init({ + thoughtSpotHost: 'https://your-thoughtspot-host', + authType: AuthType.None, +}); + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { + height: '100%', + width: '100%', + }, + worksheetId: '', // Replace with GUID of the data source + spotterVersion: SpotterVersion.SpotterX, // Enable SpotterX + // ...other embed configuration attributes +}); + +// Register event listeners +spotterEmbed.on(EmbedEvent.Init, () => { + // Show loading indicator +}); +spotterEmbed.on(EmbedEvent.Load, () => { + // Hide loading indicator +}); + +// Render the embed +spotterEmbed.render(); +---- + +[#spotterx-liveboard] +== SpotterX in Liveboard embeds + +SpotterX is supported in embedded Liveboards. When enabled, users can start a Spotter conversation from the embedded Liveboard context and analyze the data behind Liveboard visualizations conversationally. + +To enable SpotterX in a Liveboard embed, set `spotterVersion` in the `LiveboardEmbed` configuration: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + liveboardId: '', // Replace with GUID of the Liveboard + spotterVersion: SpotterVersion.SpotterX, // Enable SpotterX in the Liveboard embed + // ...other embed configuration attributes +}); +liveboardEmbed.render(); +---- + +// TODO: verify with engineering — confirm the configuration property and any additional flags required to enable the Spotter on Liveboards experience in embed mode (for example, whether the instance-level "Spotter 3 Liveboard experience" setting must also be enabled) + +[NOTE] +==== +The Spotter on Liveboards experience must be enabled on your ThoughtSpot instance. To enable this feature, contact your ThoughtSpot administrator. +==== + +== White-label and branding controls + +SpotterX supports white-label controls for text, labels, icons, and instance-level branding behavior across all embed surfaces: + +* **Text strings and labels** — Use the `customizations.content.strings` object in the SDK `init` call to replace visible UI text with custom labels. +* **Icons** — Use the icon override framework to replace SpotterX interface icons. For more information, see xref:customize-icons.adoc[Customize icons]. +* **Styles** — Use CSS variables via `customizations.style.customCSS` to adjust colors, fonts, and component appearance. SpotterX consumes `--ts-var` CSS variables for chat chrome styling. For more information, see xref:css-customization.adoc[CSS customization framework]. +* **Instance-level branding suppression** — Branding suppression works across all embed surfaces. + +// SOURCE: SCAL-326037, SCAL-337856 + +== Lifecycle events and runtime control + +Host applications can observe SpotterX lifecycle events and trigger supported actions through the `EmbedEvent` and `HostEvent` framework: + +* Use `EmbedEvent` members to listen to SpotterX lifecycle and interaction events in the embedded view. +* Use `HostEvent` members to trigger supported actions in the SpotterX interface from your host application. + +// TODO: verify with engineering — confirm the full list of EmbedEvents and HostEvents supported by SpotterX in the initial release + +== Roll back to Spotter 3 + +SpotterX rollback is a configuration value change plus re-render: + +. Set `spotterVersion` to `SpotterVersion.Spotter3` in your embed configuration. +. Re-render the embed component. + +No data or conversation history is affected by the rollback. + +// SOURCE: SCAL-326037 + +== Migration considerations + +SpotterX has a new DOM structure. If your embedding application relies on custom CSS selectors targeting the internal DOM of the classic Spotter interface, review and update your customizations after switching to SpotterX. ThoughtSpot recommends using the published `--ts-var` CSS variables and the SDK customization framework instead of DOM-based selectors. + +== Known limitations + +* Full feature parity with Spotter 3 is not available in the initial SpotterX release. +* Spotter Actions and `defaultQueryMode` are not included in the initial release. + +// SOURCE: SCAL-326037 + +== Additional resources + +* xref:embed-spotter.adoc[Embed Spotter experience] +* xref:customize-spotter-embed.adoc[Customize the Spotter embed view] +* xref:embed-ai-analytics.adoc[Feature status and availability in embed mode] +* link:https://developers.thoughtspot.com/docs/Class_SpotterEmbed[SpotterEmbed classes and methods] +* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Product Documentation] From 785c1b28e753c01f39fe721b545f47936a728c90 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:34:27 +0530 Subject: [PATCH 077/169] docs: point November SpotterX entry to new embed-spotterx page --- modules/ROOT/pages/whats-new.adoc | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 432d4a5ff..208cf02a8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -43,7 +43,7 @@ ThoughtSpot introduces SpotterX, the next-generation Spotter experience, with fu SpotterX is opt-in. Set `spotterVersion` to `SpotterVersion.SpotterX` in your `SpotterEmbed`, `LiveboardEmbed`, or `AppEmbed` configuration to enable it. Existing Spotter embeds remain unchanged unless explicitly opted in. -For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. +For more information, see xref:embed-spotterx.adoc[Embed SpotterX experience]. [discrete] ==== API rate limit enforcement @@ -63,13 +63,7 @@ For more information, see xref:link-customization-api.adoc[Link Customization AP [discrete] ==== Input Table APIs [.version-badge.new]#New# + -These REST API v2.0 endpoints allow you to create and manage input tables programmatically. An input table is a table that users can edit, stored in an external Cloud Data Warehouse (CDW) and linked to a ThoughtSpot model. - -* `POST /api/rest/2.0/input-tables/create` -* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` -* `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` -* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` -* `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` +Five new REST API v2.0 endpoints allow you to create and manage input tables — user-editable tables stored in an external CDW and linked to a ThoughtSpot model. For more information, see xref:input-table-api.adoc[Input Table APIs]. @@ -88,12 +82,6 @@ For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data AP ==== Share Analyst API The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. -[discrete] -==== Object ID in ThoughtSpot URLs [earlyAccess eaBackground]#Early Access# -You can now use an object ID (`obj_id`) instead of a GUID in ThoughtSpot URLs for Liveboards, Answers, Collections, Models, Worksheets, Tables, Views, and Connections. Because you assign the same `obj_id` to an object in every environment, links built by your host application open the correct object when switching environments. You no longer need a GUID mapping for each environment. Existing GUID-based URLs continue to work. - -For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. For guidance on moving a GUID-based deployment pipeline to `obj_id`, see xref:deploy-with-tml-apis.adoc#adopting-obj-id-in-deployment-pipeline[Adopting obj_id in a deployment pipeline]. - [discrete] ==== Default RBAC enablement for new clusters Starting with 26.11.0.cl, Role-Based Access Control (RBAC) is enabled by default on all new ThoughtSpot Cloud clusters. Existing clusters are not affected. For more information about RBAC, see xref:rbac.adoc[Role-based access control]. From 7c05146b1f7b0ca2957cbc1d43ffc393e270a1ae Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:34:29 +0530 Subject: [PATCH 078/169] docs: point SDK 1.54.0 SpotterX entry to new embed-spotterx page --- modules/ROOT/pages/api-changelog.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index dbe642cdc..665b9b28e 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -28,7 +28,7 @@ const embed = new SpotterEmbed('#tsEmbed', { }); ---- -For more information, see xref:embed-spotter.adoc[Embed Spotter experience] and xref:customize-spotter-embed.adoc[Customize the Spotter embed view]. +For more information, see xref:embed-spotterx.adoc[Embed SpotterX experience]. |[tag greenBackground]#NEW# a| From 41c453476881a608da9cdab177ac04ff0921d506 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:34:31 +0530 Subject: [PATCH 079/169] docs: replace inline SpotterX sample with pointer to dedicated embed-spotterx page --- modules/ROOT/pages/embed-spotter.adoc | 40 ++++----------------------- 1 file changed, 5 insertions(+), 35 deletions(-) diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index 2c626bf0f..333e41f87 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -277,42 +277,12 @@ if (container) { }); } ---- - **Code sample for embedding SpotterX experience** + [NOTE] + ==== + [.version-badge.new]#26.11.0.cl# To embed SpotterX, the next-generation Spotter experience, see xref:embed-spotterx.adoc[Embed SpotterX experience]. + ==== - [source,JavaScript] - ---- - import { - SpotterEmbed, - AuthType, - init, - EmbedEvent, - HostEvent - } from '@thoughtspot/visual-embed-sdk'; - - init({ - thoughtSpotHost: 'https://your-thoughtspot-host', - authType: AuthType.None, - }); - - const container = document.getElementById('ts-embed'); - if (container) { - const spotterEmbed = new SpotterEmbed(container, { - frameParams: { - height: '100%', - width: '100%', - }, - worksheetId: 'your-worksheet-id', - spotterVersion: SpotterVersion.SpotterX, - // ... other configuration attributes - }); - - spotterEmbed.on(EmbedEvent.Init, showLoader); - spotterEmbed.on(EmbedEvent.Load, hideLoader); - spotterEmbed.render(); - } - ---- - - + == Additional resources * xref:embed-ai-analytics.adoc[Spotter features and embedding options] From 72e388a2bd17a6d62845353e921bbae6e5ea00d8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:34:33 +0530 Subject: [PATCH 080/169] docs: point November SpotterX entry to new embed-spotterx page From 1d84d17345f96f0811a1689da9b6cacd9d864b63 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:34:35 +0530 Subject: [PATCH 081/169] docs: point SDK 1.54.0 SpotterX entry to new embed-spotterx page From 467f28dd87996563727273cac1f324a27ddb49ff Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Wed, 14 Oct 2026 14:34:37 +0530 Subject: [PATCH 082/169] docs: replace inline SpotterX sample with pointer to dedicated embed-spotterx page From 33f51c1d6ceda31ff86e6600520c65dc3a1c8a3d Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 15 Oct 2026 00:37:19 +0530 Subject: [PATCH 083/169] rbac for input tables --- modules/ROOT/pages/roles.adoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index 992e60f1c..12982d002 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -166,6 +166,15 @@ UI: *Can create/edit Connections*| Allows creating, editing, and managing link:h UI: *Can manage data models* |Allows users to create, edit, delete, and manage Models, Tables, and Views. |Custom variables| API: `CAN_MANAGE_VARIABLES` + UI: *Can manage variables* | Allows users to manage formula Variables in the current Org scope. +// SOURCE: SCAL-301436; SCAL-305010; PrivilegeTypeEnum.java (dev/scaligent) +// Available from: ThoughtSpot Cloud 26.6.0.cl +|Manage input tables| API: `CAN_MANAGE_INPUT_TABLES` + +UI: *Can manage input tables* | Allows users to create, delete, and upload data to input tables. Applicable only on ThoughtSpot Cloud (SaaS) instances. +// SOURCE: SCAL-305010; PrivilegeTypeEnum.java (dev/scaligent) +// Available from: ThoughtSpot Cloud 26.10.0.cl +// TODO: verify with engineering — confirm CAN_EDIT_INPUT_TABLES exact release version (parent SCAL-325428 has no fix version set) +|Edit input tables| API: `CAN_EDIT_INPUT_TABLES` + +UI: *Can edit input tables* | Allows users to update values in existing input tables. Does not grant permission to create or delete input tables. Applicable only on ThoughtSpot Cloud (SaaS) instances. |=== From f82e431e43f4ee630caad866471d4b276edf901f Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 15 Oct 2026 00:59:56 +0530 Subject: [PATCH 084/169] brought back my overwritten changes --- modules/ROOT/pages/roles.adoc | 1 - modules/ROOT/pages/whats-new.adoc | 14 +++++++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index 12982d002..40de9146b 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -172,7 +172,6 @@ UI: *Can manage variables* | Allows users to manage formula Variables in the cur UI: *Can manage input tables* | Allows users to create, delete, and upload data to input tables. Applicable only on ThoughtSpot Cloud (SaaS) instances. // SOURCE: SCAL-305010; PrivilegeTypeEnum.java (dev/scaligent) // Available from: ThoughtSpot Cloud 26.10.0.cl -// TODO: verify with engineering — confirm CAN_EDIT_INPUT_TABLES exact release version (parent SCAL-325428 has no fix version set) |Edit input tables| API: `CAN_EDIT_INPUT_TABLES` + UI: *Can edit input tables* | Allows users to update values in existing input tables. Does not grant permission to create or delete input tables. Applicable only on ThoughtSpot Cloud (SaaS) instances. |=== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 208cf02a8..ed70a7a1f 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -63,7 +63,13 @@ For more information, see xref:link-customization-api.adoc[Link Customization AP [discrete] ==== Input Table APIs [.version-badge.new]#New# + -Five new REST API v2.0 endpoints allow you to create and manage input tables — user-editable tables stored in an external CDW and linked to a ThoughtSpot model. +These REST API v2.0 endpoints allow you to create and manage input tables programmatically. An input table is a table that users can edit, stored in an external Cloud Data Warehouse (CDW) and linked to a ThoughtSpot model. + +* `POST /api/rest/2.0/input-tables/create` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/create` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/update` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/columns/{column_identifier}/delete` +* `POST /api/rest/2.0/input-tables/{input_table_identifier}/delete` For more information, see xref:input-table-api.adoc[Input Table APIs]. @@ -82,6 +88,12 @@ For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data AP ==== Share Analyst API The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. +[discrete] +==== Object ID in ThoughtSpot URLs [earlyAccess eaBackground]#Early Access# +You can now use an object ID (`obj_id`) instead of a GUID in ThoughtSpot URLs for Liveboards, Answers, Collections, Models, Worksheets, Tables, Views, and Connections. Because you assign the same `obj_id` to an object in every environment, links built by your host application open the correct object when switching environments. You no longer need a GUID mapping for each environment. Existing GUID-based URLs continue to work. + +For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. For guidance on moving a GUID-based deployment pipeline to `obj_id`, see xref:deploy-with-tml-apis.adoc#adopting-obj-id-in-deployment-pipeline[Adopting obj_id in a deployment pipeline]. + [discrete] ==== Default RBAC enablement for new clusters Starting with 26.11.0.cl, Role-Based Access Control (RBAC) is enabled by default on all new ThoughtSpot Cloud clusters. Existing clusters are not affected. For more information about RBAC, see xref:rbac.adoc[Role-based access control]. From bd297bcdad848c17194360ee6921719f751cb72c Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 15 Oct 2026 01:05:31 +0530 Subject: [PATCH 085/169] removed EA for obj id urls: --- modules/ROOT/pages/object-id-in-urls.adoc | 4 +--- modules/ROOT/pages/whats-new.adoc | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/object-id-in-urls.adoc b/modules/ROOT/pages/object-id-in-urls.adoc index 7720e16b4..1f338c7b7 100644 --- a/modules/ROOT/pages/object-id-in-urls.adoc +++ b/modules/ROOT/pages/object-id-in-urls.adoc @@ -1,4 +1,4 @@ -= Object ID in ThoughtSpot URLs [earlyAccess eaBackground]#Early Access# += Object ID in ThoughtSpot URLs :toc: true :toclevels: 2 @@ -8,8 +8,6 @@ You can use an object's xref:object-id.adoc[Object ID] (`obj_id`) in place of its GUID in a ThoughtSpot URL. Because you assign the same `obj_id` to an object in every environment, a URL built with an `obj_id` opens the correct object in development, staging, and production. -This feature is in Early Access and disabled by default. Contact ThoughtSpot Support to enable it for your instance. - == When to use Object ID in URLs GUIDs are generated separately on each ThoughtSpot instance and in each Org. When content is promoted from one environment to another, every object gets a new GUID, so any URL built with a GUID works only in the environment where it was created. Without Object ID, embedded applications and deployment pipelines have to maintain a GUID mapping table for each environment and update it after every deployment. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index ed70a7a1f..f4a6a49af 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -89,7 +89,7 @@ For more information, see xref:spotter-usage-data-api.adoc[Spotter Usage Data AP The new `POST /api/rest/2.0/ai/shareAnalyst` endpoint allows you to update share permissions for a Spotter Analyst programmatically. [discrete] -==== Object ID in ThoughtSpot URLs [earlyAccess eaBackground]#Early Access# +==== Object ID in ThoughtSpot URLs You can now use an object ID (`obj_id`) instead of a GUID in ThoughtSpot URLs for Liveboards, Answers, Collections, Models, Worksheets, Tables, Views, and Connections. Because you assign the same `obj_id` to an object in every environment, links built by your host application open the correct object when switching environments. You no longer need a GUID mapping for each environment. Existing GUID-based URLs continue to work. For more information, see xref:object-id-in-urls.adoc[Object ID in ThoughtSpot URLs]. For guidance on moving a GUID-based deployment pipeline to `obj_id`, see xref:deploy-with-tml-apis.adoc#adopting-obj-id-in-deployment-pipeline[Adopting obj_id in a deployment pipeline]. From ce8a9bdc09531a2e38e9686e6422e8eb489fdf08 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Fri, 16 Oct 2026 17:13:37 +0530 Subject: [PATCH 086/169] tutorial text and image fixes --- .../pages/rest-api/rest-api-intro.adoc | 2 +- .../pages/rest-api/rest-api_lesson-01.adoc | 12 +- .../pages/rest-api/rest-api_lesson-02.adoc | 31 +++- .../pages/rest-api/rest-api_lesson-03.adoc | 4 +- .../pages/rest-api/rest-api_lesson-04.adoc | 10 +- .../style-customization_tutorial-step-02.adoc | 2 +- .../style-customization_tutorial-step-03.adoc | 8 +- .../style-customization_tutorial-step-04.adoc | 8 +- .../style-customization_tutorial-step-06.adoc | 2 +- .../tse-fundamentals-intro.adoc | 14 +- .../tse-fundamentals-lesson-02.adoc | 4 +- .../tse-fundamentals-lesson-03.adoc | 22 +-- .../tse-fundamentals-lesson-04.adoc | 2 +- .../tse-fundamentals-lesson-05.adoc | 15 +- .../tse-fundamentals-lesson-06.adoc | 136 +----------------- .../tse-fundamentals-lesson-07.adoc | 12 +- .../tse-fundamentals-lesson-08.adoc | 18 ++- .../tse-fundamentals-lesson-09.adoc | 16 +-- .../tse-fundamentals-lesson-10.adoc | 21 +-- .../tse-fundamentals-lesson-11.adoc | 2 +- .../rest-api/playground-leftside-menu.png | Bin 81220 -> 92404 bytes .../choose-liveboard-embed.png | Bin 41790 -> 56563 bytes .../tse-fundamentals/lesson-02-doc-links.png | Bin 401808 -> 435123 bytes .../lesson-02-playground-lb.png | Bin 0 -> 424950 bytes .../lesson-03-security-settings.png | Bin 82884 -> 293977 bytes .../lesson-07-empty-liveboard.png | Bin 83133 -> 98694 bytes .../lesson-07-liveboard-selected.png | Bin 195800 -> 272035 bytes .../lesson-09-default-app-playground.png | Bin 225448 -> 244190 bytes .../tse-fundamentals/lesson-10-style-page.png | Bin 85610 -> 277930 bytes 29 files changed, 105 insertions(+), 236 deletions(-) create mode 100644 static/doc-images/images/tutorials/tse-fundamentals/lesson-02-playground-lb.png diff --git a/modules/tutorials/pages/rest-api/rest-api-intro.adoc b/modules/tutorials/pages/rest-api/rest-api-intro.adoc index a1857d2c6..2d0ecd835 100644 --- a/modules/tutorials/pages/rest-api/rest-api-intro.adoc +++ b/modules/tutorials/pages/rest-api/rest-api-intro.adoc @@ -23,7 +23,7 @@ Your setup must have the following applications and tools installed: * Chrome or Firefox * Python 3.8 or higher * link:https://code.visualstudio.com/[Visual Studio Code, window=_blank] or link:https://www.jetbrains.com/pycharm/[PyCharm, window=_blank] -* link:https://github.com/thoughtspot/thoughtspot_rest_api_python[The `thoughtspot_rest_api` GitHub repository, window=_blank] (supports REST API V1 and V2.0) in your local Python environment +* link:https://github.com/thoughtspot/thoughtspot_rest_api_python[The `thoughtspot_rest_api` GitHub repository, window=_blank] (supports REST API V1 and V2.0), installed in your local Python environment with `python3 -m pip install thoughtspot_rest_api` Download the entire link:https://github.com/thoughtspot/tse-api-tutorial[tse-api-tutorial repository, window=_blank] as a ZIP file from GitHub, then unzip it on your system: diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc index dfb69b6cb..f8d5edcb7 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc @@ -51,7 +51,7 @@ Reports:: exports in a file format Security:: permissions and access control (sharing) Data:: exports in a JSON data format -Once you click on an individual endpoint, you will see the specification for that endpoint in the middle area, and an example of using cURL to issue the request to the endpoint properly on the left: +Once you click on an individual endpoint, you will see the specification for that endpoint in the middle area, and an example of using cURL to issue the request to the endpoint properly on the right: [.widthAuto] [.bordered] @@ -77,15 +77,15 @@ DELETE:: delete, often only has a URL (but some systems use a body) [NOTE] ==== -ThoughtSpot REST API V2.0 only uses *GET* and *POST* verbs. +ThoughtSpot REST API V2.0 mostly uses *POST* and *GET* verbs. A few endpoints use *PUT* or *DELETE*. The full endpoint name includes the action the endpoint will take, rather than the same endpoint responding to different HTTP verbs. ==== -Any endpoint that ends in `/search` is a `GET` request for querying information. +Most endpoints that end in `/search` are `POST` requests for querying information. The criteria for the search are sent as a JSON body, which is required even if it is empty (`{}`). === HTTP headers -Headers describe aspects of the request, and are mandatory for any given endpoint. +Headers describe aspects of the request, and some are required for any given endpoint. ThoughtSpot's V2.0 REST API typically requires the following headers: ---- @@ -98,7 +98,7 @@ The endpoints to request access tokens do not require the `Authorization` header Endpoints that return something other than a JSON response do not use the `Accept: application/json` header. === HTTP Body -Body is data sent with the request, that does not appear in the URL (is secure). The body will vary with each endpoint, and some endpoints do not require a body at all. +Body is data sent with the request, that does not appear in the URL. The body will vary with each endpoint, and some endpoints do not require a body at all. The body of all V2.0 REST API requests will be in JSON format. @@ -111,7 +111,7 @@ You can copy the JSON request from the Playground and use directly in JavaScript == 03 - HTTP responses Each HTTP request will result in some action within the web server and then a *response*. -For *GET* requests, the only expected action is a *response* with some element. For example, the `/search` endpoints within the V2.0 REST API are *GET* requests that return sets of information about the system. +For requests that only read information, the only expected action is a *response* with some element. For example, the `/search` endpoints within the V2.0 REST API are *POST* requests that return sets of information about the system without changing it. Other types of requests cause a state change on the server, and then a response describing the new state after the action has completed. 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 09465f8d9..bb67c1192 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc @@ -6,7 +6,7 @@ [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. +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:rest-api-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 @@ -14,7 +14,7 @@ We'll use the files from the link:https://github.com/thoughtspot/tse-api-tutoria . Open your IDE + Visual Studio Code will be used in all images and instructions. -The files for this lesson are `api_training_python_1_begin.py` and `api_training_python_1_end.py`. +The files for this lesson are `api_training_python_1_begin.py` and `api_training_python_1_final.py`. . Open up your command line or terminal environment as well. [NOTE] @@ -101,7 +101,9 @@ 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}" @@ -175,7 +177,7 @@ image:images/tutorials/rest-api/python-command-in-terminal.png[Running script in If you have a more complex local Python environment you are using, find the appropriate way to send the script you have updated through the Python environment set up for this tutorial. === Update the Session object headers -Almost all REST API endpoints other than the token requests require authentication, either within the cookies or via an `Authentication: Bearer {token}` header. +Almost all REST API endpoints other than the token requests require authentication, either within the cookies or via an `Authorization: Bearer {token}` header. You need to update the `Session` object with this new header while keeping the original ones. @@ -219,6 +221,7 @@ try: except Exception as e: # do whatever is necessary in exception case + print(e) # Code after the try block will now run even after Exception ---- @@ -236,7 +239,7 @@ try: resp = requests_session.post(url=url, json=json_post_data) resp.raise_for_status() print(resp) - token = resp["token"] + token = resp.json()["token"] except requests.exceptions.HTTPError as e: print(e) print(e.request) @@ -258,6 +261,15 @@ thoughtspot_url = 'https://{}.thoughtspot.cloud' org_id = 0 api_version = '2.0' +base_url = '{thoughtspot_url}/api/rest/{version}/'.format(thoughtspot_url=thoughtspot_url, version=api_version) +api_headers = { + 'X-Requested-By': 'ThoughtSpot', + 'Accept': 'application/json' +} + +requests_session = requests.Session() +requests_session.headers.update(api_headers) + endpoint = 'auth/token/full' url = base_url + endpoint @@ -293,6 +305,7 @@ except requests.exceptions.HTTPError as e: print(e.request.headers) print(e.request.body) print(e.response.content) + exit() # Stop here, because there is no token to use # Update api_headers from before with header for Bearer token api_headers['Authorization'] = 'Bearer {}'.format(token) @@ -305,9 +318,13 @@ user_search_url = base_url + "users/search" # Every request must be wrapped in try...except try: - search_resp = requests_session.get(url=user_search_url) + # Search endpoints are POST requests and need a JSON body, even if it is only {} + search_resp = requests_session.post(url=user_search_url, json={"record_offset": 0, "record_size": 10}) search_resp.raise_for_status() -... + print(json.dumps(search_resp.json(), indent=2)) +except requests.exceptions.HTTPError as e: + print(e) + print(e.response.content) ---- You may have noticed many steps that are repeated each time for any given request. diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc index a205c4325..361fbb9a8 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc @@ -5,7 +5,7 @@ :toc!: == Get started -The files for this tutorial are `api_training_python_2_begin.py` and `api_training_python_2_end.py`. +The files for this tutorial are `api_training_python_2_begin.py` and `api_training_python_2_final.py`. You must have installed the `thoughtspot_rest_api` library in the Python environment you are using, based on the tutorial prerequisites. Despite the name, the library has components for interacting with both the V1 and V2.0 ThoughtSpot REST APIs. @@ -180,7 +180,7 @@ The first of our tasks is: # Is this a case-sensitive or case-insensitive operation? Are we finding anywhere in the name or just at the start or end? ---- -Information about the objects in the system lives under the `Metadata` heading within the Playground. Endpoints labeled `Search` are `GET` methods that query information without causing any changes. +Information about the objects in the system lives under the `Metadata` heading within the Playground. Endpoints labeled `Search` are `POST` requests that query information without causing any changes. `/metadata/search` has many different xref:rest-api-v2-metadata-search.adoc[request parameters] available to help filter and select all of the necessary information. diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc index effe6ca22..9a191ac52 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc @@ -112,7 +112,7 @@ const apiRequestObject = { The `fetch()` function in JavaScript uses the browser itself as a store of cookies and other details when you use the `credentials: "include"` parameter. -`fetch` is an asynchronous call that returns a `Promise`, which has `.then()` and `.error()` methods for calling the next code to run once the REST API response is returned: +`fetch` is an asynchronous call that returns a `Promise`, which has `.then()` and `.catch()` methods for calling the next code to run once the REST API response is returned: [source,javascript] ---- @@ -122,7 +122,7 @@ const apiFullEndpoint = tsHost + "/" + publicApiUrl + endpoint; await fetch( apiFullEndpoint, // URL { - method: ‘POST’, + method: 'POST', headers: { "Accept": "application/json", "X-Requested-By": "ThoughtSpot", @@ -159,7 +159,7 @@ const apiFullEndpoint = tsHost + "/" + publicApiUrl + endpoint; await tokenizedFetch( apiFullEndpoint, // URL { - method: ‘POST’, + method: 'POST', headers: { "Accept": "application/json", "X-Requested-By": "ThoughtSpot", @@ -276,7 +276,7 @@ To use such a function you define your request object, copied from the REST API [source,javascript] ---- // Here we actually CALL the functions to make the request -function makeSearchRequest(){ +async function makeSearchRequest(){ // Copy the request directly from the REST API Playground, substituting in any variables you need const apiRequestObject = { "metadata": [ @@ -294,7 +294,7 @@ function makeSearchRequest(){ } - let results = callMetadataSearchApi(apiRequestObject); + let results = await callMetadataSearchApi(apiRequestObject); console.log("Final results from the callMetadataSearchApi function: "); console.log(results); } diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc index 74b307c13..6184bccd8 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc @@ -37,7 +37,7 @@ The code includes examples of several settings that are commented out using the . Click *Run* again to see the updated results. == Available options for component element customization -There are many more configurations available for each component than those available in the Playground. To see all available options, see link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_interfaces[Embed Classes^] and link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_interfaces[Embed Interfaces^]. +There are many more configurations available for each component than those available in the Playground. To see all available options, see link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_classes[Embed Classes^] and link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_interfaces[Embed Interfaces^]. [.bordered] diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc index 751027c1a..da9f72406 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc @@ -69,7 +69,7 @@ Variables declare a __single__ property, therefore are defined as `"{var-name}" Selectors apply properties to elements with many layers of styling. Always add `!important` after each property to ensure the browser overrides whatever other style rules may be applied for the same property. ==== -One use case of the `rules_UNSTABLE` section is `xref:css-customization.adoc#font-declarations[@font-face]` declarations, which have many properties for one selector. +One use case of the `rules_UNSTABLE` section is xref:css-customization.adoc#_font_declarations[`@font-face`] declarations, which have many properties for one selector. We'll switch the main font to link:https://fonts.google.com/specimen/Poppins[Poppins^], available from Google Fonts: @@ -107,7 +107,7 @@ Notice the format shows the selector as the __key__, then an object block contai == CSS files You can collect a set of variables and selectors into a CSS file, rather than declaring them in the JavaScript code block. -CSS files can be included from any domain, but they must be added to the *CSP style-src domains* and *CSP font-src* domains on the *Develop* > *Customizations* -> *Security settings* page. +CSS files can be included from any domain, but they must be added to the *CSP style-src domains* and *CSP font-src domains* lists on the *Develop* > *Customizations* > *Security settings* page. Both `\https://cdn.jsdelivr.net` and `\https://fonts.gstatic.com` sites are automatically added to ThoughtSpot's CSP allowlist. @@ -118,7 +118,7 @@ In your CSS file, the global variables must be declared in the `:root { }` block :root { --ts-var-button--primary-background: #2359B6; --ts-var-button--primary--hover-background: blue; - --ts-var-button--primary--font-family: Poppins,Helvetica,Arial,sans-serif;; + --ts-var-button--primary--font-family: Poppins,Helvetica,Arial,sans-serif; } @font-face { @@ -141,7 +141,7 @@ As seen in the CSS file example above, one of the use cases for selectors is to Make sure that the selector you use is specific and does not affect other elements that you don't intend to hide. -If you have been hiding certain elements via CSS selectors, link:https://community.thoughtspot.com/s/ideas[contact ThoughtSpot^] to request configuration options for such elements, so that the overall configurations can be expanded over time. Similarly, provide feedback on properties that variables are unavailable by submitting an idea to the link:https://community.thoughtspot.com/s/ideas[ThoughtSpot Community^]. +If you have been hiding certain elements via CSS selectors, link:https://community.thoughtspot.com/s/ideas[contact ThoughtSpot^] to request configuration options for such elements, so that the overall configurations can be expanded over time. Similarly, provide feedback on properties for which variables are unavailable by submitting an idea to the link:https://community.thoughtspot.com/s/ideas[ThoughtSpot Community^]. ++++
diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc index 847d09907..5158167b2 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc @@ -5,11 +5,11 @@ :page-pageid: style-customization__step-04 :page-description: Replace text strings and icon sprites in embedded ThoughtSpot content using the customizations framework. -The `customizations` object allows replacing replace specific xref:customize-text-strings.adoc[text strings] and xref:customize-icons.adoc[icons]. +The `customizations` object allows replacing specific xref:customize-text-strings.adoc[text strings] and xref:customize-icons.adoc[icons]. == Replace text strings -Let's add the `content` property above the `style` property in the `customizations` code and then add the `strings` property block within this code. Now we can declare the exact text elements to replace within ThoughtSpot: +Let's add the `content` property above the `style` property in the `customizations` code and then add the `strings` property block within this code. Now we can declare the exact text elements to replace within ThoughtSpot: [source,javascript] ---- @@ -23,7 +23,7 @@ customizations: { } }, style: { - ... + // ... your style settings from the previous step }, }, ---- @@ -45,7 +45,7 @@ customizations: { } }, style: { - ... + // ... your style settings from the previous step }, }, ---- diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc index 6e4e41fea..bb8d769c3 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc @@ -7,7 +7,7 @@ This tutorial has covered how to customize the UI and UX of ThoughtSpot's embedded components, but only within the Visual Embed SDK Playground. -The next steps are to move this code into your application page and configure the CSP and CORS settings for your application's test environments, so you begin integrating ThoughtSpot directly into your application. +The next steps are to move this code into your application page and configure the CSP and CORS settings for your application's test environments, so that you can begin integrating ThoughtSpot directly into your application. ++++
diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc index c199d0f96..88154fb0e 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc @@ -1,7 +1,7 @@ = ThoughtSpot Embedding fundamentals :toc!: -:page-title: ThoughtSpot Embeddig fundamentals +:page-title: ThoughtSpot Embedding fundamentals :page-pageid: tse-fundamentals__intro :page-description: This is a self-guided course on ThoughtSpot Embedding Fundamentals. @@ -11,9 +11,9 @@ Each section is broken down into a concrete topic along with instructions on the == Requirements -This course was created using version 9.10.0.cl. -Features are regularly updated, so if you are using a more recent version, then things may have changed. -To use some features, your ThoughtSpot instance should be on a more recent release version. +ThoughtSpot features and the Visual Embed SDK are updated regularly, so the UI and code samples in this course may differ slightly from the version you are using. +To use some features, your ThoughtSpot instance and the Visual Embed SDK must be on a recent release version. +For the latest changes, see xref:whats-new.adoc[What's New]. == Resources @@ -23,15 +23,15 @@ For this tutorial, you will need the following: Google Chrome is recommended, but not required. All examples in this tutorial use Chrome. * Access to a ThoughtSpot instance with ThoughtSpot Embedded enabled. + -If you don't have an account, you can create a link:https://thoughtspot.com/trial?tsref=dev=stepbystep[trial account, window=_blank]. -* A code editor for editing the Javascript code. + +If you don't have an account, you can create a link:https://www.thoughtspot.com/trial?tsref=ts-dev-training[trial account, window=_blank]. +* A code editor for editing the JavaScript code. + The examples in this tutorial use link:https://code.visualstudio.com/[Visual Studio Code, window=_blank], a free editor that works on many operating systems. * A web server that will host static web content (.html, .css, .js files). The examples in this tutorial use the Live Server plug-in for Visual Studio Code. * A basic understanding of ThoughtSpot. + This can be obtained by taking introductory courses. For information about the courses you can take to learn the basics, see the link:https://training.thoughtspot.com/[ThoughtSpot Training site, window=_blank] for courses. -Ideally, you will have some experience with HTML and Javascript, but it's not required. +Ideally, you will have some experience with HTML and JavaScript, but it's not required. == Lessons This tutorial is split into smaller lessons, with specific objectives for each section. diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc index 60d6667f5..d394843a1 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc @@ -48,11 +48,11 @@ image:images/tutorials/tse-fundamentals/lesson-02-doc-links.png[Access Guides fr To open the Playground, go to *Visual Embed SDK* > *Playground* on the *Develop* page. The playground lets you quickly and easily generate working code that you can embed into your application. -The following figure shows the Playground page for embedding Natural Language Search. +The following figure shows an example of the Playground page. [.widthAuto] [.bordered] -image:images/tutorials/tse-fundamentals/lesson-02-playground-sage-search.png[Using the playground to generate code, scale=50%] +image:images/tutorials/tse-fundamentals/lesson-02-playground-lb.png[Using the playground to generate code, scale=70%] The image above has three main sections: diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc index 49cd95c62..9b8cdd8d9 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc @@ -2,7 +2,7 @@ :toc!: :page-title: Security setup -:page-pageid: tse-fundamentals__lesson-03 +:page-pageid: tse-fundamentals__lesson-03 :page-description: This lesson covers the security setup necessary to embed ThoughtSpot into TSE applications. ThoughtSpot Embedded applications operate securely with ThoughtSpot. This lesson will walk you through the security setup required for embedding ThoughtSpot. @@ -24,11 +24,10 @@ Security when using ThoughtSpot and ThoughtSpot Embedded can be in the following [options='header'] |===== |Security setting| Managed at -|Embed / web security are the security settings that allow you to embed ThoughtSpot into your application|ThoughtSpot Embedded +|Embed / web security are the security settings that allow you to embed ThoughtSpot into your application. For more information, see <<_embed_web_security,Embed / web security>>.|ThoughtSpot Embedded |Authentication determines how you will authenticate the user with ThoughtSpot. Both the authentication supported by ThoughtSpot and ThoughtSpot Embedded have to be considered.| ThoughtSpot Embedded + ThoughtSpot Analytics application -|Content security is managed by ThoughtSpot to determine what content a user has access to, such as Tables, Models (formerly Worksheets), and Liveboards. Data security can be controlled separately | ThoughtSpot Analytics application. -For more information, see xref:_embed_web_security[the following sections]. +|Content security is managed by ThoughtSpot to determine what content a user has access to, such as Tables, Models (formerly Worksheets), and Liveboards. Data security can be controlled separately | ThoughtSpot Analytics application |System privileges / roles define what a user can do inside ThoughtSpot, such as downloading data or using SpotIQ.|ThoughtSpot Analytics application |Data security restricts the columns or rows of data from the source data. Data security is managed via row-level security settings or column sharing in ThoughtSpot. It can also be controlled using pass-through security to the Cloud data warehouse.| ThoughtSpot Analytics application |===== @@ -37,7 +36,7 @@ For more information, see xref:_embed_web_security[the following sections]. The embed and web security settings determine which applications can embed ThoughtSpot and make API calls via JavaScript (cross-site scripting). -Security settings are set on the *Developer > Customisations > Security Settings* page in the ThoughtSpot UI. You can see this page if you have Developer or Administrator privileges. To configure the settings, you will need administrator privileges. +Security settings are set on the *Develop* > *Customizations* > *Security settings* page in the ThoughtSpot UI. You can see this page if you have Developer or Administrator privileges. To configure the settings, you will need administrator privileges. [.widthAuto] [.bordered] @@ -47,7 +46,7 @@ The following are the most important settings for embedding ThoughtSpot. Except === CSP visual embed hosts -CSP visual embed hosts are the URLs that are permitted to embed ThoughtSpot. For example, `\https://mycoolapp.mycompany.com`. If your app URL is not in the list, then you will get CSP errors when embedding. For development, you can add localhost, but it's not recommended for production environments. You only need a port if you are using a non-standard port such as 80, 443. +CSP visual embed hosts are the URLs that are permitted to embed ThoughtSpot. For example, `\https://mycoolapp.mycompany.com`. If your app URL is not in the list, then you will get CSP errors when embedding. For development, you can add localhost, but it's not recommended for production environments. You only need to specify a port if you are using a non-standard port such as 8080. If you add `localhost` or any non-HTTPS domain, include the `http` protocol, for example `\http://localhost:8000`. === CSP connect-src domains @@ -55,9 +54,9 @@ The CSP connect-src domains are those domains that you can send data _to_. This === CORS trusted domains -Domains added to CORS allowlist can use cross-site scripting, that is, calling web service endpoints (including login) from a web application. Command-line applications and tools, such as CURL, are not impacted by this setting. The values are the list of domains (without protocol) and any non-standard ports, such as 8080. If CORS isn't set, you will see CORS errors in the console log for web service calls. +Domains added to CORS allowlist can use cross-site scripting, that is, calling web service endpoints (including login) from a web application. Command-line applications and tools, such as CURL, are not impacted by this setting. The values are the list of domains and any non-standard ports, such as 8080. You can omit the protocol for `https` domains, but you must include it for `localhost` and other non-HTTPS domains. If CORS isn't set, you will see CORS errors in the console log for web service calls. -You will need to add the CORS setting either in your system or the trial instance. Add `localhost:8000` if that's your URL. Note that `127.0.0.1` is not the same, so if you are using an IP, set that instead. +You will need to add the CORS setting either in your system or the trial instance. Add `\http://localhost:8000` if that's your URL. Note that `127.0.0.1` is not the same, so if you are using an IP, set that instead. For more details, see the link:https://developers.thoughtspot.com/docs/security-settings[security setting] documentation, which also includes constraints on values for the above settings. @@ -75,7 +74,8 @@ The following table lists the types of authentication, the associated link:https | SSO with iframe redirect | AuthType.EmbeddedSSO | SSO or OIDC when iframe redirect is supported by the IdP. | No | link:https://en.wikipedia.org/wiki/SAML_2.0[SAML] | AuthType.SAMLRedirect | SSO with SAML | Yes | link:https://openid.net/connect/[OIDC] | AuthType.OIDCRedirect | SSO with Open ID Connect | No -| Trusted Authentication | AuthType.AuthServer | ThoughtSpot token-based approach | Yes +| Trusted Authentication (cookie-based) | AuthType.TrustedAuthToken | ThoughtSpot token-based approach that creates a session cookie | Yes +| Trusted Authentication (cookieless) | AuthType.TrustedAuthTokenCookieless | ThoughtSpot token-based approach that doesn't depend on third-party cookies. Recommended for production. | Yes |=== Each of these approaches is explored in detail in the following sections. @@ -103,7 +103,7 @@ SAML configuration requires Administrator privileges in ThoughtSpot. It shows up [.bordered] image::images/tutorials/tse-fundamentals/lesson-03-saml-configuration.png[SAML configuration dialog] -Once you have the SAML federation set up for ThoughtSpot, you also have to enable the SAML redirect for the authentication. This is set from the *Developer | Security Settings*. If this value is not set, then you will get errors trying to redirect back to your application. +Once you have the SAML federation set up for ThoughtSpot, you also have to enable the SAML redirect for the authentication. This is set from the *Develop* > *Customizations* > *Security settings* page. If this value is not set, then you will get errors trying to redirect back to your application. [.widthAuto] [.bordered] @@ -126,7 +126,7 @@ Trusted authentication is a ThoughtSpot specific approach to authentication that [.bordered] image:images/tutorials/tse-fundamentals/lesson-03-saml-trusted-auth-config.png[Trusted auth configuration] -To enable trusted authentication you have to navigate to the Developer | Security Settings page and enable it via the toggle switch. Note that only an administrator can make this change. Once enabled, you will get a cluster wide key that you can copy and use in API calls. KEEP THIS KEY PRIVATE! It is a cluster wide key that allows you to create sessions on behalf of any user. +To enable trusted authentication you have to navigate to the *Develop* > *Customizations* > *Security settings* page and enable it via the toggle switch. Note that only an administrator can make this change. Once enabled, you will get a cluster wide key that you can copy and use in API calls. KEEP THIS KEY PRIVATE! It is a cluster wide key that allows you to create sessions on behalf of any user. NOTE: On instances with Orgs enabled, you can also enable trusted authentication at the org level in addition to the instance level. The token created can only be used to log into the given org. diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc index 041c3d018..2d1ad8307 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc @@ -21,7 +21,7 @@ The examples here use link:https://code.visualstudio.com/[Visual Studio Code, wi == Make a copy of the code -You can work directly in the code you downloaded from GitHub, but it's usually better to create a copy, so you can always revert if needed The path you choose is entirely up to you. +You can work directly in the code you downloaded from GitHub, but it's usually better to create a copy, so you can always revert if needed. The path you choose is entirely up to you. Whichever approach you take, you should end up with a folder with the files shown below. diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc index 55af07228..7b57a2eda 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc @@ -57,7 +57,7 @@ const onSearch = () => { Refresh the application and click on the Search link. You should see a message in the console window of the developer tools. If not, check for errors. -You can also reference the example code (in the `src` folder). +You can also reference the example code (in the `src-updates/05-src` folder in the link:https://github.com/thoughtspot/tse-fundamentals-step-by-step[tse-fundamentals-step-by-step repository, window=_blank]). [.widthAuto] [.bordered] @@ -125,13 +125,13 @@ image:images/tutorials/tse-fundamentals/lesson-05-data-source-added.png[data sou 2. Click on **Collapse data panel** to collapse the data panel in the embed. 3. Click on **Add search tokens**. This adds code for search options. -The `searchTokenString` uses a TML query. +The `searchTokenString` contains the search tokens (the search query) to run. Here's an example: [source,javascript] ---- searchOptions: { - searchTokenString: '[sales] by [item type]', // Example TML query + searchTokenString: '[sales] [item type]', // Example search query executeSearch: true, }, ---- @@ -159,8 +159,7 @@ Every embed component requires two steps: 2. Render the object (with optional event listeners). Copy the generated code from the Playground into the `onSearch` function after the `console.log` statement. -Be sure to change the ID from `#your-own-div` to `#embed` to match the `index.html` file. Note that all IDs will -be unique to your environment. +Be sure to change the ID from `#your-own-div` to `#embed` to match the `index.html` file. Note that all IDs will be unique to your environment. [source,javascript] ---- @@ -170,7 +169,7 @@ const embed = new SearchEmbed("#embed", { disabledActions: [Action.Download], disabledActionReason: "Permission required", hiddenActions: [Action.Share], - dataSources: ["4d98d3f5-5c6a-44eb-82fb-d529ca20e31f"], // Your data source ID + dataSource: "4d98d3f5-5c6a-44eb-82fb-d529ca20e31f", // Your data source ID searchOptions: { searchTokenString: '[sales] [item type]', executeSearch: true, @@ -193,7 +192,7 @@ const onSearch = () => { disabledActions: [Action.Download], disabledActionReason: "Permission required", hiddenActions: [Action.Share], - dataSources: ["4d98d3f5-5c6a-44eb-82fb-d529ca20e31f"], // Your data source ID + dataSource: "4d98d3f5-5c6a-44eb-82fb-d529ca20e31f", // Your data source ID searchOptions: { searchTokenString: "[sales] [item type]", executeSearch: true, @@ -229,7 +228,7 @@ However, with caching disabled during development, re-downloading will still occ 6. Add a `render()` call. 7. Test the code. -If you run into issues, you can reference the code in the `src` folder. +If you run into issues, you can reference the code in the `src-updates/05-src` folder in the link:https://github.com/thoughtspot/tse-fundamentals-step-by-step[tse-fundamentals-step-by-step repository, window=_blank]. == Files changed diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc index 25a1a71e0..016f68b18 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc @@ -3,138 +3,12 @@ :page-title: Lesson 6 - Embed Natural Language Search :page-pageid: tse-fundamentals__lesson-06 -:page-description: This lesson demonstrates embedding a Natural Language Search component into the application using the same pattern as earlier lessons. +:page-description: ThoughtSpot has deprecated embedding Natural Language Search with SageEmbed. For AI Search and conversational analytics, embed Spotter. -Now that you've embedded a search, you'll notice that the rest of the embedding follows the same basic pattern: - -* Create the component in the Playground. -* Add the component to your code and render it. - -In this lesson, we'll embed Natural Language Search components into the application. - -== Pre-conditions - -You should have already completed all the lessons through xref:tse-fundamentals-lesson-05.adoc[lesson 05]. - -== Add a nav link and function for the natural language search - -First, add a nav link for the natural language embed. In the `index.html` file, add a new `
  • ` for the natural language search page. We'll also add a pipe character `|` as a separator in the menu. Your code should look like this: - -[source,html] ----- - ----- - -Now run the application to verify everything is working. You should see the Search and Natural Language links in the menu. - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-new-sage-link.png[Nav bar with sage link added] - -== Add a listener for the search link - -In `tse.js`, add the following line of code to register a listener for the click event. When clicked, it will call the `onSage` function. Place this after the listener added in the previous lesson. The event listener section should now have two listeners. - -[source,javascript] ----- -document.getElementById("search-link").addEventListener("click", onSearch); -document.getElementById("sage-link").addEventListener("click", onSage); ----- - -Next, add the `onSage` function. Initially, this will just log a message to the console to confirm it's being triggered. - -[source,javascript] ----- -const onSage = () => { - console.log('using natural language search'); -} ----- - -Refresh the application and click the Natural Language link. You should see the console log message in the developer tools. If not, check for errors. - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-console-message.png[Console message showing onSage was called] - -== Generate a natural language search to embed - -If you're not already in the Visual SDK playground, navigate there and select **Natural Language Search** from the dropdown menu. You should see an empty page with the Natural Language Search bar as shown here: - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-empty-sage-embed.png[empty sage search embed in the playground] - -Let's review the SageEmbed-specific settings and configure the embed. - -* The `Select data source` dropdown is similar to what we used for the Search embed. It will display any Models enabled for natural language search. Select one from the dropdown to update the code with the data source's GUID. - -Unlike the Search embed, you can only have one data source for natural language search, and a data source is always required for natural language search, though it can be user-provided. - -Now, set some additional options: - -* **Disable changing model**: Prevents the user from changing the pre-selected data source. -* **Hide Sage Answer header**: Hides the "AI answer" header in the results. -* **Add search query**: Predefines a text query to run automatically, similar to the search embed. - -For this exercise, select the options **Disable changing model**, **Hide Sage Answer header**, and **Add search query**. Enter a search query, then press **Run**. You should see a result like this: - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-sage-embed-playground.png[complete sage embed in the playground] - -== Embed the natural language search into the application - -Now that we've created the natural language embed component using the playground, let's add it to the `onSage` function. Remember to update the `div` ID from `#your-own-div` to `#embed` to match the `index.html` file. Finally, add a call to `render()`. - -Here is the resulting function with comments removed and the DIV ID updated: - -[source,javascript] ----- -const onSage = () => { - const embed = new SageEmbed("#embed", { - frameParams: {}, - disableWorksheetChange: true, - hideSageAnswerHeader: true, - dataSource: "4d98d3f5-5c6a-44eb-82fb-d529ca20e31f", // Your data source ID - searchOptions: { - searchQuery: "top selling items", - executeSearch: true, - }, - }); - - embed.render(); -}; ----- - -== Test natural language search embed - -The final step is to test the Sage embed. Refresh the application (with cache disabled), then click the Sage link. You should see something like this: - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-sage-embed-results.png[final sage embed in the application] - -== Activities - -1. Add the nav link and handler to your code. -2. Import `SageEmbed`. -3. Use the playground to create a natural language search embed component. -4. Copy the search embed component from the playground to your code and modify the DIV ID. -5. Add a `render()` call. -6. Test the code. - -If you run into issues, you can reference the code in the `src` folder. - -== Files changed - -* index.html -* tse.js +[IMPORTANT] +==== +ThoughtSpot has deprecated embedding Natural Language Search with `SageEmbed`. To embed AI Search and conversational analytics, ThoughtSpot strongly recommends using Spotter. For more information, see the xref:embed-spotter.adoc[Spotter embed] and xref:customize-spotter-embed.adoc[customization] documentation. +==== ++++
    diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc index 42cf6ea95..8ef70894c 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc @@ -2,7 +2,7 @@ :toc!: :page-title: Embed a Liveboard -:page-pageid: tse-fundamentals__lesson-07 +:page-pageid: tse-fundamentals__lesson-07 :page-description: In this lesson we'll embed a full Liveboard using the `LiveboardEmbed` component. == Pre-conditions @@ -19,9 +19,7 @@ First, we want to add another nav link to the nav bar. In the `index.html` file
    ---- @@ -34,7 +32,7 @@ image::images/tutorials/tse-fundamentals/lesson-07-new-liveboard-link.png[Nav ba == Add a listener for the Liveboard links -In `tse.js` add the following lines of code. It adds a listener for the click events, so when the user clicks, it will call the `onLiveboard` function. Add the following line after the one we added for the `sage-link`. +In `tse.js` add the following lines of code. It adds a listener for the click events, so when the user clicks, it will call the `onLiveboard` function. Add the following line after the one we added for the `search-link`. [source,javascript] ---- @@ -99,7 +97,7 @@ image:images/tutorials/tse-fundamentals/lesson-07-liveboard-selected.png[Liveboa == Embed the Liveboard into the application -As with Search and Natural Language Search embedding, we'll copy the code from the playground into the application. +As with Search embedding, we'll copy the code from the playground into the application. . Copy the component creation section. Your code will show as follows. . Paste this code into the `onLiveboard` function. @@ -148,7 +146,7 @@ image:images/tutorials/tse-fundamentals/lesson-07-liveboard-embed-results.png[Li 4. Copy and paste the generated code (adding `render()`) into your application 5. Test the code -If you run into problems, you can look at the code in the `src` folder in this section. +If you run into problems, you can look at the code in the `src-updates/07-src` folder in the link:https://github.com/thoughtspot/tse-fundamentals-step-by-step[tse-fundamentals-step-by-step repository, window=_blank]. == Files changed diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc index 64d207308..102131c6f 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc @@ -1,7 +1,7 @@ = Embed a Liveboard visualization :toc!: -:page-title: Embed a Liveboard Visualization +:page-title: Embed a Liveboard Visualization :page-pageid: tse-fundamentals__lesson-08 :page-description: In this lesson we'll embed a single visualization from a Liveboard using the `LiveboardEmbed` component. @@ -20,8 +20,6 @@ In the `index.html` file add a new `
  • ` for the separator and Liveboard visual