diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0b682e3ed..c4b6b0302 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1,1849 +1,248 @@ -= Visual Embed changelog += Visual Embed SDK changelog :toc: true -:toclevels: 1 +:toclevels: 2 -:page-title: Changelog -:page-pageid: embed-sdk-changelog -:page-description: Changes to the SDK and APIs +:page-title: Visual Embed SDK changelog +:page-pageid: api-changelog +:page-description: Changelog for the Visual Embed SDK -This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +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.49.x, June 2026 +== Version 1.50.x, July 2026 + +// SOURCE: SCAL-311987, SCAL-290720, SCAL-309464, SCAL-303724, SCAL-309605 [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# 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`: control legend visibility, position, and color palette of charts. -* `dataLabel` attribute for data labels and per-column label filters. -* `display` attributes for such as regression line overlay and grid line visibility in charts and table themes and content density in tables. -* `axis` property for axis name and label visibility and fixed y-axis range. -* `columns` property for per-column series color and conditional formatting rules. -* `updateMaskPaths` property for partial updates -* `columns` property for column visibility, text wrapping, conditional formatting, and column summary in tables. -For more information, see xref:viz-overrides.adoc[Visualization overrides]. - -//|[tag greenBackground]#NEW FEATURE# a| -//[discrete] -//===== New charts library - -//The SDK introduces the `newChartsLibrary` parameter to enable the new Muze charting library in Liveboard and full application embedding. - -|[tag greenBackground]#NEW FEATURE# a| [discrete] -===== Liveboard browser cache refresh - -The SDK introduces the following event IDs and action ID to support programmatic and user-triggered browser cache refresh for the Liveboard ChartViz containers. These APIs require `enableLiveboardDataCache` to be enabled in your embed configuration. - -Events:: - -* `EmbedEvent.RefreshLiveboardBrowserCache` + -Emitted when a user clicks the *Refresh* button in the Liveboard header to clear the browser cache. +==== SpotterViz branding and customization [.version-badge.new]#New# -* `HostEvent.RefreshLiveboardBrowserCache` + -Allows the host application to programmatically trigger a browser cache refresh for all visualization containers on the embedded Liveboard. +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. -New action ID:: - -* `Action.RefreshLiveboardBrowserCache` + -Action ID to control the visibility of the *Refresh* button that clears the browser cache and fetches new data for Liveboard ChartViz containers. - -|[tag greenBackground]#NEW FEATURE# a| -[discrete] -===== Spotter file upload -The SDK introduces the following configuration parameters in `SpotterChatViewConfig` to enable and control file uploads in the embedded Spotter chat interface. +Using `SpotterVizConfig`, you can now: -* `spotterFileUploadEnabled` + -When set to `true`, enables the file upload feature in the Spotter chat panel. +* Set a custom brand name and headline for the SpotterViz panel. +* Add a custom description and input chat placeholder text. +* Show, hide, or replace the default starter prompts with +application-specific suggestions using `SpotterVizStarterPrompt`. -* `spotterFileUploadFileTypes` + -Restricts the file types allowed for upload in the Spotter chat panel. Accepts a `SpotterFileUploadFileTypes` object. -|==== +The `spotterViz` property is available on both `AppViewConfig` and +`LiveboardViewConfig`. +For more information, see xref:embed-spotter-viz.adoc[Customizing SpotterViz]. +--- -== Version 1.48.x, May 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# 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;; +==== New EmbedEvents for SpotterViz [.version-badge.new]#New# -* `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. +The SDK introduces two new event identifiers for monitoring SpotterViz +panel activity in embedded Liveboards: -Liveboard download actions:: +* `EmbedEvent.SpotterVizMount` + +Emitted when the SpotterViz panel mounts in embed mode. +* `EmbedEvent.SpotterVizPromptSubmit` + +Emitted when a user submits a prompt in the SpotterViz panel. -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 FEATURE# 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. +===== SpotterViz embed customization -|[tag greenBackground]#NEW FEATURE# a| +// SOURCE: SCAL-311987, SCAL-311988 -[discrete] -===== Event handling -Note the following changes: +The SDK introduces the following customization APIs for the SpotterViz component embedded in Liveboards. -EmbedEvent:: +`SpotterVizConfig` interface:: +A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` via the `spotterViz` property. It exposes the following options: ++ +* `brandName` — Custom brand name displayed in the SpotterViz panel header. +* `headline` — Custom headline text for the SpotterViz panel. +* `description` — Custom description text shown below the headline. +* `inputPlaceholder` — Custom placeholder text for the Spotter chat input. +* `starterPrompts` — Array of `SpotterVizStarterPrompt` objects to replace default prompt suggestions. ++ +// TODO: verify with engineering — confirm full list of SpotterVizConfig properties and their types -* `EmbedEvent.Subscribed` + -The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. -* `EmbedEvent.Error` + -The `EmbedEvent.Error` now fires on HostEvent payload validation failures. -* `EmbedEvent.ChangePersonalizedView` + -Emits when a user selects a different Personalized View or resets to default. +CSS variables:: +SpotterViz exposes CSS custom properties to allow visual styling of the tile. Apply these variables using the `customCSS` configuration in your `LiveboardEmbed` initialization. ++ +// TODO: verify with engineering — provide the authoritative list of CSS variable names and their defaults (for example, --ts-spotterviz-background, --ts-spotterviz-text-color) -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`. +Embed events:: -* `HostEvent.SelectPersonalizedView` + -Triggers the selection of a specific Personalized View and resets the default view on a Liveboard. +* `EmbedEvent.SpotterVizMount` + +Emitted when the SpotterViz panel mounts in embed mode. -⚠️Deprecated events and action IDs️:: -The following events are deprecated and replaced with new event IDs. +* `EmbedEvent.SpotterVizPromptSubmit` + +Emitted when a user submits a prompt in the SpotterViz panel. -* `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`. +// TODO: verify with engineering — confirm whether additional EmbedEvents are introduced for Insight Tile load and error states +Actions:: +// TODO: verify with engineering — confirm Action enum names for SpotterViz visibility control (for example, Action.InsightTileRetrigger) -|==== +For more information, see xref:embed-spotterViz.adoc[Customizing SpotterViz]. -== Version 1.47.x, April 2026 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat history sidebar customization** +[discrete] +==== SpotterViz branding and customization [.version-badge.new]#New# -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: +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. -* `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. +Using `SpotterVizConfig`, you can now: -* `spotterSidebarTitle` + -Allows adding custom title text for the sidebar header. +* Set a custom brand name and headline for the SpotterViz panel. +* Add a custom description and input chat placeholder text. +* Show, hide, or replace the default starter prompts with +application-specific suggestions using `SpotterVizStarterPrompt`. -* `spotterSidebarDefaultExpanded` + -Sets the default state of the sidebar to expanded or collapsed view. +The `spotterViz` property is available on both `AppViewConfig` and +`LiveboardViewConfig`. -* `spotterChatRenameLabel` + -Allows setting a custom label for the **Rename** action in the conversation edit menu. +For more information, see xref:embed-spotter-viz.adoc[Customizing SpotterViz]. -* `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. +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Insight Tiles — runtime filter and parameter support -* `spotterBestPracticesLabel` + -Allows customizing the label for the best practices button in the sidebar footer. +// SOURCE: SCAL-309605 -* `spotterDocumentationUrl` + -The best practices documentation link shown in the sidebar footer. You can customize the link by specifying the full URL. +Runtime filters and parameters passed to `LiveboardEmbed` are now forwarded to Insight Tiles (AI tiles). When a runtime filter is applied, the Insight Tile regenerates its AI-generated insights using the filtered data context. -* `spotterConversationsBatchSize` + -Sets the number of conversations to fetch per batch when loading conversation history. Default is `30`. +No SDK configuration changes are required. Runtime filters already passed via `runtimeFilters` in `LiveboardViewConfig` are automatically applied to Insight Tiles on the same Liveboard. -* `spotterNewChatButtonTitle` + -Allows customizing the title text for the **New chat** button in the sidebar. +For more information, see xref:runtime-filter.adoc[Runtime filters]. -|[tag redBackground]#DEPRECATED# a| **Standalone `enablePastConversationsSidebar` attribute in Spotter embed** +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Saved Chat host events -The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` and `AppViewConfig` is deprecated from SDK 1.47.0 and ThoughtSpot 26.4.0.cl. +// SOURCE: SCAL-290720, SCAL-313991 -Use `enablePastConversationsSidebar` in the `spotterSidebarConfig` instead. When both are defined, the property in the `spotterSidebarConfig` object takes precedence. +The SDK introduces the following host events for managing saved Spotter conversations from the host application. These events complement the new REST API endpoints for saved conversations. -[source,javascript] +* `HostEvent.LoadChat` + +Loads a specific saved conversation by ID into the embedded Spotter interface. + ++ +[source,JavaScript] ---- -// Deprecated -enablePastConversationsSidebar: false, - -// Recommended -spotterSidebarConfig: { - enablePastConversationsSidebar: true, - //... other config properties -} +spotterEmbed.trigger(HostEvent.LoadChat, { chatId: '' }); ---- -|[tag greenBackground]#NEW FEATURE# a| **Spotter chat UI branding** - -The SDK introduces the `SpotterChatViewConfig` interface for customizing branding in Spotter tool response cards. You can pass these parameters as the `spotterChatConfig` object properties in `SpotterEmbed`, `AppEmbed`, or `LiveboardEmbed` where Spotter interface is used. - -* `hideToolResponseCardBranding` + -When set to `true`, hides the ThoughtSpot logo and icon in tool response cards. The branding label prefix is controlled separately via `toolResponseCardBrandingLabel`. Default value is `false`. - -* `toolResponseCardBrandingLabel` + -Custom label to replace the `ThoughtSpot` prefix in tool response cards. Set to an empty string (`''`) to hide the prefix entirely. - -[NOTE] -==== -These settings do not affect the external MCP tool branding. -==== - -|[tag greenBackground]#NEW FEATURE# a|**Liveboard embed enhancements** - -Personalized Liveboard view:: - -The `personalizedViewId` property allows embedding a saved personalized view of a Liveboard. A personalized view is a saved configuration that includes specific filter selections and changes applied by a user. To embed a personalized view of Liveboard, specify the GUID of the saved personalized view to load along with `liveboardId`. - -Centralized Liveboard filter setting:: - -When set to `true`, the `isCentralizedLiveboardFilterUXEnabled` enables displaying a unified modal to manage and update multiple filters at once, replacing the older individual filter interactions. This feature is disabled by default on ThoughtSpot Embedded instances. - -|[tag greenBackground]#NEW FEATURE# a|**Option to include current period in rolling date filters** - -If the current period inclusion in rolling date filters feature is enabled on your instance, the rolling date filters options such as **Last ** and **Next ** for the Liveboards and Answers in the embed view will allow you to include current period. For example, when you define a date range such as "Last 2 months", the date filter interface displays the **Include this month** checkbox. -To disable this feature, use the `isThisPeriodInDateFiltersEnabled` setting. To hide, show, or disable this option in the embed view, use the action ID, `Action.IncludeCurrentPeriod`. -|==== - - -== Version 1.46.x, March 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Host events with page context framework** - -The Visual Embed SDK introduces the HostEvent V2 framework for improved handling and execution of host events in embedded ThoughtSpot experiences with multi-layer UI interactions. The v2 framework supports the page context feature, which tracks the top-most active layer in the user's current context. Developers can use this feature to route events based on the user's current context or set a specific target context for precise and predictable handling of host events. - -* To enable this feature, set `useHostEventsV2` to `true`. -* To retrieve the current context, use `getCurrentContext()`. -* To set a target context for a host event, use xref:ContextType.adoc[ContextType]. - -For more information, refer to the xref:events-context-aware-routing.adoc[Host events documentation]. - -|[tag redBackground]#DEPRECATED# a| **dataPanelV2** - -The `dataPanelV2` parameter is deprecated and can no longer be used to switch between the classic and new data panel experience. By default, the new data panel v2 experience is enabled on all ThoughtSpot embedded instances. - -|[tag greenBackground]#NEW FEATURE# a| **Spotter experience** -The SDK includes the following parameters, action IDs, and events to customize the Spotter embed experience. - -Chat history sidebar customization:: - -//* `SpotterSidebarViewConfig` interface with configuration parameters for customizing the visibility and appearance of the chat history sidebar. -//* `spotterSidebarConfig` properties for customizing the appearance and available options in the chat history sidebar. -* Action IDs for customizing the visibility and status of actions in the embedded Spotter interface: -** `Action.DataModelInstructions` for the data model instructions icon. -** `Action.SpotterSidebarHeader` for the chat history sidebar header -** `Action.SpotterSidebarFooter` for the chat history sidebar footer -** `Action.SpotterSidebarToggle` for the chat history toggle that expands or collapses the sidebar. -** `Action.SpotterNewChat` for the new chat icon in the chat history sidebar. -** `Action.SpotterPastChatBanner` for the banner in the chat history sidebar. -** `Action.SpotterChatMenu` for the chat menu component in the chat history sidebar. -** `Action.SpotterChatRename` for **Rename** action in the chat menu of a saved chat. -** `Action.SpotterChatDelete` for **Delete** action in the chat menu of a saved chat. -//** `Action.SpotterDocs` for best practices documentation icon in the chat history sidebar. - -Events:: -* `HostEvent.DataModelInstructions` + -Opens the Data Model instructions modal. -* `EmbedEvent.DataModelInstructions` + -Is emitted when a user clicks the Data Model instructions icon in the Spotter interface. -* `EmbedEvent.SpotterConversationRenamed` + -Is emitted when a user renames a saved chat. -* `EmbedEvent.SpotterConversationDeleted` + -Is emitted when a saved chat is deleted. -* `EmbedEvent.SpotterConversationSelected` + -Is emitted when a saved chat is selected in the chat history sidebar. - -|[tag greenBackground]#NEW FEATURE# | `enableLinkOverridesV2` + - -Use this configuration setting to override ThoughtSpot URLs on hover or when opening in a new tab. This is recommended over the earlier `linkOverride` flag for a better user experience. - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** - -* The `isLiveboardXLSXCSVDownloadEnabled` attribute adds XLSX and CSV to the available Liveboard download formats. -* The `isGranularXLSXCSVSchedulesEnabled` attribute allows you to include the entire Liveboard, specific visualizations, or only tables and pivot tables in the XLSX and CSV schedules. -|==== - -== Version 1.45.0, February 2026 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Spotter enhancements** - -You can now embed the Spotter 3 experience in your application and use features such as Auto mode for automatic data model selection, chat history, and a new chat prompt interface. - -* To enable the new chat prompt interface, set `updatedSpotterChatPrompt` to `true`. -* To use Auto mode, set the `worksheetId` to `auto_mode`. -* To enable Chat history, set `enablePastConversationsSidebar` to `true`. - -For more information, see xref:embed-spotter.adoc[Embedding Spotter] and xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Features available with Spotter 3 experience]. - -Events:: - -* `EmbedEvent.AddToCoaching` for the *Add to Coaching* workflow in a Spotter conversation session -* `HostEvent.AddToCoaching` to trigger the *Add to Coaching* action in a Spotter conversation session. -* `HostEvent.StartNewSpotterConversation` to trigger the action to start a new chat session with Spotter. - -[NOTE] -==== -On Spotter embed deployments running version 26.2.0.cl or later, the *Add to Coaching* feature is enabled by default. To disable or hide the *Add to Coaching* button, use the xref:Action.adoc#_inconversationtraining[InConversationTraining] action ID. -==== - -|[tag greenBackground]#NEW FEATURE# a| **Liveboard experience enhancements** + - -Styling and grouping:: - -* The `isLiveboardStylingAndGrouping` attribute, used to enable the Liveboard styling and grouping feature, is now replaced with `isLiveboardMasterpiecesEnabled`. While your existing configuration with the deprecated `isLiveboardStylingAndGrouping` attribute continues to work, we recommend switching to the new configuration setting. -* The following action IDs are now available to show, disable, or hide the grouping menu actions on a Liveboard: -** `Action.MoveToGroup` for the **Move to Group** menu action. -** `Action.MoveOutOfGroup` for the **Move out of Group** menu action. -** `Action.CreateGroup` for the *Create Group* menu action. -** `Action.UngroupLiveboardGroup` for the **Ungroup Liveboard Group** menu action. - -Filter chip masking:: -The `showMaskedFilterChip` boolean parameter is now available to control the visibility of masked filter chips on a Liveboard. When set to `true`, if a Liveboard is shared with a user who has restricted access due to column-level security, the filter chip corresponding to those inaccessible columns will be displayed as masked to that user. When set to `false`, the filter chip for inaccessible columns will not be visible to the user. -+ -For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards]. +* `HostEvent.DeleteChat` + +Deletes a specific saved conversation by ID. The embed emits `EmbedEvent.SpotterConversationDeleted` after deletion. + + -The `showMaskedFilterChip` setting is also available in full application embedding. - -|[tag greenBackground]#NEW FEATURE# a| **Publishing objects** - -The following action IDs are available for the data publishing menu actions in the *Data workspace* page: - -* `Action.Publish` for *Publish* -* `Action.ManagePublishing` for *Manage publishing* -* `Action.Unpublish` for *Unpublish* -* `Action.Parameterize` for *Parameterize* -|[tag greenBackground]#NEW FEATURE# a| **Error handling improvements** - -To handle errors in the embedding workflows, the SDK includes the following features: - -* `ErrorDetailsTypes` enum for categorizing error types, such as `API`, `VALIDATION_ERROR`, and `NETWORK`. -* `EmbedErrorCodes` enum with specific error codes for programmatic error handling. -* `EmbedErrorDetailsEvent` interface for structured error event handling. - -For more information, see link:https://developers.thoughtspot.com/docs/Enumeration_EmbedErrorCodes[EmbedErrorCodes] and link:https://developers.thoughtspot.com/docs/Enumeration_ErrorDetailsTypes[ErrorDetailsTypes]. -|==== - -== Version 1.44.x, January 2026 - -[width="100%" cols="1,4"] -|==== - -|[tag redBackground]#DEPRECATED# | **Use `minimumHeight` instead of `defaultHeight`** + - -The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. -To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. - -|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + -The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: - -//* `enableApiIntercept` + -//When set to true, enables the feature on your ThoughtSpot embed. -* `interceptUrls` + -Allows configuring which API calls to intercept. -* `interceptTimeout` + -Sets the timeout duration for handling interception. -* `isOnBeforeGetVizDataInterceptEnabled` + -When set to true, it enables use of `EmbedEvent.OnBeforeGetVizDataIntercept` to emit and intercept search execution calls initiated by users and implement custom logic or workflows to allow or restrict search execution. -* `EmbedEvent.ApiIntercept` + -Emits when an API call matching the conditions defined in `interceptUrls` is detected. - -For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. -|==== - - -== Version 1.43.0, November 2025 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* - -The following enumerations are available for code-based custom actions: - -* `CustomActionTarget` + -To define the target object for the custom action, such as on a Liveboard, visualization, Answer, or in Spotter. -* `CustomActionsPosition` + -To define the position of the custom action in the target object, such as primary menu, **More** options menu image:./images/icon-more-10px.png[the more options menu], or the contextual menu. -|[tag greenBackground]#NEW FEATURE# | *Attribute to set Parameter chip visibility during overrides* + -The `HostEvent.UpdateParameters` event now supports configuring the `isVisibleToUser` attribute to show or hide the Parameter chips after an override. For more information, see xref:runtime-parameters.adoc#_show_or_hide_parameter_chips_in_embedded_sessions[Show or hide Parameter chips in embedded sessions]. -|==== - -== Version 1.42.0, October 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* - -The Visual Embed SDK now supports runtime overrides in Spotter embed. - -* To apply runtime filters, use the `runtimeFilters` object -* To apply runtime Parameters, use the `runtimeParameters` object. - -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + -To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. - -The SDK also provides the following action IDs: - -* `Action.PngScreenshotInEmail` + -Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. -* `Action.RemoveAttachment` + -Allows the user to remove an attachment from the email configuration in the schedule email dialog. -|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* - -Action IDs:: -The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: - -* `Action.SpotterWarningsBanner` + -Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. -* `Action.SpotterWarningsOnTokens` + -Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. -* `Action.SpotterTokenQuickEdit` + -Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. -|==== - -== Version 1.41.0, September 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* - -The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. - -For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* - -The following event handlers are now available for Spotter embed: - -* `EmbedEvent.SpotterInit` + -Fires when Spotter embed component rendering is initialized. -* `EmbedEvent.QueryChanged` + -Fires when the Spotter query is updated by the user. -* `HostEvent.AskSpotter` + -Triggers *Ask Spotter* action for visualizations. -* `HostEvent.GetParameters` + -Triggers the action to fetch runtime Parameters applied on a visualization. -* `HostEvent.UpdateParameters` + -Triggers the action to update runtime Parameters for a Spotter-generated Answer. -* `HostEvent.GetTML` + -Triggers the action to get TML representation of a Spotter-generated Answer. - -For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* - -You can now use the following host events in Spotter Agent embedding: - -- `HostEvent.DownloadAsCsv` + -Triggers the action to download a Spotter-generated Answer in CSV format. -- `HostEvent.DownloadAsPng` + -Triggers the action to download a Spotter-generated Answer in PNG format. -- `HostEvent.DownloadAsXlsx` + -Triggers the action to download a Spotter-generated Answer in XLSX format. -- `HostEvent.DownloadAsPdf` + -Triggers the action to download the PDF version of a Spotter-generated Answer. -- `HostEvent.Pin` + -Triggers the action to add a Spotter-generated Answer to a Liveboard. -- `HostEvent.Save` + -Triggers the *Save* action for a Spotter-generated Answer. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* - -You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. - -You can also set the margin property for lazy loading to define when the visualization should load. - -For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + - -You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature is disabled by default on ThoughtSpot instances and is available for Early Access. When it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. - -When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. -|==== - -== Version 1.40.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Fullscreen presentation mode controls for embedded Liveboards and visualizations* + -Developers can now control whether a visualization or Liveboard can be presented in full screen mode using the `disableFullscreenPresentation` attribute. By default, the full screen mode is disabled on embedded Liveboards and visualizations. -|[tag greenBackground]#NEW FEATURE# a| *PDF download settings* + -Developers can now control the display of *Include cover page* and *Include filter page(s)* options on the Download PDF dialog for Liveboards. The *Include cover page* and *Include filter page(s)* options are disabled by default on ThoughtSpot instances. When this feature is enabled, developers can use the `coverAndFilterOptionInPDF` attribute to show or hide these options for the Liveboard users in their embedding app. - -|[tag greenBackground]#NEW FEATURE# a| *Parameter for overriding a default primary action* + - -If Spotter is enabled on your instance, the *Spotter* button appears by default as the primary action on embedded Liveboard charts; if Spotter is not enabled, the *Explore* button is set as the primary action. If you want to replace the primary action with a different action, you can now use the `primaryAction` attribute. - -For more information, see xref:embed-actions.adoc#_override_default_primary_actions[Override default primary action]. - -|[tag greenBackground]#NEW FEATURE# a| *Full application embed experience enhancements* + - -The SDK now includes the `hideObjectSearch` property, which allows developers to hide the object search button in the navigation bar when embedding the full application. - -|[tag greenBackground]#NEW FEATURE# a| *Host events* + - -In this version, the SDK introduces the following host event handlers: - -- `HostEvent.ExitPresentMode` + -Triggers the exit action that allows users to exit the Liveboard or visualization present mode. -- `HostEvent.SpotterSearch` + -Triggers a search operation for the specified query string in Spotter embed. -- `HostEvent.PreviewSpotterData` + -Triggers the *Preview data* action that shows the data used for Spotter conversations. -- `HostEvent.ResetSpotterConversation` + -Triggers the *Reset* action to reset a Spotter conversation. -- `HostEvent.EditLastPrompt` + -Triggers the edit prompt action. -- `HostEvent.DeleteLastPrompt` + -Triggers the delete prompt action. - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -You can now use the following host events in Spotter embed: - -- `HostEvent.DownloadAsCsv` -- `HostEvent.DownloadAsPng` -- `HostEvent.DownloadAsXlsx` -- `HostEvent.Edit` -//- `HostEvent.GetParameters` -//- `HostEvent.GetTML` -- `HostEvent.MakeACopy` -- `HostEvent.Pin` -- `HostEvent.Save` - -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| *Lazy loading with full height* +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.DeleteChat, { chatId: '' }); +---- -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. +* `HostEvent.RenameChat` + +Renames a specific saved conversation by ID. + ++ +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.RenameChat, { chatId: '', title: 'New title' }); +---- [NOTE] ==== -To use these attributes effectively in embedded applications, your ThoughtSpot instance must be upgraded to version 10.12.0.cl or later. +Users can only load, delete, or rename their own conversations. These operations require the user to have Spotter access and the *Save chat* feature enabled on the cluster. ==== -|==== +// TODO: verify with engineering — confirm whether a SpotterConversationRenamed EmbedEvent is emitted after a successful rename -== Version 1.39.0, July 2025 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + -The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: +For more information, see xref:saved-conversations-api.adoc[Saved Chat public APIs]. -* `ConversationEmbed` + -Replaced with `SpotterEmbed` -* `ConversationViewConfig` + -Replaced with `SpotterEmbedViewConfig` -* `BodylessConversation` + -Replaced with `SpotterAgentEmbed` -* `BodylessConversationViewConfig` + -Replaced with `SpotterAgentEmbedViewConfig` +|[tag redBackground]#BREAKING CHANGE# a| +[discrete] +===== Removal of `EmbedEvent.SpotterData` -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]. +// SOURCE: SCAL-309464 -|[tag greenBackground]#NEW FEATURE# a| *Action ID for Spotter in-conversation training* + -For ThoughtSpot instances that have the new Spotter in-conversation training workflow enabled, the SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to Coaching* button on Answers generated from Spotter prompts. +`EmbedEvent.SpotterData` has been removed from the Visual Embed SDK. This constant was a legacy event identifier that was never emitted in Spotter 3. It was superseded by `EmbedEvent.PreviewSpotterData` in the Spotter 3 release (SDK v1.28.x) and the old constant was not removed at that time. -[NOTE] -The *Add to Coaching* feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. - -|[tag greenBackground]#NEW FEATURE# a|*Events support for Spotter embed* - -New embed events:: - -- `EmbedEvent.ExitPresentMode` + -Emits when a user exits the Liveboard or visualization presentation mode. -- `EmbedEvent.LastPromptDeleted` + -Emits when a query prompt in Spotter embed is deleted. -- `EmbedEvent.LastPromptEdited` + -Emits when a query prompt in Spotter embed is edited. -- `EmbedEvent.ResetSpotterConversation` + -Emits when a Spotter query is reset. -- `EmbedEvent.PreviewSpotterData` + -Emits when a user clicks the Preview data button in the Spotter conversation panel. -- `EmbedEvent.SpotterQueryTriggered` -Emits when a Spotter query is triggered. - -The following embed events are also supported in Spotter embed: - -- `EmbedEvent.AddRemoveColumns` -- `EmbedEvent.AnswerChartSwitcher` -- `EmbedEvent.AuthExpire` -- `EmbedEvent.AuthInit` -- `EmbedEvent.CopyToClipboard` -- `EmbedEvent.CustomAction` -- `EmbedEvent.Data` -- `EmbedEvent.DataSourceSelected` -- `EmbedEvent.DialogClose` -- `EmbedEvent.DialogOpen` -- `EmbedEvent.Download` -- `EmbedEvent.DownloadAsCsv` -- `EmbedEvent.DownloadAsPng` -- `EmbedEvent.DownloadAsXlsx` -- `EmbedEvent.DrillDown` -- `EmbedEvent.DrillExclude` -- `EmbedEvent.DrillInclude` -- `EmbedEvent.Edit` -- `EmbedEvent.Error` -- `EmbedEvent.Load` -- `EmbedEvent.Pin` -- `EmbedEvent.Save` -- `EmbedEvent.TableVizRendered` -- `EmbedEvent.VizPointClick` -- `EmbedEvent.VizPointDoubleClick` -- `EmbedEvent.VizPointRightClick` - -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. +*Action required:* Update all references to `EmbedEvent.SpotterData` in your integration code to use `EmbedEvent.PreviewSpotterData`. -|==== +[source,JavaScript] +---- +// Before — no longer works in SDK v1.50.x and later: +spotterEmbed.on(EmbedEvent.SpotterData, (data) => { ... }); -== Version 1.38.0, June 2025 +// After: +spotterEmbed.on(EmbedEvent.PreviewSpotterData, (data) => { ... }); +---- -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| *String IDs for text customization* + -Developers can now customize a specific occurrence of a visible text string in the ThoughtSpot UI using the `stringIDs` object in the customization interface. +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Liveboard browser cache refresh -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. +// SOURCE: SCAL-305659 -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. +The Liveboard browser cache feature is now in Early Access. Set `enableLiveboardDataCache` to `true` in `LiveboardViewConfig` to enable client-side caching of Liveboard visualization data. -For more information, see xref:customize-text-strings.adoc[Customize text strings]. +The following SDK identifiers are available for this feature: -|[tag greenBackground]#NEW FEATURE# a| *Hide columns on list pages* + +[cols="2,3"] +|==== +| Identifier | Description -In full app embedding, you can now hide the following columns on the *Liveboards* and *Answers* listing pages using the `hiddenListColumns` array: +| `EmbedEvent.RefreshLiveboardBrowserCache` +| Emitted when the Liveboard browser cache is refreshed. -* *Author* + -`hiddenListColumns: [ListPageColumns.Author]` -* *Favorite* + -`hiddenListColumns: [ListPageColumns.Favourite]` -* *Last modified* + -`hiddenListColumns: [ListPageColumns.DateSort]` -* *Tags* + -`hiddenListColumns: [ListPageColumns.Tags]` -* *Share* + -`hiddenListColumns: [ListPageColumns.Share]` + +| `HostEvent.RefreshLiveboardBrowserCache` +| Trigger a manual cache refresh from the host application. -For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. +| `Action.RefreshLiveboardBrowserCache` +| Action ID to show or hide the cache refresh button in the Liveboard toolbar. |==== -== Version 1.37.0, April 2025 - -[width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pairs. -This feature is available only if third-party integration is enabled on your instance and the script hosting domain URL is added to the CSP allowlist. - -For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. - -|[tag greenBackground]#NEW FEATURE# a| -You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. - -|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: - -Embed Events:: - -* `EmbedEvent.TableVizRendered` + -Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. -* `EmbedEvent.CreateLiveboard` + -Emits when a Liveboard is created. - -Host Events:: - -* `HostEvent.TransformTableVizData` + -Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. - -* `HostEvent.Remove` + -Triggers the *Delete* action on a Liveboard. -|==== +== Version 1.49.x, June 2026 -== Version 1.36.0, February 2025 +// SOURCE: https://github.com/thoughtspot/developer-docs/blob/26.7.0.cl-doc-updates/modules/ROOT/pages/api-changelog.adoc [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# a| -The following HostEvents now allow custom parameters to set object properties programmatically: +[discrete] +===== Spotter file upload -* `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. +The SDK introduces two new configuration parameters in `SpotterChatViewConfig`: -For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. +* `spotterFileUploadEnabled` — When set to `true`, enables the file upload feature in the Spotter chat panel. +* `spotterFileUploadFileTypes` — Restricts file types allowed for upload. Accepts a `SpotterFileUploadFileTypes` object. |[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Chart and table visualization overrides -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: +The `visualOverrides` property is introduced in `SearchViewConfig` and `AppViewConfig`. Chart and table override options are available at embed initialization time. -* `--ts-var-spotter-input-background` -* `--ts-var-spotter-prompt-background` +For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. -For more information about Spotter customization, see xref:embed-spotter.adoc#SpotterCSS[Customize styles]. |[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== EmbedEvent.SpotterConversationDeleted +Emitted when a saved Spotter conversation is deleted by the user inside the embedded interface. -Configuration attributes:: - -* `hideIrrelevantChipsInLiveboardTabs` + -Hides filter chips on a Liveboard when set to `true`. - -* `isLiveboardCompactHeaderEnabled` + -Enables the compact Liveboard header feature when set to `true`. - -Action IDs:: -Use the following action IDs in the `disabledActions`, `visibleActions`, or `hiddenActions` array to disable, show, or hide menu actions on an embedded Liveboard: - -* `Action.DisableChipReorder` + -ID for the action that disables filter chip reordering. -* `Action.ChangeFilterVisibilityInTab` - -|==== - -== Version 1.35.0, December 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| -The SDK now provides the `isUnifiedSearchExperienceEnabled` setting to customize the Search experience on ThoughtSpot Home page for embedding application users: - -* When set to `true`, the split search experience is disabled and the Search bar on the Home page functions as Natural Language Search interface -* When set to `false`, the split search experience is enabled and object Search is set as the default Home page search experience. - -For more information, see xref:full-app-customize.adoc#_search_components[Search interface on the Home page in full application embedding]. - -|[tag greenBackground]#NEW FEATURE# a| The `overrideOrgId` parameter in the SDK provides the ability to override Org context for embedding application users. This parameter allows users authenticated to an Org to temporarily view content from another Org. Before specifying the Org ID for override, make sure the Per Org URL feature is enabled on your ThoughtSpot instance. To enable Per Org URL on your instance, contact ThoughtSpot Support. -|==== - -== Version 1.34.0, November 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now embed the following ThoughtSpot Spotter components in your app: - -* `SpotterEmbed` + -Embeds Spotter conversation interface in your app -* `SpotterAgentEmbed` + -Creates a conversation component without the body, which can be integrated into chatbots or other conversational apps. - -For more information, see xref:embed-spotter.adoc[Embed Spotter] and xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters and enumerations are available for customizing Liveboard experience: - -* `showLiveboardVerifiedBadge` + -Shows or hides the Liveboard verified badge. Available if the Liveboard compact header feature is enabled. -* `showLiveboardReverifyBanner` + -Shows or hides the re-verify banner. Available if the Liveboard compact header feature is enabled. -* `Action.KPIAnalysisCTA` + -Action ID to show, hide, or disable the **Analyze CTA** action on a KPI chart. - -|[tag greenBackground]#NEW FEATURE# |You can now use the `HostEvent.GetIframeUrl` to get the iframe src URL from the Visual Embed Playground. If you are embedding ThoughtSpot in apps like Salesforce and Sharepoint without the SDK, use this event to generate the iframe URL. - -|[tag greenBackground]#NEW FEATURE# a|The following parameters are available for customizing Search experience: - -* `collapseDataPanel` -Minimizes the data panel view. Users can click the data panel header any time to expand the panel. -* `collapseSearchBar` -Sets the initial state of the search bar when embedding a saved Answer. - -|[tag greenBackground]#NEW FEATURE# a| The following settings are available for customizing the new home page and navigation experience in full app embedding: - -* `HomeLeftNavItem.LiveboardSchedules` + -The Liveboard schedules menu on the left navigation panel. - -Action enumerations:: - -* `Action.EditScheduleHomepage` + -To show, disable, or hide the *Edit* action on the *Liveboard schedules* page -* `Action.PauseScheduleHomepage` + -To show, disable, or hide the *Pause* action on the *Liveboard schedules* page -* `Action.ViewScheduleRunHomepage` + -To show, disable, or hide the *View run history* action on the *Liveboard schedules* page -* `Action.DeleteScheduleHomepage` + -To show, disable, or hide the *Delete* action on the *Liveboard schedules* page -* `Action.UnsubscribeScheduleHomepage` + -To show, disable, or hide the *Unsubscribe* action on the *Liveboard schedules* page -|==== - -== Version 1.33.x, October 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| You can now customize the search experience for the embedded ThoughtSpot **Home** page using `homePageSearchBarMode`. By default, the **Home** page includes the Object Search bar, which allows finding popular Liveboards and Answers. - -You can set the `homePageSearchBarMode` property to one of the following options: +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== EmbedEvent.SpotterConversationSelected -** `aiAnswer` + -Displays the search bar for Natural Language Search. -** `none` -Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. -** `objectSearch` (default) + -Displays Object Search bar on the **Home** page. -|[tag greenBackground]#NEW FEATURE# a|The SDK now allows you to set the focus on the Search bar or outside the Search bar when rendering the embedded Search page. Use the `focusSearchBarOnRender` property to set the position of the cursor focus. -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following Event and Action enumeration members: - -Events:: - -* `EmbedEvent.OnBeforeGetVizDataIntercept` + -Developers can emit this event to intercept search execution, allow or restrict certain queries, and show an error message with custom text for restricted queries. To allow the embedded page to emit this event, you must set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true`. - -* `EmbedEvent.ParameterChanged` + -Emitted when a Parameter is changed on a saved Answer or Liveboard. - -Actions:: - -* `Action.ManageTags` + -Use this action enumeration to disable, show, or hide the **Manage tags** button on the Liveboards and Answers pages. -|==== - -== Version 1.32.x, August 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following new action enumerations are available in this version: + - -* `Action.CreateLiveboard` for the *Create Liveboard* menu action on the Liveboards lists page. + -* `Action.SyncToTeams` for the **Sync to Teams** menu action on Liveboard visualizations. -* `Action.SyncToSlack` for the **Sync to Slack** action on Liveboard visualizations. -* `Action.AddQuerySet` for the **Add Query Set** action on the data panel (new experience) of the Search page. -* `Action.AddColumnSet` for the **Add Column Set** action on the data panel (new experience) of the Search page. -* `Action.AddDataPanelObjects` for the **Add** menu that includes sub-menu options such as Formulas, Parameters, Query set, and Column set actions. -* `Action.OrganiseFavourites` for the **Organize** action above the Favorites panel on the modular Homepage (New experience) -For more information, see xref:Action.adoc[Actions]. -|[tag greenBackground]#NEW FEATURE#| Developers can now use the `disableRedirectionLinksInNewTab` parameter to disable links and redirection of links in the embedded view. -|[tag greenBackground]#NEW FEATURE# a|You can now enable `enable2ColumnLayout` on a Liveboard to adjust the page view according to the width and resolution of users' devices. -|| -|==== - -== Version 1.31.x, July 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| Runtime filters + - -* `NOT_IN` operator for Runtime filters. -For more information, see xref:runtime-filters.adoc#runtimeFilterOp[Runtime filters]. -* `excludeRuntimeParametersfromURL` parameter to exclude or remove runtimeParameters from the URL. -|[tag greenBackground]#NEW FEATURE# |For performance optimization, developers can choose to load embedded views in a lightweight V2 shell by setting `enableV2Shell_experimental` to `true`. -|==== - -== Version 1.30.0, June 2024 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **CSS variables for new homepage experience** - -* `--ts-var-home-watchlist-selected-text-color` + -* `--ts-var-home-card-color` + -* `--ts-var-home-favorite-suggestion-card-text-color` + -* `--ts-var-home-favorite-suggestion-card-background` + -* `--ts-var-home-favorite-suggestion-card-icon-color` - -For more information, see xref:css-customization.adoc#_homepage_modules_new_experience_mode[CSS variables and overrides]. -|==== - -== Version 1.29.0, May 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| **Ask Sage** - -With Ask Sage [beta betaBackground]^Beta^ embedded application users can ask follow-up questions on a visualization generated from a Natural Language Search query, converse with AI analyst, and refine results. To enable this feature, set `enableAskSage` to `true`. - -Action enumeration:: -To show, hide, or disable Ask Sage on a visualization, add `Action.AskAi`. For example, -+ -[source,JavaScript] ----- -hiddenActions: [Action.AskAi] ----- - -Events:: -* `HostEvent.AskSage` + -Triggers the **Ask Sage** action on a Liveboard visualization. -* `EmbedEvent.AskSageInit` + -Emits when the **Ask Sage** action is initialized. -* `HostEvent.GetParameters` + -Triggers a fetch action to get runtime Parameters. -* `HostEvent.UpdateParameters` + -Updates runtime Parameters -* `HostEvent.ResetLiveboardPersonalisedView` + -Resets a personalized Liveboard view. -* `HostEvent.UpdateCrossFilter` + -Updates cross filters applied on a Liveboard. -|==== - -== Version 1.28.x, April 2024 - -[width="100%" cols="1,4"] -|===== -|[tag greenBackground]#NEW FEATURE# a| The SDK includes the following new enumeration members in v1.28.0: - -** `Action.VerifiedLiveboard` + -Can be used to show or hide the *Verified Liveboard* banner. -|[tag greenBackground]#NEW FEATURE# a| To access the new Home page and global navigation experience in the full application embedding, you can use the `modularHomeExperience` property in the SDK. The modular homepage experience is turned off by default and is available as an Early Access feature in 9.12.5.cl release. When `modularHomeExperience` is set to `true`, you can use the following parameters in the SDK to control the application experience: - -* `hiddenhomeleftnavitems` -* `hiddenhomepagemodules` -* `hideapplicationswitcher` -* `hidehomepageleftnav` -* `hideorgswitcher` -* `reorderedhomepagemodules` -* `hiddenhomeleftnavitems` -* `HomeLeftNavItem` - -For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. -|[tag greenBackground]#NEW FEATURE# a| The following embed event is available from the v1.28.0 onwards: - -`EmbedEvent.Rename` + -Emits when an embedded Liveboard or visualization is renamed. -|[tag greenBackground]#NEW FEATURE# a| TML actions - -The following TML menu actions are now grouped under *TML* sub-menu of the **More** image:./images/icon-more-10px.png[the more options menu] menu on Answer page. - -* Export TML -* Edit TML -* Update TML - -To show, hide, or disable these actions in the embedded mode, use the following format: - -[source,JavaScript] ----- - // to show the TML menu and its sub-menu options -visibleActions: [Action.TML, Action.ExportTML, Action.EditTML] ----- - -[source,JavaScript] ----- - // to hide all TML actions -hiddenActions: [Action.TML] ----- - -[source,JavaScript] ----- - // to disable all TML actions -disabledActions: [Action.TML] ----- -|[tag greenBackground]#NEW FEATURE# | You can now reset authentication token and fetch a new token for new authentication requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_resetCachedAuthToken[resetCachedAuthToken]. - -|[tag greenBackground]#NEW FEATURE#| You can now override the default number, date, and currency format defined by your locale settings. To override the default settings, use the following parameters: - -* `numberFormatLocale` + -* `dateFormatLocale` + -* `currencyFormat` - -For more information, see xref:locale-setting.adoc#_set_locale_in_the_sdk[Customize locale]. - -|[tag greenBackground]#NEW FEATURE# |Tokenized fetch + -The SDK now provides a fetch wrapper that adds the authentication token to the API requests. -For more information, see link:https://developers.thoughtspot.com/docs/Function_tokenizedFetch#_tokenizedfetch[tokenizedFetch]. -|===== - -== Version 1.27.x, March 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The following action enumeration members are available from v1.27.9 and v1.27.10: - -* `Action.AIHighlights` -* `Action.AddToWatchlist` -* `Action.RemoveFromWatchlist` -* `Action.CopyKpiLink` - -For more information, see xref:Action.adoc[Action]. -| [tag greenBackground]#NEW FEATURE# a| You can now use `HostEvent.GetAnswerSession` to get Answer session data for a Search Answer or Liveboard Visualization in the embedded view. -|==== - -== Version 1.27.0, January 2024 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. - -For a complete list of methods, functions, interface objects, and properties, see the following pages: + - -* xref:SageEmbed.adoc[SageEmbed] -* xref:SageViewConfig.adoc[SageViewConfig] - -|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. -For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: - -* Host Events -** `HostEvent.UpdateSageQuery` + -Updates the search query string for Natural Language Search operations. -* Embed Events -** `EmbedEvent.CreateConnection` + -Emitted when a user creates a new data connection on the **Data** page. -** `EmbedEvent.CreateWorksheet` + -Emitted when a user creates a new Worksheet. -|==== - -== Version 1.26.0, November 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK provides `AnswerService` class to trigger the answer service with a custom action payload. -You can use this service to run GraphQL queries in the context of the Answer with a custom action trigger. For more information, see link:https://developers.thoughtspot.com/docs/Class_AnswerService[AnswerService]. Recommended ThoughtSpot application version is 9.10.0.cl. - -|[tag greenBackground]#NEW FEATURE# a|The following object properties and feature flags are introduced in the `LiveboardEmbed` and `AppEmbed` SDK packages: - -* `showLiveboardDescription` + -Shows the Liveboard description text when set to `true` -* `showLiveboardTitle` + -Shows the Liveboard title when set to `true` -* `isLiveboardHeaderSticky` + -Sets Liveboard header bar as a fixed element when set to `true` -* `hideLiveboardHeader` + -Hides the Liveboard header when set to `true` -* `hiddenTabs` + -Hides the specified tabs from the Liveboard page -* `visibleTabs` + -Displays the specified tabs on the Liveboard page - -|[tag greenBackground]#NEW FEATURE# |You can now enable the new data panel experience by setting `dataPanelV2` to `true` in the SDK when embedding ThoughtSpot Search. The new data panel experience is turned off by default on embedded ThoughtSpot instances. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports the following events: - -Embed events:: -* `EmbedEvent.hiddenTabs` -* `EmbedEvent.visibleTabs` -* `EmbedEvent.UpdatePersonalisedView` -* `EmbedEvent.SavePersonalisedView` -* `EmbedEvent.ResetLiveboard` -* `EmbedEvent.DeletePersonalisedView` -* `EmbedEvent.SageWorksheetUpdated` -* `EmbedEvent.SageEmbedQuery` -+ -For more information, see xref:EmbedEvent.adoc[EmbedEvent]. - -Host events:: - -* `HostEvent.GetTabs` -* `HostEvent.SetVisibleTabs` -* `HostEvent.SetHiddenTabs` -* `HostEvent.GetAnswerSession` -* `HostEvent.UpdateSageQuery` -+ -For more information, see xref:HostEvent.adoc[HostEvent]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.AddTab` + -Show, disable, or hide the **Add Tab** action on a Liveboard. -* `Action.PersonalisedViewsDropdown` + -Show, disable, or hide the Liveboard views saved by a user. -* `Action.LiveboardUsers` + -Show, disable, or hide Liveboard users. -* `Action.SageAnswerFeedback` -Show, disable, or hide the feedback widget on AI-generated Answer page. -* `Action.EditSageAnswer` -Show, disable, or hide the **Edit** action on the AI-generated Answer page. - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.25.0, October 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# | The SDK now supports runtime Parameter overrides on Liveboards and Answers. -For more information, see xref:runtime-parameters.adoc#_apply_parameter_overrides_using_visual_embed_sdk[Runtime Parameter overrides]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: - -* `Action.RenameModalTitleDescription` -* `Action.EnableContextualChangeAnalysis` -* `Action.RequestVerification` -* `Action.AddTab` - -For more information, see xref:Action.adoc[Actions]. -|==== - -== Version 1.24.0, September 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| ThoughtSpot now provides the `SageEmbed` package to embed the ThoughtSpot Search page with Sage features such as natural language search and AI-suggested search examples. This feature is in beta and not available in the Visual Embed Playground. -|[tag greenBackground]#NEW FEATURE# a| The `HostEvent.SetActiveTab` event in the upcoming version of the SDK allows you to set a tab as an active tab on a Liveboard. -|==== - -== Version 1.23.0, August 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| New events for Liveboard filters + - -* `EmbedEvent.FilterChanged` + -* `HostEvent.GetFilters` + -* `HostEvent.UpdateFilters` -//// - -== Version 1.22.0, June 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the `TrustedAuthTokenCookieless` `authType` property to allow Cookieless embedding. The Cookieless authentication method allows using a bearer token to identify the signed-in user instead of session cookies. - -For more information, see xref:embed-authentication.adoc#_cookieless_authentication[Cookieless authentication]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK allows you to block user access to the non-embedded instance of the ThoughtSpot application. In full app embed deployments, you can use the `blockNonEmbedFullAppAccess` property in the SDK to restrict or allow your application users from accessing ThoughtSpot pages in the non-embed mode. - -For more information, see xref:security-settings.adoc#_block_access_to_non_embedded_thoughtspot_pages[Block access to non-embedded ThoughtSpot pages]. - -|==== - -//// -|[tag greenBackground]#NEW FEATURE# a| The SDK supports the following performance optimization enhancements: + - -* Ability to pre-render a generic instance of the ThoughtSpot component using the `prerenderGeneric` attribute. The generic instance uses the default host and flags and can be rendered in the background to improve application response. -* Ability to use an iFrame from a pre-rendered iFrame pool using the `usePrerenderedIfAvailable` attribute. -//// - -== Version 1.21.0, May 2023 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following action enumeration members: - -* `Action.AxisMenuAggregate` -* `Action.AxisMenuConditionalFormat` -* `Action.AxisMenuEdit` -* `Action.AxisMenuFilter` -* `Action.AxisMenuGroup` -* `Action.AxisMenuNumberFormat` -* `Action.AxisMenuPosition` -* `Action.AxisMenuRemove` -* `Action.AxisMenuRename` -* `Action.AxisMenuSort` -* `Action.AxisMenuTextWrapping` -* `Action.AxisMenuTimeBucket` -* `Action.CrossFilter` -* `Action.RemoveCrossFilter` - -For more information, see xref:embed-action-ref.adoc[Action reference]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following events: - -* `HostEvent.AddColumns` -* `HostEvent.OpenFilter` -* `HostEvent.RemoveColumn` -* `HostEvent.ResetSearch` -* `EmbedEvent.CrossFilterChanged` -* `EmbedEvent.DownloadAsPng` -* `EmbedEvent.VizPointRightClick` - -For more information, see xref:embed-events.adoc[Events]. - -|[tag redBackground]#DEPRECATED# a| - -The following events are deprecated from version 1.21.0 onwards. - -* `HostEvent.Download` + -* `EmbedEvent.Download` - -You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. - -For more information, see xref:embed-events.adoc[Events reference]. -|[tag orangeBackground]#MODIFIED# a| - -Events:: -The SDK supports omitting or executing a search query in xref:HostEvent.adoc#_search[`HostEvent.Search`]. -Actions:: -Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: -+ -* `Action.DownloadAsCsv` -* `Action.DownloadAsPdf` -* `Action.DownloadAsXlsx` -* `Action.DownloadAsPng` - -+ -To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + - -** `Action.DownloadAsCsv` + -** `Action.DownloadAsPdf` + -** `Action.DownloadAsXlsx` + -** `Action.DownloadAsPng` - -|[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: - -* `linkOverride` -+ -Allows overriding the *Open in new tab* link on embedded pages. - -* `contextMenuTrigger` -+ -Allows triggering contextual menu on the Liveboard visualizations and Answers from left-click to right-click. - -* `hideSearchBar` -+ -Allows hiding the Search bar on the embedded Search page. -|[tag greenBackground]#NEW FEATURE# | The SDK now allows setting the loading preference for embedded iFrames. -For performance optimization, you can set the `loading` attribute to `lazy` in the `FrameParams` property. -|==== - -== Version 1.20.0, April 2023 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#DEPRECATED# a|The `dataSources` property in `SearchEmbed` and `SearchBarEmbed` is deprecated and replaced with the `dataSource` attribute. The SDK supports searching from a single data source only. -|[tag greenBackground]#NEW FEATURE# a|The embed SDK packages now include the `insertAsSibling` property. This attribute can be used to insert the embedded object as a sibling to the element inside the target container. -|==== - -== Version 1.19.0, February 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the styles for dialogs, search bar, search navigation and search suggestions panels. -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: - -[source,JavaScript] - ----- -liveboardEmbed.on(EmbedEvent.CustomAction, payload => { - if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { - console.log('Custom Action event:', payload.data); - } -}) ----- - -You may also want to update the data classes in your scripts to process the JSON response payload and handle complex data. For more information, see xref:custom-actions-callback.adoc#_define_functions_and_classes_to_handle_liveboard_data[Callback custom actions]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK introduces the following Host events: - -* `HostEvent.Delete` -* `HostEvent.Download` -* `HostEvent.DownloadAsCsv` -* `HostEvent.DownloadAsXlsx` -* `HostEvent.ManagePipelines` -* `HostEvent.Save` -* `HostEvent.Share` -* `HostEvent.ShowUnderlyingData` -* `HostEvent.SpotIQAnalyze` -* `HostEvent.SyncToOtherApps` -* `HostEvent.SyncToSheets` - -For more information, see xref:events-hostEvents.adoc[Host events]. - -|[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. - -For more information, see xref:embed-authentication.adoc#_saml_redirection[SAML Redirection]. -|==== - -== Version 1.18.0, January 2023 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK provides the `SearchBarEmbed` JavaScript package to embed only the ThoughtSpot Search bar in your app. + - -For more information, see xref:embed-searchbar.adoc[Embed ThoughtSpot search bar]. - -|[tag greenBackground]#NEW FEATURE# a|The `customCSS` property in the `customizations` object supports new variables to customize the UI elements on Liveboard, visualization, and Answer pages. You can also use these variables to define custom styles in the CSS file. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|[tag greenBackground]#NEW FEATURE# |The new version of the SDK allows fetching TML objects via `GetTML` host event. This event is triggered when a user clicks on the *Show underlying data* action on a Liveboard visualization or Answer page. + - -For more information, see xref:HostEvent.adoc#_gettml[GetTML]. - -|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following enums in the `Action` object: - -* `Action.SyncToOtherApps` + -* `Action.SyncToSheets` + -* `Action.ManagePipelines` + - -You can use these enums to show, hide, or disable *Sync to sheets*, *Sync to other apps*, and *Manage pipelines* menu actions on a Liveboard visualization or Answer. - -For more information, see xref:embed-action-ref.adoc[Actions]. -|==== - -== Version 1.17.1, December 2022 - -Bug fixes to the trusted authentication feature. - -== Version 1.17.0, November 2022 - -The new version of the SDK introduces several new features and enhancements. -[width="100%" cols="1,4"] -|==== -|[tag orangeBackground]#MODIFIED# a|The `AuthType` property is modified and supports new enums. + - -* `AuthType.SAML` is renamed as `AuthType.SAMLRedirect` + -* `AuthType.OIDC` is renamed as `AuthType.OIDCRedirect` + -* `AuthType.AuthServer` is renamed to `AuthType.TrustedAuthToken` + -This enhancement does not introduce any breaking changes to your current implementation. -|[tag greenBackground]#NEW FEATURE# a|To use your current SAML or OIDC authentication setup and redirect users to the IdP for authentication within the embedded iFrame, you can now use `AuthType.EmbeddedSSO`. + -For more information, see xref:embed-authentication.adoc[Authentication]. -|[tag greenBackground]#NEW FEATURE#| -The `customizations` object in the SDK allows you to specify a custom CSS URL. You can also use this object to define CSS variables directly in the `init` code. + -For more information, see xref:css-customization.adoc[Customize CSS]. -|==== - -== Version 1.16.0, October 2022 - -The new version of the SDK includes bug fixes and improvements to the new Liveboard experience. - -== Version 1.15.1, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The `prefetch` method now supports the `url` and `prefetchFeatures` parameters. You can use these parameters to call the prefetch method before `init` and prefetch static resources on application load. + -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. -|==== - -== Version 1.15.0, September 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. - -For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. - -|[tag greenBackground]#NEW FEATURE# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: - -* CopyLink -* CreateMonitor -* DownloadAsPdf -* Edit -* EditTML -* Explore -* ExportTML -* LiveboardInfo -* MakeACopy -* ManageMonitor -* Pin -* Present -* Remove -* Schedule -* SchedulesList -* UpdateTML - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.14.0, August 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -The Visual Embed SDK now includes the `liveboardV2` attribute in the `LiveboardEmbed` package to allow developers to enable the new Liveboard experience on their embedded ThoughtSpot instance. + -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. -|[tag orangeBackground]#MODIFIED#|If trusted authentication is enabled, the SDK makes a `POST` API call to get a login token and log the user into ThoughtSpot. -The earlier versions of the SDK supported only `GET` API requests. For more information, see xref:embed-authentication.adoc#_configure_token_based_authentication_method_in_visual_embed_sdk[Configure token-based authentication method in Visual Embed SDK]. -|==== - -== Version 1.13.0, July 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. -|[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + -For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. -|[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + -This change does not impact your current embed implementation with `AuthType.SSO`. -|[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + -For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.12.0, June 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. - -For more information, see xref:events-hostEvents.adoc[Events reference]. -|[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. -|==== - -== Version 1.11.2, June 2022 - -Bug fix for Typescript builds that affect Angular project configurations. - -== Version 1.11.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK includes the action enum `ReportError`, using which you can turn off ThoughtSpot-specific error reporting. -|==== - -== Version 1.11.0, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK includes the following new events: - -* `ALL` -* `AnswerChartSwitcher` -* `AnswerDelete` -* `CopyAEdit` -* `CopyToClipboard` -* `Download` -* `DownloadAsPdf` -* `DownloadAsCsv` -* `DownloadAsXlsx` -* `DrillExclude` -* `DrillInclude` -* `EditTML` -* `ExportTML` -* `Monitor` -* `Pin` -* `Save` -* `SaveAsView` -* `Share` -* `ShowUnderlyingData` -* `SpotIQAnalyze` -* `UpdateTML` -* `VizPointClick` - -For more information about how to register and handle these events, see xref:embed-events.adoc[Events and app integration]. -|[tag greenBackground]#NEW FEATURE# a| The new version of SDK supports the `showAlerts` attribute, using which you can show or hide alerts and error messages in the embedded view. - -|[tag greenBackground]#NEW FEATURE# a| The `Action.CreateMonitor` enumeration is available in the SDK for embedded ThoughtSpot environments on which the *Monitor* feature is enabled. -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. -|==== - -== Version 1.10.4, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `detectCookieAccessSlow` parameter in the SDK allows your app to check if third-party cookies are enabled on the browser. This parameter is available only for trusted and `Basic` authentication types. -|==== -== Version 1.10.3, May 2022 - -Bug fix and improvements to the `logout` method. - -== Version 1.10.2, May 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|Ability to configure `redirectPath` on the origin when using the SAMLRedirect `authType`. -|==== - -== Version 1.10.1, May 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|You can now use the `logout` method to log out embed users. -|[tag orangeBackground]#MODIFIED# a| Note the following changes: + - -* You can now use the `loginFailedMessage` property on init to display the `Not logged in` message when a user login fails. You can customize this message by defining a custom text string in the `loginFailedMessage` attribute. -* The `init` method now returns an event emitter which can be used to listen to `AuthStatus` such as login failure, success, or user logout. -|==== - -== Version 1.10.0, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.8, April 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `pageId` attribute now allows you to set the **SpotIQ** page as the home tab of your embedded ThoughtSpot app. - -For more information, see xref:full-embed.adoc[Embed full application]. -|==== - -== Version 1.9.6 and 1.9.7, April 2022 - -Bug fixes and improvements - -== Version 1.9.5, April 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#|The `locale` attribute is now available in embed packages. You can use this attribute to set the locale or language of your embedded application view. -For more information, see xref:locale-setting.adoc[Set locale and display language]. -|==== - -== Version 1.9.4, April 2022 - -Bug fixes and improvements to React components. - -== Version 1.9.3, March 2022 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now supports the `disableLoginRedirect` attribute to improve the login experience for your application users. When enabled, this attribute prevents your app from redirecting users to the login page when their session expires. + -You can use this attribute along with `autoLogin` to automatically authenticate and re-login a user. + -This feature is applicable to token-based authentication, that is, when the `AuthType` is set as `TrustedAuthToken` in the SDK. - -For more information, see xref:embed-authentication.adoc#trusted-auth-embed[Authentication]. -|==== - -== Version 1.9.2, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| You can now trigger events on React components using the `useEmbedRef` hook. - -For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. -|==== - -== Version 1.9.1, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE#| The SDK now includes the `visibleVizs` attribute in the `LiveboardEmbed` package. This attribute allows you to add visualization GUIDs that you want to display when a Liveboard renders for the first time. - -For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. - -|[tag greenBackground]#NEW FEATURE# a| The following events are now available in the SDK: + - -* `LiveboardRendered` (EmbedEvent) - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.9.0, March 2022 -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a| The SDK now includes the following new enumerations for UI actions: - -* `Action.AnswerDelete` + -* `Action.AnswerChartSwitcher` + -* `Action.AddToFavorites` + -* `Action.EditDetails` + - -For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. - -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. -|==== - -== Version 1.8.x, February 2022 - -[width="100%" cols="1,4"] -|==== -|[tag redBackground]#BREAKING CHANGE# | The `autoLogin` attribute is now set as `false` by default. This attribute is used in the `init` method to automatically re-login a user when a session expires. -|[tag greenBackground]#NEW FEATURE# | The `init` method now returns the `authPromise` which resolves when a user authentication is completed. -|==== - - -== Version 1.7.0, January 2022 - -[width="100%" cols="1,4"] -|==== -| -[tag greenBackground]#NEW FEATURE# |+++
OIDC AuthType
+++ - -The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. - -For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK includes the following new event: - -* `RouteChange` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.6.x, November 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
Visible actions
+++ - -You can now configure a set of ThoughtSpot UI actions as visible actions and display these actions in the embedded UI. If your embedded instance requires only a few actions, you can use the `visibleActions` API to show only these actions in the embedded ThoughtSpot UI. - -For more information, see xref:embed-actions.adoc[Show or hide UI actions]. - -|[tag orangeBackground]#MODIFIED# | +++
Terminology changes
+++ - -The SDK library and object parameter names are modified to rebrand pinboards as Liveboards. For a complete list of changes, see xref:terminology-update.adoc#sdk-changes[Terminology changes]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK supports the following new events: - -* `DialogOpen` -* `DialogClose` - -For more information, see xref:event-embedEvents.adoc[Events reference]. -|==== - -== Version 1.5.0, October 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# | +++
Render embedded objects in queue
+++ - -The SDK now supports rendering embedded objects in a queue. If you have multiple embedded objects, you can enable the `queueMultiRenders` parameter to queue your embedded objects and render them one after another. This feature helps in decreasing the load on the web browsers and improving your application loading experience. By default, this attribute is set to `false`. - -|[tag greenBackground]#NEW FEATURE# a|+++
Liveboard embed
+++ - -The `pinboardEmbed` package includes the `defaultHeight` attribute that sets a minimum height for embedded objects on a pinboard page, and the corresponding visualization pages that a user can navigate to. - -For more information, see xref:embed-search.adoc[Embed a pinboard]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ - -The SDK EmbedEvent library includes the following new events: - -* `VizPointDoubleClick` -* `Drilldown` -* `SetVisibleVizs` - -For more information, see xref:event-embedEvents.adoc[Events reference]. - -|==== - -== Version 1.4.0, September 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a|+++
+++Prefetch API+++
+++ - -The `prefetch` API fetches static resources from a given URL before your application loads. Web browsers can then cache the prefetched resources locally and serve them from a user's local disk. You can use this API to load the embedded objects faster and improve your application response time. - -For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++In-app page navigation+++
+++ - -The `navigateToPage` method in the SDK lets you provide quick and direct access to a specific pinboard, saved Answer, or an application page. You can add a custom menu action or button in your application UI that calls the `navigateToPage` method and leads your users to the page specified in the `path` parameter. - -For more information, see xref:page-navigation.adoc[Add a custom action for in-app navigation]. - -|[tag greenBackground]#NEW FEATURE# a|+++
+++Full application embedding+++
+++ - -The `appEmbed` SDK package includes the following new attributes: - -* The `disableProfileAndHelp` attribute to show or hide the `Help (?)` and the user profile menu in the navigation bar of your embedded app. - -* The `hideObjects` attribute to hide specific objects from a user's page view. - -For more information, see xref:full-embed.adoc[Embed full application]. - -|[tag greenBackground]#NEW FEATURE# |+++
+++Search embed +++
+++ - -The `searchEmbed` package includes the `forceTable` attribute that sets tabular view as the default format for presenting search data. You can set this attribute to `true` to force search results to appear in the table view. - -For more information, see xref:embed-search.adoc[Embed ThoughtSpot search]. - -|[tag redBackground]#REMOVED# | - -The `searchQuery` parameter is no longer supported and is removed from the `searchEmbed` SDK package. -|[tag greenBackground]#NEW FEATURE# a|+++
+++Embed events +++
+++ -The SDK EmbedEvent library includes the following events: - -* `QueryChanged` -* `AuthExpire` - -For more information, see xref:embed-events.adoc[Events and app integration]. -|==== - -== Version 1.3.0, August 2021 - -[width="100%" cols="1,4"] -|==== -|| -|[tag greenBackground]#NEW FEATURE# a| +++
searchOptions
+++ - -The `searchEmbed` SDK package introduces the `searchOptions` parameter for setting search tokens. The `searchOptions` parameter includes the following attributes: - -* `searchTokenString` -+ -A TML query string to define search tokens. - -* `executeSearch` -+ -When set to `true`, it executes search and shows the search results. - -For more information, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag redBackground]#DEPRECATED# a| +++
searchQuery
+++ - -The `searchQuery` parameter in the `searchEmbed` SDK package is deprecated in the Visual Embed SDK version 1.3.1. Instead, you can use the `searchOptions` parameter to define the search token string. - -For more information about `searchOptions`, see xref:embed-search.adoc#search-query[Embed ThoughtSpot search]. - -|[tag greenBackground]#NEW FEATURE# a| +++
autoLogin
+++ - -The SDK now supports logging in users automatically after a user session has expired. - -For more information, see xref:embed-authentication.adoc#embed-session-sec[Embed user authentication]. - -|[tag greenBackground]#NEW FEATURE# a| +++
shouldEncodeUrlQueryParams
+++ - -You can now convert query parameters in the ThoughtSpot generated URLs to base64-encoded format. You can enable this attribute to secure your cluster from cross-site scripting attacks. -|[tag redBackground]#BREAKING CHANGE# a| +++
Data structure changes in custom action response payloads
+++ - -* The data structure passed in the custom action response for search now shows as `payload.data.embedAnswerData` instead of `payload.data.columnsAndData`. - -* The Answer payload for custom actions includes the following metadata: - -** `reportBookmetadata` -+ -Includes visualization metadata attributes such as description, object header metadata, author details, timestamp of the Answer creation, and modification. - -** user data -+ -Includes user information such as username, GUID of the user, and email address. - -To view a sample response payload, see xref:callback-response-payload.adoc#search-data-payload[Custom action response payload]. - -|[tag greenBackground]#NEW FEATURE# a| +++
preventPinboardFilterRemoval
+++ - -The `pinboardEmbed` SDK package now includes the `preventPinboardFilterRemoval` attribute. You can use this attribute to disable the filter removal action and thus prevent users from removing the filter chips added on a pinboard page. - -For more information, see xref:embed-pinboard.adoc[Embed a pinboard] and xref:embed-a-viz.adoc[Embed a visualization]. -|[tag greenBackground]#NEW FEATURE# a| +++
suppressNoCookieAccessAlert
+++ - -You can now set custom alerts for `noCookieAccess` events. By default, the SDK triggers a `noCookieAccess` event and generates an alert when a user's browser blocks third-party cookies. The `suppressNoCookieAccessAlert` allows you to disable this alert. - -|[tag greenBackground]#NEW FEATURE# a| +++
Support for fetching callback custom action payload in batches
+++ - -The Visual Embed SDK now supports processing data in batches for callback custom action responses. -The callback custom action event in the SDK package supports defining `batchSize` and `offset` values to paginate the Answer payload and send the records in batches. - -For more information, see xref:push-data-to-external-app.adoc#large-dataset[Callback custom action workflow]. -|==== - -== Version 1.2.0, June 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
SAML authentication
+++ - -The Visual Embed SDK packages now include the `noRedirect` attribute as an optional parameter for the SAMLRedirect SSO `AuthType`. If you want to display the SAML authentication workflow in a pop-up window, instead of refreshing the application web page to direct users to the SAML login page, you can set the `noRedirect` attribute to `true`. - -For more information, see the instructions for embedding xref:full-embed.adoc[ThoughtSpot pages], xref:embed-search.adoc[search], xref:embed-pinboard.adoc[pinboard], and xref:embed-a-viz.adoc[visualizations]. - -|[tag greenBackground]#NEW FEATURE# a|+++
Pinboard actions
+++ -The *More* menu image:./images/icon-more-10px.png[the more options menu] in the embedded Pinboard page now shows the following actions for pinboard and visualizations. - -Pinboard:: -* Save -* Make a copy -* Add filters -* Configure filters -* Present -* Download as PDF -* Pinboard info -* Manage schedules - - -[NOTE] -Users with edit permissions can view and access the *Save*, *Add filters*, *Configure filters*, and *Manage schedules* actions. -|[tag greenBackground]#NEW FEATURE# a|+++
Visualization actions
+++ - -Visualizations on a pinboard: - -* Pin -* Download -* Edit -* Present -* Download as CSV -* Download as XLSX -* Download as PDF - -[NOTE] -Users with edit permissions can view and access the *Edit* action. The *Download as CSV*, *Download as XLSX*, and *Download as PDF* actions are available for table visualizations. The *Download* action is available for chart visualizations. - -|==== - -== Version 1.1.0, May 2021 - -[width="100%" cols="1,4"] -|==== -|[tag greenBackground]#NEW FEATURE# a|+++
NoCookieAccess event
+++ +Emitted when a saved Spotter conversation is selected from the chat history sidebar in the embedded Spotter interface. -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. |==== diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index f37a0a86e..d4ee519ca 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -75,6 +75,19 @@ Multi-tenancy ** link:{{navprefix}}/single-tenant-data-models[Single-tenant data models with Orgs] * link:{{navprefix}}/tse-cluster[Cluster maintenance and upgrade] +[.sidebar-title] +Webhooks + +* link:{{navprefix}}/webhooks[Overview] +* link:{{navprefix}}/webhooks-manage[Webhooks UI] +* link:{{navprefix}}/webhooks-rest-api[Webhook APIs] +* link:{{navprefix}}/webhooks-comm-channel[Configure and monitor webhook communication channels] +* link:{{navprefix}}/webhooks-lb-schedule[Deliver Liveboard reports to external application] +* link:{{navprefix}}/webhooks-s3-integration[AWS S3 storage integration for webhook delivery] +* link:{{navprefix}}/webhooks-gcs-storage[GCS storage integration for webhook delivery] +* link:{{navprefix}}/webhooks-lb-payload[Webhook response payload] +* link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] + * Integration with external tools ** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] ** link:{{navprefix}}/pendo-integration[Pendo integration with embed] diff --git a/modules/ROOT/pages/embed-spotter-viz.adoc b/modules/ROOT/pages/embed-spotter-viz.adoc new file mode 100644 index 000000000..39c0c9296 --- /dev/null +++ b/modules/ROOT/pages/embed-spotter-viz.adoc @@ -0,0 +1,191 @@ += Customizing SpotterViz +:toc: true +:toclevels: 2 + +:page-title: Customizing SpotterViz +:page-pageid: embed-spotter-viz +:page-description: Customize the SpotterViz panel and Insight Tiles in embedded Liveboards using the Visual Embed SDK. + +// SOURCE: SCAL-311987, SCAL-311988, SCAL-303724, SCAL-309605 + +SpotterViz is the AI-powered analysis panel that appears on embedded Liveboards. It displays **Insight Tiles** — AI-generated textual analysis of Liveboard data — and exposes a customizable prompt interface for user interaction. + +This page describes how to customize SpotterViz in embedded Liveboards using the Visual Embed SDK `SpotterVizConfig` interface and related APIs. + +[NOTE] +==== +SpotterViz customization APIs require ThoughtSpot Cloud 26.7.0.cl or later and Visual Embed SDK v1.50.0 or later. The Insight Tile feature is in Beta. Contact ThoughtSpot Support to enable this feature on your instance. +==== + +== About Insight Tiles + +Insight Tiles are a new Liveboard tile type that uses Spotter AI to generate automated textual analysis of the data in your Liveboard. A tile displays 5–7 AI-generated bullet-point insights with a distinct light blue gradient background. + +Key behaviors: + +* *Scope* — Each Insight Tile can be scoped to a Tab, a Group, or an individual Answer. +* *Auto-retriggering* — Insight Tiles automatically regenerate insights on Liveboard load and when Liveboard-level filters change. +* *Localization* — Insights are rendered in the user's configured locale. +* *Runtime filters* — Runtime filters and parameters passed to `LiveboardEmbed` are respected by Insight Tiles. See <>. + +Beta limitations: + +* Insight Tiles are not rendered in scheduled exports or downloads. A placeholder is shown instead. +* Cross-filter interactions are not supported in this Beta release. +* Pinning Insight Tiles from plugins is not supported. + +// TODO: verify with engineering — add link to product docs page for Insight Tiles (thoughtspot-docs) once published + +== `SpotterVizConfig` interface + +The `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` via the `spotterViz` property. Use it to customize the SpotterViz panel's branding and prompt experience. + +[source,JavaScript] +---- +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + liveboardId: '', + spotterViz: { + brandName: 'Acme Analytics', + headline: 'AI-powered insights for your business', + description: 'Ask a question or explore the insights below.', + inputPlaceholder: 'Ask Acme Analytics a question...', + starterPrompts: [ + { prompt: 'What are the top-performing regions this quarter?' }, + { prompt: 'Show me revenue trends for the last 6 months.' }, + ], + }, +}); + +liveboardEmbed.render(); +---- + +=== `SpotterVizConfig` properties + +[cols="2,1,1,4"] +|==== +| Property | Type | Required | Description + +| `brandName` +| string +| No +| Custom brand name displayed in the SpotterViz panel header. Replaces the default "Spotter" label. + +| `headline` +| string +| No +| Custom headline text for the SpotterViz panel. + +| `description` +| string +| No +| Custom description text shown below the headline. + +| `inputPlaceholder` +| string +| No +| Custom placeholder text for the Spotter chat input field. + +| `starterPrompts` +| `SpotterVizStarterPrompt[]` +| No +| Array of starter prompt objects to replace the default prompt suggestions. Each object requires a `prompt` string property. +|==== + +// TODO: verify with engineering — confirm the complete and final list of SpotterVizConfig properties and whether any additional properties are available in 26.7.0.cl + +== CSS customization + +SpotterViz exposes CSS custom properties that allow you to style the Insight Tile to match your application's visual design. Apply these variables using the `customCSS` configuration in your `LiveboardEmbed` initialization. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + liveboardId: '', + customCSS: { + variables: { + // TODO: verify with engineering — replace with confirmed CSS variable names + '--ts-spotterviz-background': 'linear-gradient(135deg, #e8f4fd, #cce8f8)', + '--ts-spotterviz-text-color': '#1a1a2e', + }, + }, +}); +---- + +// TODO: verify with engineering — provide the authoritative list of CSS variable names, their default values, and the CSS scope they apply to + +== Brand customization + +SpotterViz respects ThoughtSpot's brand customization settings. When brand colors are configured in the ThoughtSpot *Develop* > *Style customization* panel, the Insight Tile gradient background updates to reflect your brand palette. + +// TODO: verify with engineering — confirm the exact behavior of brand color overrides on the Insight Tile gradient background + +== Embed events + +Listen to the following events emitted by SpotterViz in your `LiveboardEmbed`: + +=== `EmbedEvent.SpotterVizMount` + +Emitted when the SpotterViz panel mounts in embed mode. + +[source,JavaScript] +---- +liveboardEmbed.on(EmbedEvent.SpotterVizMount, (eventData) => { + console.log('SpotterViz panel mounted:', eventData); +}); +---- + +=== `EmbedEvent.SpotterVizPromptSubmit` + +Emitted when a user submits a prompt in the SpotterViz panel. + +[source,JavaScript] +---- +liveboardEmbed.on(EmbedEvent.SpotterVizPromptSubmit, (eventData) => { + console.log('SpotterViz prompt submitted:', eventData); +}); +---- + +// TODO: verify with engineering — confirm whether additional EmbedEvents are introduced for Insight Tile load and error states in 26.7.0.cl + +[#runtime-filters] +== Runtime filters and Insight Tiles + +// SOURCE: SCAL-309605 + +Runtime filters and parameters passed to `LiveboardEmbed` are respected by Insight Tiles. When a runtime filter is applied, Spotter automatically regenerates the tile's insights using the filtered data context. + +No additional configuration is required. Runtime filters specified via `runtimeFilters` in `LiveboardViewConfig` are automatically applied to all Insight Tiles on the same Liveboard. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + liveboardId: '', + runtimeFilters: [ + { + columnName: 'Region', + operator: RuntimeFilterOp.EQ, + values: ['West'], + }, + ], + spotterViz: { + brandName: 'Acme Analytics', + }, +}); + +liveboardEmbed.render(); +---- + +For more information, see xref:runtime-filter.adoc[Runtime filters]. + +== Related topics + +* xref:embed-spotter.adoc[Embed Spotter] +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:runtime-filter.adoc[Runtime filters] +* xref:api-changelog.adoc[Visual Embed SDK changelog] +* xref:whats-new.adoc[What's new] diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index d50cd0cd5..df0941a7f 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -1269,6 +1269,12 @@ 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.3.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. diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index c0f7ec2d4..b1da5b337 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,16 +8,8 @@ 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.7.0.cl, July 2026 -// TODO: Confirm with engineering whether any new Spotter REST API v2 endpoints -// are introduced in 26.7.0.cl beyond those listed in 26.6.0.cl. -// If no new endpoints ship, this section should note that and link to the 26.6.0.cl -// entries for agent instructions and stop-response which remain current. - -// SOURCE: https://github.com/thoughtspot/developer-docs/blob/main/modules/ROOT/pages/rest-apiv2-changelog.adoc -// (Current 26.6.0.cl entries for Spotter AI APIs are the most recent documented changes) === Spotter AI APIs @@ -30,6 +22,8 @@ The Spotter agent instructions APIs and the stop-response endpoint introduced in For the complete list of Spotter REST API v2 endpoints, see xref:spotter-agent-apis.adoc[Spotter Agent APIs]. +=== Webhook APIs +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. == Version 26.6.0.cl, June 2026 diff --git a/modules/ROOT/pages/saved-conversations-api.adoc b/modules/ROOT/pages/saved-conversations-api.adoc new file mode 100644 index 000000000..b77e40238 --- /dev/null +++ b/modules/ROOT/pages/saved-conversations-api.adoc @@ -0,0 +1,267 @@ += Saved Chat public APIs +:toc: true +:toclevels: 2 + +:page-title: Saved Chat APIs +:page-pageid: saved-conversations-api +:page-description: Use REST APIs and SDK methods to manage saved Spotter conversations from your host application. + +// SOURCE: SCAL-290720, SCAL-313991 + +ThoughtSpot provides public REST API endpoints and Visual Embed SDK host events for managing saved Spotter conversations. These APIs enable advanced embed developers to build fully headless conversation history experiences — for example, rendering a custom chat history list in the host application and loading or managing conversations without relying on the ThoughtSpot sidebar UI. + +== Prerequisites + +* ThoughtSpot Cloud 26.7.0.cl or later. +* Visual Embed SDK v1.50.0 or later. +* The authenticated user must have *Spotter access* on the instance. +* The *Save chat* feature must be enabled on your cluster. Contact ThoughtSpot Support to enable it. + +== Use case + +Some embedded applications manage navigation entirely in the host app and hide ThoughtSpot's native sidebar navigation. These integrations can use the Saved Chat APIs to: + +* Display a custom list of a user's saved Spotter conversations in the host application's own UI. +* Load a specific conversation into the embedded Spotter interface on user selection. +* Rename or delete conversations in response to user actions in the host app. +* React to conversation lifecycle events to keep an external history list in sync. + +== REST API: Fetch saved conversations + +Use the following endpoint to retrieve a paginated list of saved conversations for the authenticated user. + +=== Endpoint + +---- +GET /api/rest/2.0/ai/agent/conversations +---- + +=== Authentication + +Requires Bearer token authentication. The token must be scoped to the user whose conversation history is being accessed. + +=== Request parameters + +[cols="2,1,1,4"] +|==== +| Parameter | Type | Required | Description + +| `limit` +| integer +| No +| Number of conversations to return per page. Default: `20`. Maximum: `40`. + +| `offset` +| integer +| No +| Pagination offset. Default: `0`. + +| `skip_empty` +| boolean +| No +| When `true`, skips conversations where the user created a thread but did not ask any questions. Default: `true`. +|==== + +// TODO: verify with engineering — confirm whether GET /api/rest/2.0/ai/agent/conversations accepts parameters in the request body or as query parameters + +=== Example request + +[source,bash] +---- +curl -X GET \ + 'https:///api/rest/2.0/ai/agent/conversations?limit=20&offset=0&skip_empty=true' \ + -H 'Authorization: Bearer ' +---- + +=== Example response + +[source,json] +---- +{ + "conversations": [ + { + "conv_id": "yatqmyIIWfCQ", + "title": "Sales by region Q1", + "created_at": "2026-01-21T09:11:05.297252Z", + "updated_at": "2026-01-21T11:16:55.167147Z", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "worksheet_name": "Retail - Apparel", + "active_thread_length": 4 + } + ] +} +---- + +// SOURCE: SCAL-313991, design doc 17cu1O3lQa2-WQsBMwkv0gMGCwAaT5gPfHETQR_5VRcw + +=== Response fields + +[cols="2,1,4"] +|==== +| Field | Type | Description + +| `conv_id` +| string +| Unique identifier for the conversation. Pass this value to SDK host events. + +| `title` +| string +| User-visible title of the conversation. + +| `created_at` +| string (ISO 8601) +| Timestamp when the conversation was created. + +| `updated_at` +| string (ISO 8601) +| Timestamp of the most recent update to the conversation. + +| `worksheet_id` +| string +| GUID of the data source associated with the conversation. + +| `worksheet_name` +| string +| Display name of the associated data source. + +| `active_thread_length` +| integer +| Number of active messages in the conversation thread. +|==== + +== SDK host events + +After fetching the conversation list via the REST API, use the following `SpotterEmbed` host events to load or manage a specific conversation in the embedded interface. + +=== Load a conversation + +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.LoadChat, { chatId: '' }); +---- + +Loads the specified conversation by ID into the embedded Spotter interface. When triggered, Spotter restores the conversation context and the user can continue the session from where they left off. + +[NOTE] +==== +Users can only load their own conversations. Attempting to load another user's conversation returns an error. +==== + +=== Delete a conversation + +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.DeleteChat, { chatId: '' }); +---- + +Deletes the specified conversation by ID. After deletion, the embed emits `EmbedEvent.SpotterConversationDeleted`. Listen to this event to update your external conversation list. + +[source,JavaScript] +---- +spotterEmbed.on(EmbedEvent.SpotterConversationDeleted, (eventData) => { + // Remove the deleted conversation from your host app's list + removeConversationFromList(eventData.data.chatId); +}); +---- + +=== Rename a conversation + +[source,JavaScript] +---- +spotterEmbed.trigger(HostEvent.RenameChat, { + chatId: '', + title: 'New conversation title' +}); +---- + +Renames the specified conversation. After a successful rename, refresh your external conversation list by calling `GET /api/rest/2.0/ai/agent/conversations`. + +// TODO: verify with engineering — confirm whether a SpotterConversationRenamed EmbedEvent is emitted after a successful rename + +== Embed events for conversation lifecycle + +The following embed events are available to keep your host application's conversation list in sync with user actions inside the embedded Spotter interface: + +[cols="2,4"] +|==== +| Event | When emitted + +| `EmbedEvent.SpotterConversationDeleted` +| When a saved conversation is deleted by the user or via `HostEvent.DeleteChat`. + +| `EmbedEvent.SpotterConversationSelected` +| When a saved conversation is selected from the Spotter chat history sidebar. +|==== + +== Complete example: Custom conversation history list + +The following example demonstrates a pattern for rendering a custom conversation history list in the host application and allowing users to continue conversations inside the embedded Spotter interface. + +[source,JavaScript] +---- +import { + SpotterEmbed, + AuthType, + init, + EmbedEvent, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://', + authType: AuthType.TrustedAuthToken, + getAuthToken: () => fetchToken(), +}); + +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + frameParams: { width: '100%', height: '100%' }, + worksheetId: 'auto_mode', +}); + +// Listen for conversation deletion inside the embed +spotterEmbed.on(EmbedEvent.SpotterConversationDeleted, (eventData) => { + refreshConversationList(); // Re-fetch via REST API and update host app UI +}); + +// Listen for conversation selection inside the embed +spotterEmbed.on(EmbedEvent.SpotterConversationSelected, (eventData) => { + highlightConversationInList(eventData.data.chatId); +}); + +spotterEmbed.render(); + +// Load a conversation when the user clicks in the host app's history list +function loadConversation(convId) { + spotterEmbed.trigger(HostEvent.LoadChat, { chatId: convId }); +} + +// Delete a conversation from the host app's history list +function deleteConversation(convId) { + spotterEmbed.trigger(HostEvent.DeleteChat, { chatId: convId }); +} + +// Rename a conversation from the host app's history list +function renameConversation(convId, newTitle) { + spotterEmbed.trigger(HostEvent.RenameChat, { chatId: convId, title: newTitle }); +} + +// Fetch conversation list from the REST API +async function fetchConversations(offset = 0) { + const response = await fetch( + `https:///api/rest/2.0/ai/agent/conversations?limit=20&offset=${offset}&skip_empty=true`, + { + method: 'GET', + headers: { + 'Authorization': `Bearer ${await fetchToken()}`, + }, + } + ); + return response.json(); +} +---- + +== Related topics + +* xref:embed-spotter.adoc[Embed Spotter] +* xref:api-changelog.adoc[Visual Embed SDK changelog] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] diff --git a/modules/ROOT/pages/webhooks-api.adoc b/modules/ROOT/pages/webhooks-api.adoc new file mode 100644 index 000000000..f068a8978 --- /dev/null +++ b/modules/ROOT/pages/webhooks-api.adoc @@ -0,0 +1,469 @@ += Webhook configuration and management via REST APIs +:toc: true +:toclevels: 3 + +:page-title: Manage webhooks +:page-pageid: webhooks-rest-api +:page-description: Create and manage webhooks using Webhook APIs + +The REST API framework is intended for automation and integration scenarios, for example, creating webhooks programmatically or delivering Liveboard report attachments to a cloud storage destination. + +The following webhook REST APIs are available for webhook configuration and management: + +* `POST /api/rest/2.0/webhooks/create` + +Allows xref:webhooks-api.adoc#_creating_a_webhook[creating a webhook] for the Liveboard schedule event type, configuring storage destination for webhook delivery. +* `GET /api/rest/2.0/webhooks/storage-config` + +xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[Gets storage setup information] for configuring customer-managed storage. +* `POST /api/rest/2.0/webhooks/search` + +xref:webhooks-api.adoc#_getting_a_list_of_webhooks[Gets a list of webhooks] configured in the Org. +* `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + +Allows xref:webhooks-api.adoc#_updating_a_webhook[updating configuration properties]. +* `POST /api/rest/2.0/webhooks/delete` + +xref:webhooks-api.adoc#_deleting_a_webhook[Deletes one or more webhooks]. + +== Creating a webhook +To create a webhook for the Liveboard schedule event, send a `POST` request to the +`/api/rest/2.0/webhooks/create` API endpoint. ThoughtSpot allows only one webhook per Org. + +[IMPORTANT] +==== +Before creating a webhook, ensure that a xref:webhooks-comm-channel.adoc[webhook communication channel] is configured for your Org or at the instance level on your instance. +==== + +=== Request parameters + +[width="100%" cols="1,6"] +[options='header'] +|===== +|Parameter|Description +| `name` a|__String__. Name of the webhook. +| `description` + +__Optional__ a|__String__. Description text for the webhook. +| `url` a|__String__. The fully qualified URL of the listening endpoint to which you want to +send webhook notifications. +| `url_params` a|A JSON map of key-value pairs to append as query parameters in the webhook URL. +| `events` a|__Array of strings__. List of events to subscribe to. Specify `LIVEBOARD_SCHEDULE`. +| `status` + +__Optional__ a|__String__. Status of the webhook. Specify `ENABLED` to activate the webhook +immediately, or `DISABLED` to create it in a deactivated state. Available from 26.7.0.cl. +| `authentication` a|Defines the authentication method and credentials ThoughtSpot uses when +sending HTTP requests to the webhook endpoint. + +Specify the authentication type: + +* `API_KEY` + +API key to authorize the payload requests. Specify the API key to use in the `X-API-Key` +request header. +* `BASIC_AUTH` + +Authentication with username and password. +* `BEARER_TOKEN` + +Authentication token to authenticate and authorize requests. +* `OAUTH2` + +OAuth credentials to authorize API requests. Specify client ID, client secret key, and +authorization URL. If the registered webhook has OAuth authentication enabled, +`Authorization: Bearer ` is sent in the request header. +| `signature_verification` + +__Optional__ a|Signature verification parameters for the webhook endpoint to verify the +authenticity of incoming requests. ThoughtSpot signs the webhook payload with a secret, and +your webhook endpoint validates the signature using the shared secret. + +If using signature verification, specify the following parameters: + +* `type` + +Signature verification type. The supported type is `HMAC_SHA256`. +* `header` + +HTTP header where the signature is sent. +* `algorithm` + +Hash algorithm used for signature verification. +* `secret` + +Shared secret used for HMAC signature generation. +| `storage_destination` + +__Optional__ a|Configuration parameters for cloud storage destination. ThoughtSpot supports AWS S3 and Google Cloud Storage (GCS) as storage destinations. For more information, see xref:webhooks-s3-storage.adoc[Deliver Liveboard reports to AWS S3 storage] and xref:webhooks-gcs-storage.adoc[Deliver Liveboard reports to GCS storage]. +|`additional_headers` + +__Optional__ a|__Array of key-value pairs__. Custom HTTP headers to include in every outbound. +Webhook request, in addition to authentication headers and standard HTTP headers such as +`Content-Type` and `User-Agent`. + +[source,JSON] +---- +"additional_headers": [ + { + "key":"X-Custom-Header", + "value":"custom_value" + } +] +---- +| `status` + +__Optional__ a|__String__. Status of the webhook. Specify `ENABLED` to activate the webhook immediately after creation, or `DISABLED` to create it in a deactivated state. When omitted, the status is not stored and will be absent from search results. + +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "name": "webhook-lb-event", + "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", + "events": [ + "LIVEBOARD_SCHEDULE" + ], + "authentication": { + "BEARER_TOKEN": "Bearer {AUTH_TOKEN}" + }, + "description": "Liveboard report" +}' +---- + +=== API response + +If webhook creation is successful, the API returns a 204 response code. + +== Retrieving storage information for webhook configuration +To get storage setup information for your ThoughtSpot instance required for configuring a webhook storage destination, use the `GET /api/rest/2.0/webhooks/storage-config` API. + +=== Example request + +[source, cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/storage-config' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ +---- + +=== API response + +This API endpoint returns data based on whether the ThoughtSpot instance is hosted on AWS or GCP. + +* For AWS hosted S3 storage, the API endpoint returns a JSON array with platform AWS account ID, IAM trust policy template, and storage setup instructions. +* For GCP-hosted S3 storage, the API endpoint returns a JSON array with +* For GCP-hosted GCS storage, the endpoint returns is a JSON array with the platform GCP service account email, the IAM role to grant for service account impersonation, and storage setup instructions. + +==== Top-level fields +The following fields are included in the response, regardless of the storage provider. + +* `storage_type`: The category of storage destination. This field is always `OBJECT_STORAGE` for blob/bucket storage targets, including both AWS S3 and Google Cloud Storage. +* `provider`: Cloud storage service provider. Returns one of the following values: + +** `AWS_S3` for Amazon S3 bucket + +** `GCP_GCS` for Google Cloud Storage bucket + +* `config`: A configuration object that contains the provider-specific setup details for the storage destination. The structure of this object varies based on the `config_type` field within it. The `config_type` can be one of the following values: +** `AWS_TO_S3_STORAGE`: AWS-hosted ThoughtSpot instance writing to an S3 bucket +** `GCP_TO_S3_STORAGE`: GCP-hosted ThoughtSpot instance writing to an S3 bucket +** `GCP_TO_GCS_STORAGE`: GCP-hosted ThoughtSpot instance writing to a GCS bucket + +==== Storage configuration attributes for AWS_TO_S3_STORAGE +The response returned for AWS-hosted ThoughtSpot instances where the customer configures an AWS S3 bucket as the storage destination includes the following information: + +* `aws_account_id`: The AWS account ID of the ThoughtSpot-managed AWS account. You must reference this value in the `Principal` field of the IAM trust policy you create in your AWS account. The policy grants ThoughtSpot's account permission to assume the IAM role that has write access to your S3 bucket. +* `trust_policy_template`: A ready-to-use IAM trust policy JSON object. Attach this policy to the IAM role you create in your AWS account. The policy authorizes ThoughtSpot's AWS account (`aws_account_id`) to call `sts:AssumeRole` and deliver webhook payloads to your S3 bucket. The `sts:ExternalId` condition in the policy prevents unauthorized cross-account access (confused deputy attack). +** `Version`: The IAM policy language version,`2012-10-17`. +** `Statement`: Includes the following information: +** `Effect`: Specifies whether the statement grants or denies access. Always `Allow` in this template. +*** `Principal`: The ARN of the ThoughtSpot AWS account principal that is trusted to assume your IAM role. Constructed as `arn:aws:iam:::root`. +*** `Action`: The AWS STS action being permitted. Always `sts:AssumeRole` for AWS-hosted instances. +*** `Condition`: A unique, ThoughtSpot-generated external ID. Include this value as a condition in your IAM trust policy to prevent unauthorized parties from assuming your role. This value is unique per webhook and must be preserved exactly as returned. For example: ++ +[source,JSON] +---- +"StringEquals": { + "sts:ExternalId": "ts-webhook-a1b2c3d4-7890" +} +---- + +* `setup_instructions`: An ordered list of steps to complete in your AWS account before using this storage destination. Follow these steps to create the IAM role, attach the trust policy, and configure the required S3 permissions (`s3:PutObject`, `s3:PutObjectAcl`). + +===== Example response + +[source,JSON] +---- +[ + { + "storage_type": "OBJECT_STORAGE", + "provider": "AWS_S3", + "config": { + "config_type": "AWS_TO_S3_STORAGE", + "aws_account_id": "123456789012", + "trust_policy_template": { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::123456789012:root" + }, + "Action": "sts:AssumeRole", + "Condition": { + "StringEquals": { + "sts:ExternalId": "ts-webhook-a1b2c3d4-7890" + } + } + } + ] + }, + "setup_instructions": [ + "1. Create an IAM role in your AWS account", + "2. Attach the trust policy template to the role", + "3. Attach S3 permissions (s3:PutObject, s3:PutObjectAcl) to the role", + "4. Use the role ARN in your webhook storage configuration" + ] + } + } +] +---- + +==== Storage configuration attributes for GCP_TO_S3_STORAGE +This response returned for GCP-hosted ThoughtSpot instances where the customer configures an AWS S3 bucket as the storage destination includes the following attributes. + +* `gcp_service_account_id`: The unique numeric ID of the ThoughtSpot GCP service account. This ID is used as the OIDC subject (`sub`) in the AWS IAM web identity trust policy condition, scoping the trust to exactly this service account. Use this value when configuring the `accounts.google.com:sub` condition in your IAM role's trust policy. + +* `oidc_provider`: The OIDC identity provider URL that AWS IAM uses to validate the identity token presented by ThoughtSpot's GCP service account. Always `accounts.google.com` for GCP-hosted instances. Register this URL as an Identity Provider in your AWS IAM account before creating the trust policy. + +* `trust_policy_template`: A ready-to-use IAM trust policy JSON object for web identity federation. Attach this policy to the IAM role you create in your AWS account. The policy trusts the GCP-hosted OIDC provider (`accounts.google.com`) and restricts assumption to the specific ThoughtSpot GCP service account identified by `gcp_service_account_id`. Includes the following attributes: + +** `Version`: The IAM policy language version,`2012-10-17`. +** `Statement`: Array of IAM policy statements. Contains one statement that permits the ThoughtSpot GCP service account to assume the IAM role via OIDC federation. +*** `Effect`: Specifies whether the statement grants or denies access. Always `Allow` in this template. +*** `Principal`: The ARN of the OIDC identity provider registered in your AWS IAM account. Replace `YOUR_AWS_ACCOUNT_ID` in the template with your own AWS account ID before applying the policy. +*** `Action`: ThoughtSpot uses AWS STS `AssumeRoleWithWebIdentity` (OIDC federation) to obtain temporary credentials. No long-lived AWS access keys are stored or exchanged. +*** `Condition`: The OIDC subject condition that scopes the trust to the specific ThoughtSpot GCP service account. This value matches `gcp_service_account_id`. Including this condition ensures that only ThoughtSpot's service account, not any other GCP principal, can assume your IAM role. ++ +[source,JSON] +---- +"StringEquals": { + "accounts.google.com:sub": "115663769112811637952" +} +---- + +* `config.setup_instructions`: An ordered list of steps to complete in your AWS account before using this storage destination. Follow these steps to register the OIDC provider, create the IAM role with web identity federation trust, and configure the required S3 permissions (`s3:PutObject`, `s3:PutObjectAcl`). + +===== Example response +[source,JSON] +---- +[ + { + "storage_type": "OBJECT_STORAGE", + "provider": "AWS_S3", + "config": { + "config_type": "GCP_TO_S3_STORAGE", + "gcp_service_account_id": "115663769112811637952", + "oidc_provider": "accounts.google.com", + "trust_policy_template": { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/accounts.google.com" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "accounts.google.com:sub": "115663769112811637952" + } + } + } + ] + }, + "setup_instructions": [ + "1. Add accounts.google.com as an Identity Provider in AWS IAM", + "2. Create an IAM role with Web Identity Federation trust", + "3. Configure the trust policy with the GCP service account ID", + "4. Attach S3 permissions (s3:PutObject, s3:PutObjectAcl) to the role", + "5. Use the role ARN in your webhook storage configuration" + ] + } + } +] +---- + +==== Storage configuration attributes for GCP_TO_GCS_STORAGE +The storage information is returned for GCP-hosted ThoughtSpot instances where the customer configures a Google Cloud Storage (GCS) bucket as the storage destination. ThoughtSpot's service account is granted the `roles/iam.serviceAccountTokenCreator` role on the customer's service account, which allows it to generate short-lived tokens and write to the GCS bucket on the customer's behalf. + +* `service_account_email`: The email address of the ThoughtSpot GCP service account that the customer must grant access to. Grant this service account the `roles/iam.serviceAccountTokenCreator` role on the service account that has write access to your GCS bucket. This allows ThoughtSpot to impersonate that service account and deliver webhook payloads to the bucket. +* `required_role`: The GCP IAM role that must be granted to ThoughtSpot's service account (`service_account_email`) on your bucket-owning service account. Always `roles/iam.serviceAccountTokenCreator`. This role allows ThoughtSpot to create short-lived identity tokens for the impersonated service account without requiring the service account key to be shared. +* `setup_instructions`: An ordered list of steps to complete in your GCP project before using this storage destination. Follow these steps to locate your bucket-owning service account, grant the `roles/iam.serviceAccountTokenCreator` role to ThoughtSpot's service account, and configure the GCS bucket in your webhook settings. + + +===== Example response + +[source,json] +---- +[ + { + "storage_type": "OBJECT_STORAGE", + "provider": "GCP_GCS", + "config": { + "config_type": "GCP_TO_GCS_STORAGE", + "service_account_email": "webhook-sa@example-project.iam.gserviceaccount.com", + "required_role": "roles/iam.serviceAccountTokenCreator", + "setup_instructions": [ + "1. In GCP Console, go to IAM & Admin > Service Accounts", + "2. Click on the service account that has write access to your GCS bucket", + "3. Open the 'Principals with access' tab and click 'Grant Access'", + "4. Enter the service account email as the principal", + "5. Assign the roles/iam.serviceAccountTokenCreator role and save", + "6. Use your service account email in the webhook storage configuration" + ] + } + } +] +---- + +== Getting a list of webhooks +To view the properties of a webhook or get a list of webhooks configured on your instance, send a `POST` request to the `/api/rest/2.0/webhooks/search` API endpoint. + +By default, the API fetches a list of all webhooks available on the ThoughtSpot instance. To fetch webhooks created in a specific Org, specify the Org ID. + +To get the details of specific webhook, specify the webhook ID in the API request. + +To filter results by the Webhook status, specify `ENABLED` or `DISABLED` in the `status` parameter as needed. + +=== Example request + +The following example shows the request body to fetch details of an active webhook: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "org_identifier": "Primary", + "webhook_identifier": "27997a8a-cd33-485d-a039-b40b71d191a8", + "event_type": "LIVEBOARD_SCHEDULE" + "status": "ENABLED" +}' +---- + +=== API response + +If the request is successful, the API returns details of the webhook: + +[source,JSON] +---- +{ + "webhooks":[ + { + "id":"27997a8a-cd33-485d-a039-b40b71d191a8", + "name":"UserA", + "description":null, + "org":{ + "id":"0", + "name":"Primary" + }, + "url":"https://webhook-test-server-263n.onrender.com/", + "url_params":null, + "events":[ + "LIVEBOARD_SCHEDULE" + ], + "authentication":null, + "signature_verification":null, + "additional_headers":null, + "creation_time_in_millis":1773824614455, + "modification_time_in_millis":1781070122709, + "created_by":{ + "id":"4e6e5692-667e-487d-9672-f301ccc2ea77", + "name":"UserA@thoughtspot.com" + }, + "last_modified_by":{ + "id":"826b21a7-8ea2-4af9-b0bd-d1d6b604d07d", + "name":"UserA@thoughtspot.com" + }, + "storage_destination": null, + "status":"ENABLED" + } + ], + "pagination":{ + "record_offset":0, + "record_size":50, + "total_count":1, + "has_more":false + } +} +---- + +== Updating a webhook +To update a webhook, send a `POST` request to the +`/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint. In the update request, include the webhook ID as a path parameter and the properties to modify in the request body. + +To update existing configuration, specify the following parameters in the API request as needed: + +* `name`: Name of the webhook. +* `description`: Description text. +* `url`: Webhook endpoint URL. +* `events`: Event type that initiates the webhook delivery. +* `url_params`: Key-value pairs for the URL query parameters. +* `authentication`: Authentication type to use for authorizing webhook requests. +* `signature-verification`: Signature verification type. +* `storage_destination`: Storage configuration parameters for webhook delivery. +* `additional_headers`: Custom headers to include in the request. +* `status`: Activation state of the webhook. Specify `ENABLED` or +`DISABLED`. + +To reset configured values, specify properties to reset in `reset_options`.The `reset_options` attribute removes one or more optional configuration sections from the webhook without replacing the entire configuration. Supported values are: + +* `AUTHENTICATION`: Removes the authentication configuration. +* `SIGNATURE_VERIFICATION`: Removes the signature verification configuration. +* `STORAGE_DESTINATION`: Removes the storage destination configuration. + +=== Example request +The following example shows the request body for updating the name, description text, endpoint URL, and storage properties of a webhook object: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/09e069e2-fc42-4354-9b46-cc96984c4f30/update' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "name": "test-webhook", + "status": "DISABLED", + "reset_options": [ + "AUTHENTICATION" + ] +}' +---- + +=== API response + +If the API request is successful, the API returns a 204 response code indicating a successful operation. + +== Deleting a webhook + +To delete a webhook, send a `POST` request to the `/api/rest/2.0/webhooks/delete` API endpoint with the webhook IDs in the request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/delete' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "webhook_identifiers": [ + "09e069e2-fc42-4354-9b46-cc96984c4f30" + ] +}' +---- + +=== API response + +If the API request is successful, the API returns the 200 response with the details of the deleted webhook. + +== Related resources +* xref:webhooks-comm-channel.adoc[Configure webhook communication channels] +* xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an external application] +* xref:webhooks-s3-storage.adoc[AWS S3 storage integration for webhook delivery] +* xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery] +* xref:webhooks-ux.adoc[Webhook configuration and management in the UI] diff --git a/modules/ROOT/pages/webhooks-gcs-storage.adoc b/modules/ROOT/pages/webhooks-gcs-storage.adoc new file mode 100644 index 000000000..0a8fe6db6 --- /dev/null +++ b/modules/ROOT/pages/webhooks-gcs-storage.adoc @@ -0,0 +1,149 @@ += GCS storage integration for webhook delivery +:toc: true +:toclevels: 2 + +:page-title: GCS storage for webhooks +:page-pageid: webhooks-gcs-storage +:page-description: Configure a Google Cloud Storage bucket to receive ThoughtSpot webhook payloads on GCP clusters. + +// SOURCE: SCAL-301399, SCAL-304083, SCAL-310002 + +ThoughtSpot supports delivering webhook payloads directly to a **Google Cloud Storage (GCS) bucket** on GCP-hosted clusters. This allows you to capture and retain webhook event data — such as KPI Monitor alerts — without requiring a publicly reachable HTTP endpoint. + +[NOTE] +==== +GCS storage integration for webhooks is available for GCP-hosted ThoughtSpot clusters only. For AWS clusters, see xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery]. +==== + +== Before you begin + +Before configuring GCS storage for webhooks, ensure that: + +* Your ThoughtSpot instance is hosted on GCP. +* You have a GCS bucket in the same GCP project or a project that allows cross-project IAM bindings. +* You have administrative access to your ThoughtSpot instance. +* The *Webhooks* feature is enabled on your cluster. Contact ThoughtSpot Support if it is not enabled. + +== Step 1: Retrieve the ThoughtSpot GCP Service Account + +ThoughtSpot uses a managed GCP Service Account to write objects to your GCS bucket. You must grant this service account the appropriate IAM role on your bucket before webhook delivery can begin. + +Use the storage config REST API endpoint to retrieve the GCP Service Account email address: + +[source,bash] +---- +curl -X GET \ + 'https:///api/rest/2.0/webhooks/storage/config' \ + -H 'Authorization: Bearer ' +---- + +// TODO: verify with engineering — confirm the exact endpoint path for the get storage config API + +The response returns the GCP Service Account email in the following format: + +[source,json] +---- +{ + "gcp_service_account": "ts-webhook-@.iam.gserviceaccount.com" +} +---- + +// TODO: verify with engineering — confirm the exact response field names for GCP Service Account details + +== Step 2: Grant IAM permissions on your GCS bucket + +In the GCP Console or using the `gcloud` CLI, grant the ThoughtSpot service account the *Storage Object Creator* role on your GCS bucket: + +[source,bash] +---- +gcloud storage buckets add-iam-policy-binding gs:// \ + --member="serviceAccount:" \ + --role="roles/storage.objectCreator" +---- + +[NOTE] +==== +ThoughtSpot requires write-only access to deliver payloads. The *Storage Object Creator* role is sufficient and follows the principle of least privilege. +==== + +== Step 3: Configure a webhook with GCS storage + +Use the REST API to create or update a webhook, specifying your GCS bucket as the storage destination. + +=== Create a webhook with GCS storage + +[source,bash] +---- +curl -X POST \ + 'https:///api/rest/2.0/webhooks/create' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "name": "my-gcs-webhook", + "storage_config": { + "storage_type": "GCS", + "bucket_name": "", + "object_prefix": "thoughtspot-webhooks/" + } + }' +---- + +// TODO: verify with engineering — confirm the exact request body schema for GCS storage_config, including all required and optional fields, and whether a URL field is required when GCS storage is used + +=== Update an existing webhook to use GCS storage + +[source,bash] +---- +curl -X PUT \ + 'https:///api/rest/2.0/webhooks//update' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "storage_config": { + "storage_type": "GCS", + "bucket_name": "", + "object_prefix": "thoughtspot-webhooks/" + } + }' +---- + +// TODO: verify with engineering — confirm the update endpoint path and request body schema + +== Webhook payload format in GCS + +ThoughtSpot writes each webhook event as a separate object in your GCS bucket. Objects are named using the following pattern: + +---- +//-.json +---- + +// TODO: verify with engineering — confirm the object naming convention and payload format for GCS deliveries + +== Verify delivery + +To verify that ThoughtSpot is delivering webhooks to your GCS bucket: + +. In the GCP Console, navigate to your bucket and check for new objects. +. Review the object content to confirm the payload matches the expected schema. + +== Troubleshoot + +[cols="2,3"] +|==== +| Issue | Resolution + +| Objects are not appearing in the bucket +| Verify that the ThoughtSpot service account has the `roles/storage.objectCreator` IAM binding on the bucket. + +| `permission denied` error in webhook logs +| The service account may have been rotated. Retrieve the current service account email using the storage config API and re-grant IAM permissions. + +| Webhook is configured but not triggering +| Verify that the webhook is enabled and that the associated KPI Monitor alert condition is met. Contact ThoughtSpot Support if the issue persists. +|==== + +== Related topics + +* xref:webhooks-s3-storage.adoc[Amazon S3 storage integration for webhook delivery] +* xref:webhooks.adoc[Webhooks for KPI Monitor alerts] +* xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog] diff --git a/modules/ROOT/pages/webhooks-kpi-alerts.adoc b/modules/ROOT/pages/webhooks-kpi-alerts.adoc index 2df9a283b..2ee5bb568 100644 --- a/modules/ROOT/pages/webhooks-kpi-alerts.adoc +++ b/modules/ROOT/pages/webhooks-kpi-alerts.adoc @@ -27,31 +27,9 @@ The webhooks feature is in Beta and is turned off by default. To enable this fea == Configure webhooks To configure a webhook and send alert data to the destination URL, complete the following steps: -* xref:webhooks.adoc#_register_a_webhook[Register a webhook in ThoughtSpot] +* xref:webhooks-ux.adoc#_creating_a_webhook_for_kpi_alerts[Create a webhook in ThoughtSpot] * xref:webhooks.adoc#_assign_webhook_to_a_kpi_monitor_alert[Assign the registered webhook to KPI Monitor alerts] -=== Register a webhook - -To register a webhook in ThoughtSpot, complete the following steps: - -. Go to **Develop** > **Customizations** > **Webhooks**. -. Click **Create Webhook**. -. In the ** Create Webhook** modal, specify the Webhook name and the URL of the destination application. -+ -For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank]. -. Specify the authentication type. -* No authentication + -Default authentication option. Not recommended for production environments. - -* API Key + -Allows using an API key to authenticate API requests to the destination URL. Specify the API key to use in the `X-API-Key` request header. - -* OAuthentication 2.0 + -Allows using OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. -If the registered webhook has Oauth authentication enabled, `Authorization: Bearer ` is sent in the request header. -. If the destination URL requires query parameters to be passed in the request URL, specify the parameters as key-value pairs. -. Click **Save**. - === Assign webhook to a KPI Monitor alert To assign the registered webhook to an alert: diff --git a/modules/ROOT/pages/webhooks-lb-schedule.adoc b/modules/ROOT/pages/webhooks-lb-schedule.adoc index 9f4a1dd44..ecb3c8bd5 100644 --- a/modules/ROOT/pages/webhooks-lb-schedule.adoc +++ b/modules/ROOT/pages/webhooks-lb-schedule.adoc @@ -1,33 +1,13 @@ -= Deliver Liveboard reports to an external application += Delivering reports to external destination via webhooks :toc: true :toclevels: 3 :page-title: Webhooks for Liveboard Scheduled Jobs :page-pageid: webhooks-lb-schedule -:page-description: Configure Webhooks and send alerts to specific communication channels - -[beta betaBackground]^Beta^ - -By configuring a webhook, users can send notifications automatically to a target application whenever a scheduled Liveboard job is triggered in ThoughtSpot. - -[NOTE] -==== -* Webhook support for Liveboard schedule events is available only on ThoughtSpot Cloud instances with 10.14.0.cl or later. The webhook feature is currently in beta and not enabled by default. To enable this feature on your instance, contact ThoughtSpot Support. -* You can configure only one webhook for the Liveboard schedule event per Org. -==== - -== Overview +:page-description: Configure a webhook to deliver scheduled Liveboard reports to an external application or cloud storage destination If you have scheduled a Liveboard job to receive a daily report via email, you can configure ThoughtSpot to send the report directly to a webhook endpoint and create your own custom emails or workflows. -* Configure a webhook for the Liveboard schedule event to enable programmatic communication between the target application and ThoughtSpot. + -To create and manage webhook APIs, use the following APIs: -** `POST /api/rest/2.0/webhooks/create` -** `POST /api/rest/2.0/webhooks/delete` -** `POST /api/rest/2.0/webhooks/search` -** `POST /api/rest/2.0/webhooks/{webhook_identifier}/update` - - == Before you begin Check your application environment for the following prerequisites: @@ -37,25 +17,24 @@ If your instance has Role-based Access Control (RBAC) enabled, you need the foll ** `APPLICATION_ADMINISTRATION` (*Can Manage Application settings*) to create and view communication channels. ** `CAN_MANAGE_WEBHOOKS` (*Can manage webhooks*) to create and manage webhooks. * Ensure that a xref:webhooks-comm-channel.adoc[webhook communication channel] is configured for your Org or at the cluster level on your instance. -//* To allow outbound traffic from ThoughtSpot to the webhook endpoint, add the webhook destination URL to the xref:security-settings.adoc#csp-connect-src[CSP connect-src] allowlist in ThoughtSpot. * Ensure that your destination application has a callback URL to accept HTTP POST requests from ThoughtSpot. * If you plan to use OAuth authentication, make sure you have the OAuth credentials and authorization URL of your application. * If you plan to use an API key for authentication, ensure that you have a valid API key. == Configuration steps - The webhook setup for Liveboard schedule events includes the following steps: -* xref:webhooks-lb-schedule.adoc#_configure_a_webhook[Creating a webhook to listen to Liveboard schedule events]. -* xref:webhooks-lb-schedule.adoc#_verify_the_integration[Verifying the integration and webhook payload]. - -== Configure a webhook - -To configure webhooks for the Liveboard schedule event, use the webhook REST API. +. xref:webhooks-lb-schedule.adoc#configure-webhook[Configure a webhook] to listen to Liveboard +schedule events. +. xref:webhooks-lb-schedule.adoc#verify-integration[Verify the integration] and webhook payload. -=== Create a webhook +[#configure-webhook] +== Configuring a webhook +You can create and manage webhooks using the new Webhooks page in the UI or via Webhook REST APIs. -To create a webhook for the Liveboard schedule event, send a `POST` request to the `/api/rest/2.0/webhooks/create` API endpoint. ThoughtSpot allows only one webhook per Org. +=== Through REST API +To create a webhook for the Liveboard schedule event, send a `POST` request to the +`/api/rest/2.0/webhooks/create` API endpoint. ThoughtSpot allows only one webhook per Org. ==== Request parameters @@ -66,33 +45,35 @@ To create a webhook for the Liveboard schedule event, send a `POST` request to t | `name` a|__String__. Name of the webhook. | `description` + __Optional__ a|__String__. Description text for the webhook. -| `url` a|__String__. The fully qualified URL of the listening endpoint to which you want to send webhook notifications. -| `url_params` a| A JSON map of key-value pairs to append as query parameters in the webhook URL. -| `events` a|__Array of strings__. List of events to subscribe to. Specify the event as `LIVEBOARD_SCHEDULE`. -| `authentication` a| +| `url` a|__String__. The fully qualified URL of the listening endpoint to which you want to +send webhook notifications. +| `url_params` a|A JSON map of key-value pairs to append as query parameters in the webhook URL. +| `events` a|__Array of strings__. List of events to subscribe to. Specify `LIVEBOARD_SCHEDULE`. +| `authentication` a|Defines the authentication method and credentials ThoughtSpot uses when +sending HTTP requests to the webhook endpoint. -Defines authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint. - -Specify the authentication type. +Specify the authentication type: * `API_KEY` + -API key to authorize the payload requests. Specify the API key to use in the `X-API-Key` request header. +API key to authorize the payload requests. Specify the API key to use in the `X-API-Key` +request header. * `BASIC_AUTH` + -Authentication methods with username and password. +Authentication with username and password. * `BEARER_TOKEN` + Authentication token to authenticate and authorize requests. * `OAUTH2` + -OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. -If the registered webhook has OAuth authentication enabled, `Authorization: Bearer ` is sent in the request header. +OAuth credentials to authorize API requests. Specify client ID, client secret key, and +authorization URL. If the registered webhook has OAuth authentication enabled, +`Authorization: Bearer ` is sent in the request header. | `signature_verification` + -__Optional__ a| Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests. This typically involves ThoughtSpot signing the webhook payload with a secret, and your webhook endpoint validating this signature using the shared secret. - +__Optional__ a|Signature verification parameters for the webhook endpoint to verify the +authenticity of incoming requests. ThoughtSpot signs the webhook payload with a secret, and +your webhook endpoint validates the signature using the shared secret. -If using signature verification, specify the following parameters. +If using signature verification, specify the following parameters: * `type` + -Signature verification type. Supported type is `HMAC_SHA256`, which uses Hash-based Message Authentication Code (HMAC) algorithm with the SHA-256 hash function to generate a cryptographic signature for webhook payloads. When configured, ThoughtSpot will sign the webhook payload using a shared secret and the HMAC_SHA256 algorithm. Your receiving endpoint should use the same secret and algorithm to compute the HMAC of the received payload and compare it to the signature sent by ThoughtSpot. - +Signature verification type. The supported type is `HMAC_SHA256`. * `header` + HTTP header where the signature is sent. * `algorithm` + @@ -100,11 +81,17 @@ Hash algorithm used for signature verification. * `secret` + Shared secret used for HMAC signature generation. | `storage_destination` + -__Optional__ | Configuration parameters for the S3 storage destination. For more information, see xref:webhooks-s3-storage.adoc[Deliver content to AWS S3 storage using webhooks]. +__Optional__ a|Configuration parameters for the cloud storage destination. ThoughtSpot supports +AWS S3 and GCP GCS as storage destinations. For more information, see +xref:webhooks-s3-storage.adoc[Deliver Liveboard reports to AWS S3 storage] and +xref:webhooks-gcs-storage.adoc[Deliver Liveboard reports to GCS storage]. +| `status` + +__Optional__ a|__String__. Status of the webhook. Specify `ENABLED` to activate the webhook +immediately, or `DISABLED` to create it in a deactivated state. Available from 26.7.0.cl. |`additional_headers` + -__Optional__ a|__Array of key-value pairs__. Allows including custom HTTP headers in every outbound webhook HTTP request that ThoughtSpot sends to the configured destination URL. When configured, ThoughtSpot sends these headers in addition to the authentication headers and standard HTTP headers such as `Content-Type`, `User-Agent`. - -You can use this parameter to pass arbitrary headers with custom metadata in key-value pairs, as required by the webhook receiver endpoint: +__Optional__ a|__Array of key-value pairs__. Custom HTTP headers to include in every outbound +webhook request, in addition to authentication headers and standard HTTP headers such as +`Content-Type` and `User-Agent`. [source,JSON] ---- @@ -118,7 +105,6 @@ You can use this parameter to pass arbitrary headers with custom metadata in key |===== ==== Example request -The following example shows the request body for creating a webhook: [source,cURL] ---- @@ -141,243 +127,87 @@ curl -X POST \ ---- ==== Example response - If webhook creation is successful, the API returns a 204 response code. -=== View webhook properties - -To view the properties of a webhook or get a list of webhooks configured on your ThoughtSpot instance, send a `POST` request to the `/api/rest/2.0/webhooks/search` API endpoint. - -To get specific information, define the following parameters. If the API request is sent without parameters in the request body, ThoughtSpot returns the webhooks configured for the Org context in ThoughtSpot. - -==== Request parameters - -[width="100%" cols="2,4"] +=== Through the Webhooks page in UI +If the new Webhooks page is enabled on your instance, you can create a webhook via UI. + +==== Creating a webhook +To add a webhook for the Liveboard schedule events: + +. Go to **Develop** > **Customizations** and click **Webhooks**. +. In the *Webhooks* page, click *Create webhook*. +. In the *Create webhook* modal, configure the following: +* *Name*: A display name for the webhook. +* *URL*: The fully qualified HTTPS URL of the endpoint that will receive webhook payloads. +* *Description*: (optional) A short description of the webhook's purpose. +* *Event type*: Specify the ThoughtSpot event types to subscribe to. Ensure that *Liveboard schedule* is set as the event type. +. Configure the authentication method your destination endpoint requires. + +ThoughtSpot sends the configured credentials in every outbound request. The following options are available: +* *No Authentication*: No authentication headers are added to the request. Not recommended for production use. +* *OAuth 2.0*: ThoughtSpot obtains an access token using your OAuth client ID, client secret, and authorization URL, then sends `Authorization: Bearer ` in the request header. The token is refreshed automatically before expiry. +* *API Key*: ThoughtSpot sends the API key in the `X-API-Key` request header. +* *Bearer Token*: ThoughtSpot sends a static bearer token in the `Authorization: Bearer` header. +* *Basic authentication*: ThoughtSpot sends a Base64-encoded username and password in the `Authorization` header. +. Configure the file storage options. For more information, see xref:webhooks-s3-storage.adoc[AWS S3 storage integration for webhook delivery] and xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery]. +. Configure the advanced settings if required: +* *Signature verification* + +Specify the signature to send in the header for your endpoint to verify each request. Configure HMAC-SHA256 payload signing. ThoughtSpot signs each outbound +payload with a shared secret. Your endpoint can use the same secret and algorithm to verify the signature in the incoming request header. +* *Custom headers* + +Use this feature to pass arbitrary metadata required by your endpoint in addition to standard and authentication headers. Define key-value pairs of custom headers to add to every outbound HTTP request. +* *URL parameters*: +Specify the query parameters to append to the webhook URL on every request. +. Click *Save*. + +If the webhook creation is successful, it will be added to table list in the Webhooks page. + +==== Activating a webhook +To activate the webhook, use one of the following options: +* Select the webhook and click *Enable*. +* In the webhook row, from the More options menu (`...`), click **Enable*. + +[#test-webhook] +== Test a webhook + +Testing a webhook sends a synthetic payload to the configured endpoint to verify connectivity and +authentication. + +. Hover over the webhook row and click the actions menu (*...*). +. Select *Test*. +. Review the result in the *Test Event* modal. + +The modal displays one of the following outcomes: + +[width="100%" cols="1,4"] [options='header'] |===== -|Parameter|Description -| `org_identifier` + -__Optional__ |__String__. ID or name of the Org. -| `webhook_identifier` + -__Optional__ | __String__. ID or name of the webhook. -| `event_type` + -__Optional__| __String__. Type of webhook event to filter by. For Liveboard schedule events, specify `LIVEBOARD_SCHEDULE`. -|Pagination settings a| If fetching multiple records, specify the following parameters to paginate the API response: + - -* `record_offset` + -__Integer__. Specifies the starting point (index) from which records should be returned. Default is 0. -* `record_size` + -__Integer__. Specifies the number of records to return in the response. Default is 50. -| `sort_options` + -__Optional__ a| Enables sorting of the API response by a specific field in ascending or descending order. - -To define a sorting criteria for the webhook records in API response, set the `field_name` to one of the following options: - -* `CREATED` + -Sorts the records by the webhook creation timestamp. -* `MODIFIED` + -Sorts the webhook object by the last modified timestamp. -* `NAME` + -Sorts the records alphabetically. - -To specify the sort order, set `order` to `ASC` for ascending order, or `DESC` for descending order. - -For example: - -[source,JSON] ----- -"sort_options": { - "field_name":"CREATED", - "order":"ASC" -} ----- +|Outcome|Description +|*Success*|The endpoint returned an HTTP 2xx response within the timeout window. +|*Authentication error*|The endpoint rejected the request due to invalid or missing credentials. +|*Timeout*|The endpoint did not respond within the allowed time window. +|*4xx error*|The endpoint returned a client error (for example, 400 Bad Request or 404 Not Found). +|*5xx error*|The endpoint returned a server error. |===== -==== Example request - -The following example shows the request body to fetch webhook properties: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/search' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "org_identifier": "testOrg1", - "event_type": "LIVEBOARD_SCHEDULE" -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot returns the webhook configuration details: - -[source,JSON] ----- -{ - "webhooks":[ - { - "id":"27997a8a-cd33-485d-a039-b40b71d191a8", - "name":"webhook-lb-event", - "description": "Webhook for Liveboard schedule", - "org":{ - "id":"2100019165", - "name":"testOrg1" - }, - "url":"https://webhook-test-server-263n.onrender.com/", - "url_params":null, - "events":[ - "LIVEBOARD_SCHEDULE" - ], - "authentication":null, - "signature_verification":null, - "additional_headers":null, - "creation_time_in_millis":1773824614455, - "modification_time_in_millis":1773824614455, - "created_by":{ - "id":"4e6e5692-667e-487d-9672-f301ccc2ea77", - "name":"UserA@example.com" - }, - "last_modified_by":null, - "storage_destination":null - } - ], - "pagination":{ - "record_offset":0, - "record_size":50, - "total_count":1, - "has_more":false - } -} ----- - -=== Update the properties of a webhook - -To update the name, description text, endpoint URL, or the authentication settings of a webhook object, send a `POST` request to the `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint. - -==== Request parameters - -Specify the `webhook_identifier` and pass it as a path parameter in the request URL. - -The API operation allows you to update the following webhook properties: - -* `name` + -Name of the webhook. -* `description` + -Description text of the webhook. -* `url` + -The URL of the webhook endpoint. -* `url_params` + -Query parameters to append to the endpoint URL. -* `events` + -Events subscribed to the webhook. In the current release, ThoughtSpot supports only the `LIVEBOARD_SCHEDULE` event. -* `authentication` + -Authentication method and credentials that ThoughtSpot will use when sending HTTP requests to the webhook endpoint. -* `signature_verification` + -Signature verification parameters for the webhook endpoint to verify the authenticity of incoming requests. -* `additional_headers` + -Optional and custom HTTP headers in the webhook request triggered by ThoughtSpot. - -==== Example request - -The following example shows the request body for updating the name, description text, and endpoint URL of a webhook object: - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/webhook-lb-test/update' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "name": "webhook-lb-event", - "description": "Webhook for Liveboard schedule event", - "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d/2e5251b2-8274-41f6-80a0-1b82854df31f", - "events": [ - "LIVEBOARD_SCHEDULE" - ] -}' ----- - -==== Example response - -If the API request is successful, the API returns a 204 response code indicating a successful operation. - +[#verify-integration] == Verify the integration -To verify the webhook configuration, send an API request to the `/api/rest/2.0/system/communication-channels/validate` API endpoint and check the connection status. - -If the validation returns errors, verify the configuration and xref:webhooks-lb-schedule.adoc#_update_the_properties_of_a_webhook[update the webhook properties]. +After creating a webhook, verify the configuration using one of the following methods: -If the connection status is successful, trigger a webhook delivery to the configured destination and xref:webhooks-payload.adoc[verify the payload]. +=== Use the test event feature +On the *Webhooks* page in the *Develop* tab, hover over the webhook row, click the actions +menu (*...*), and select *Test*. ThoughtSpot sends a synthetic payload to the configured +endpoint. For more information, see xref:webhooks-manage.adoc#test-webhook[Test a webhook]. -//For testing purposes, you can use a URL from link:https://webhook.site/[Webhook.site^] as a webhook endpoint and check the payload when the Liveboard schedule event is triggered. +=== Trigger a Liveboard schedule -== Monitor webhook delivery status -To monitor the webhook delivery and job status, use the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. For more information, see xref:webhooks-comm-channel.adoc#_monitor_webhook_delivery_and_job_status[Monitor webhook delivery and job status]. +After the webhook is configured, ThoughtSpot delivers a payload to the webhook endpoint +whenever a Liveboard schedule job runs. You can verify delivery in the *Logs* tab on the +*Webhooks* page, or by checking your receiving endpoint directly. -== Delete a webhook -To delete a webhook, send a `POST` request with the webhook ID to the `/api/rest/2.0/webhooks/delete` API endpoint. - -=== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/webhooks/delete' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "webhook_identifiers": [ - "webhook-lb-test" - ] -}' ----- - -=== Example response - -If the API request is successful, the webhook is deleted, and the API returns the details of the deleted webhook in the response body. - -[source,JSON] ----- -{ - "deleted_count": 1, - "failed_count": 0, - "deleted_webhooks": [ - { - "id": "45fe7810-3239-4761-94fd-04c017df29c4", - "name": "webhook-test", - "description": "Webhook for testing purposes", - "org": { - "id": "1574427524", - "name": "testOrg2025" - }, - "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d/2e5251b2-8274-41f6-80a0-1b82854df31f", - "url_params": null, - "events": [ - "LIVEBOARD_SCHEDULE" - ], - "authentication": null, - "signature_verification": null, - "additional_headers":null, - "creation_time_in_millis": 1761184185887, - "modification_time_in_millis": 1761184185887, - "created_by": { - "id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "name": "UserA@example.com" - }, - "last_modified_by": null, - "storage_destination":null - } - ], - "failed_webhooks": [] -} ----- +For information about scheduling a Liveboard, see +xref:schedule-liveboard.adoc[Schedule a Liveboard job]. -== Additional resources -* xref:webhooks-comm-channel.adoc[Configure webhook communication channel] -* link:https://docs.thoughtspot.com/cloud/latest/liveboard-schedule[Scheduling Liveboard jobs^] -* +++Liveboard schedule REST APIs+++ +For information about the webhook payload structure, see +xref:webhooks-payload.adoc[Webhook payload for Liveboard events]. \ No newline at end of file diff --git a/modules/ROOT/pages/webhooks-s3-storage.adoc b/modules/ROOT/pages/webhooks-s3-storage.adoc index bc581e52e..34080e241 100644 --- a/modules/ROOT/pages/webhooks-s3-storage.adoc +++ b/modules/ROOT/pages/webhooks-s3-storage.adoc @@ -1,4 +1,4 @@ -= Deliver Liveboard reports to AWS S3 Storage += AWS S3 storage integration for webhook delivery :toc: true :toclevels: 3 @@ -171,7 +171,6 @@ In the permissions policy, specify the role ARN and S3 bucket name. Optionally, ---- |==== - == Provide the storage configuration details to ThoughtSpot Provide the following information to your ThoughtSpot administrator: @@ -184,9 +183,9 @@ Provide the following information to your ThoughtSpot administrator: == Configure a webhook for the S3 storage destination in ThoughtSpot To create a webhook in ThoughtSpot, the webhook feature must be enabled on your instance. Only ThoughtSpot users with administration privileges or the *Can Manage Webhooks* privilege are allowed to create or manage a webhook. -Currently, ThoughtSpot supports webhook creation with AWS S3 storage via REST APIs only. +You can create a webhook with a cloud storage destination using the **Webhooks** page in the UI or through the create webhook REST API. -=== Create a webhook +=== Using REST API To configure the S3 storage properties in ThoughtSpot, the IAM role, external ID, S3 bucket name, and S3 region configured in your AWS account are required. To create a webhook, send a `POST` request to the `/api/rest/2.0/webhooks/create` API endpoint. @@ -317,6 +316,43 @@ If the API request is successful, ThoughtSpot returns the webhook configuration } ---- +=== Through the Webhooks page in UI +If the new Webhooks page is enabled on your instance, you can create a webhook via UI. + +==== Creating a webhook +To create a webhook with an AWS S3 storage as the target destination for payload delivery: + +. Go to **Develop** > **Customizations** and click **Webhooks**. +. In the *Webhooks* page, click *Create webhook*. +. In the *Create webhook* modal, configure the following: +* *Name*: A display name for the webhook. +* *URL*: The fully qualified HTTPS URL of the endpoint that will receive webhook payloads. +* *Description*: (optional) A short description of the webhook's purpose. +* *Event type*: Specify the ThoughtSpot event types to subscribe to. Ensure that *Liveboard schedule* is set as the event type. +. Configure the authentication method your destination endpoint requires. + +ThoughtSpot sends the configured credentials in every outbound request. The following options are available: +* *No Authentication*: No authentication headers are added to the request. Not recommended for production use. +* *OAuth 2.0*: ThoughtSpot obtains an access token using your OAuth client ID, client secret, and authorization URL, then sends `Authorization: Bearer ` in the request header. The token is refreshed automatically before expiry. +* *API Key*: ThoughtSpot sends the API key in the `X-API-Key` request header. +* *Bearer Token*: ThoughtSpot sends a static bearer token in the `Authorization: Bearer` header. +* *Basic authentication*: ThoughtSpot sends a Base64-encoded username and password in the `Authorization` header. +. Configure the file storage options. For more information, see xref:webhooks-s3-storage.adoc[AWS S3 storage integration for webhook delivery] and xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery]. +. Configure the advanced settings if required: +* *Signature verification* + +Specify the signature to send in the header for your endpoint to verify each request. Configure HMAC-SHA256 payload signing. ThoughtSpot signs each outbound +payload with a shared secret. Your endpoint can use the same secret and algorithm to verify the signature in the incoming request header. +* *Custom headers* + +Use this feature to pass arbitrary metadata required by your endpoint in addition to standard and authentication headers. Define key-value pairs of custom headers to add to every outbound HTTP request. +* *URL parameters*: +Specify the query parameters to append to the webhook URL on every request. +. Click *Save*. + +If the webhook creation is successful, it will be added to table list in the Webhooks page. + +==== Activating a webhook +To activate the webhook, use one of the following options: +* Select the webhook and click *Enable*. +* In the webhook row, from the More options menu (`...`), click **Enable*. + === View webhook configuration details To view the webhook configuration details, send a `POST` request to the `/api/rest/2.0/webhooks/search` API endpoint. @@ -368,11 +404,11 @@ If the webhook ID is valid, the API returns the following response: "modification_time_in_millis":1772127859128, "created_by":{ "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "name":"shashikala.subramanya@thoughtspot.com" + "name":"userA@thoughtspot.com" }, "last_modified_by":{ "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "name":"shashikala.subramanya@thoughtspot.com" + "name":"userA@thoughtspot.com" }, "storage_destination":{ "storage_type":"AWS_S3", diff --git a/modules/ROOT/pages/webhooks-ux.adoc b/modules/ROOT/pages/webhooks-ux.adoc new file mode 100644 index 000000000..a739084fc --- /dev/null +++ b/modules/ROOT/pages/webhooks-ux.adoc @@ -0,0 +1,161 @@ += Webhook configuration and management through the UI +:toc: true +:toclevels: 3 + +:page-title: Manage webhooks +:page-pageid: webhooks-manage +:page-description: Create and manage webhooks from the UI + +The **Develop** page in ThoughtSpot UI provides the option to configure and manage webhooks. + +== Webhook configuration and management (New experience) + +The **Webhooks** option in the **Develop** page allows you to access the new **Webhooks** page. This page provides a centralized interface for creating, managing, and monitoring all webhooks in your ThoughtSpot Org. + +[IMPORTANT] +==== +* The new Webhooks UI experience is an Early Access feature and is disabled by default. To enable this feature, contact ThoughtSpot Support. +* The new Webhooks UI experience is available on only ThoughtSpot Cloud instances running 26.7.0.cl and later. +* In the current version, the new experience allows creating and managing created webhooks for Liveboard Schedule events only. +==== + +=== Creating a webhook +You can create a webhook for the Liveboard schedule event type a lightweight JSON payload and also send these as reports to a Cloud Storage destination in the file format supported by the Liveboard scheduled jobs. + +To create a webhook: + +. Go to **Develop** > **Customizations** and click **Webhooks**. +. In the *Webhooks* page, click *Create webhook*. +. In the *Create webhook* modal, configure name, webhook endpoint, event type, authentication options and other parameters as needed. For more information about the configuration parameters, see the following pages: + +* xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard Scheduled Jobs]. +* xref:webhooks-s3-storage.adoc[AWS S3 storage integration for webhook delivery] +* xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery] +. Click **Save**. + +=== Activating a webhook +To activate the webhook, use one of the following options: +* Select the webhook and click *Enable*. +* In the webhook row, from the More options menu (`...`), click **Enable*. + +=== Editing a webhook +To edit webhook properties: + +. Use one of the following options to open the edit panel: +* Select the webhook and click *Edit*. +* In the webhook row, from the More options menu (`...`), click **Edit*. +. Update the fields as required. +. Click **Save**. + +[NOTE] +==== +To clear an authentication, signature verification, or storage destination configuration entirely without replacing it, you can use the `reset_options` parameter in the xref:webhooks-lb-schedule.adoc[update webhook REST API]. +==== + +=== Deleting a webhook + +. Hover over the webhook row and click the actions menu (*...*). +. Select *Delete*. +. Confirm the deletion in the prompt that appears. + +Deleting a webhook is permanent. Delivery logs associated with the webhook are removed when they reach the 3-day retention limit. + +=== Managing and monitoring Webhooks (New experience) +The new **Webhooks** page displays the following options: + +Webhooks list:: +Displays a list of webhooks configured in the Org. Note that ThoughtSpot allows only one webhook for Liveboard Schedule event per Org. The list includes the following columns: + +* *Name*: Display name of the webhook. +* *Events*: ThoughtSpot event types the webhook is subscribed to, such as `LIVEBOARD_SCHEDULE`. +* *Delivery status*: Summary of recent delivery outcomes for the webhook. +* *Status*: Current activation state of the webhook: *Enabled* or *Disabled*. Use the toggle to change the state without editing the webhook. +* *Creator*: ThoughtSpot user who created the webhook. +*Last modified*: Date and time the webhook configuration was last updated. + +For each item in the webhooks list, the following actions are available: + +* *Edit*: Opens the webhook edit panel +* *Enable*: Enables selected webhooks. +* *Disable*: Disables selected webhooks. +* *Send test event*: Sends a test payload to all selected webhook endpoints. +* *Delete*: Deletes the selected webhooks. + +Webhook configuration options:: +The **Create webhook** option to create a webhook for the Liveboard schedule event type. Only one webhook can be created per Org. To configure and manage webhooks, the *Can manage webhooks* (`CAN_MANAGE_WEBHOOKS`) privilege is required. + +The webhook creation workflow allows configuring webhook properties, including authentication parameters, storage destination, signature verification, custom headers, and URL parameters. + +To enable, disable, edit, or delete the webhook configuration, select the webhook in the list, and use the options available for in the More options (`...`) menu. + +Webhook details:: +Provides a dashboard view with the following cards. The cards are refreshed every 60 seconds. + +* *Delivery rate*: Percentage of webhook delivery attempts that succeeded. +* *Failed*: Total count of delivery attempts that failed or resulted in an error. +* *In Retry Queue*: Count of delivery attempts currently queued for retry. +* *Pending*: Count of delivery attempts awaiting dispatch. + +Actions for the webhook list items:: +The following actions are available for the list items in the Webhooks page: + +* *Sort*: Click any column header to sort the webhook list by that column. +* *Filter controls*: Use the column filter controls to narrow the list by name, state, creator, or other attributes. +* *Bulk selection*: Select multiple webhooks using the checkboxes to perform bulk actions. +* *Row-level actions*: Hover over a webhook row and click the actions menu (*...*) to edit, +delete, test, enable, or disable that webhook. + +UI Options in the webhook page:: +Clicking a webhook in the list opens a page that displays the options to filter webhook deliveries by their delivery status. To view the logs, click **View details**. + +== Webhook configuration and management (Legacy experience) +The **Legacy Webhooks** page allows you to create, view, and edit webhooks created for KPI alerts. These webhooks are managed through the UI and can be selected as custom channels when configuring KPI alert notifications in the UI. For more information, see xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. + +[NOTE] +==== +The webhook configuration and management options in the Legacy Webhooks page will be integrated with the new Webhooks page experience in a future release. +==== + +=== Creating a webhook for KPI alerts +To register a webhook in ThoughtSpot, complete the following steps: + +. Go to **Develop** > **Customizations** > **Legacy Webhooks**. +. Click **Create Webhook**. +. In the ** Create Webhook** modal, specify the Webhook name and the URL of the destination application. ++ +For testing purposes, you can use a URL from the link:https://webhook.site/[Webhook site, window=_blank]. +. Specify the authentication type. +* No authentication + +Default authentication option. Not recommended for production environments. + +* API Key + +Allows using an API key to authenticate API requests to the destination URL. Specify the API key to use in the `X-API-Key` request header. + +* OAuthentication 2.0 + +Allows using OAuth credentials to authorize API requests. Specify client ID, client secret key, and authorization URL. +If the registered webhook has Oauth authentication enabled, `Authorization: Bearer ` is sent in the request header. +. If the destination URL requires query parameters to be passed in the request URL, specify the parameters as key-value pairs. +. Click **Save**. +. xref:webhooks-kpi-alerts.adoc#_assign_webhook_to_a_kpi_monitor_alert[Assign webhook to a KPI Monitor alert]. + +=== Editing a webhook (Legacy experience) +To edit webhook properties: + +. In the **Legacy Webhooks** page, select the webhook to edit. +. In the webhook row, click More options menu (`...`) > **Edit*. +. Update the fields as required. +. Click **Save**. + +=== Deleting a webhook (Legacy experience) +To delete a webhook: + +. Hover over the webhook row and click the actions menu (*...*). +. Select *Delete*. +. Confirm the deletion in the prompt that appears. + +== Related resources + +* xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an external application] +* xref:webhooks-s3-storage.adoc[Deliver content to cloud storage using webhooks] +* xref:webhooks-comm-channel.adoc[Configure webhook communication channels] +* xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts] \ No newline at end of file diff --git a/modules/ROOT/pages/webhooks.adoc b/modules/ROOT/pages/webhooks.adoc index d8af984a2..38b834f81 100644 --- a/modules/ROOT/pages/webhooks.adoc +++ b/modules/ROOT/pages/webhooks.adoc @@ -1,48 +1,83 @@ = Webhooks :toc: true +:toclevels: 3 :page-title: Webhooks :page-pageid: webhooks -:page-description: Register a webhook to send KPI monitor and Liveboard schedule alerts to an external application +:page-description: Use webhooks to send real-time event notifications from ThoughtSpot to external applications, communication channels, and cloud storage destinations -Webhooks in ThoughtSpot provide a way to automate workflows and integrate with external systems by sending real-time notifications when specific events occur. In ThoughtSpot, webhooks can be used for two alerting use cases: +A webhook is ThoughtSpot provides a way to deliver data and reports to a target application, URL endpoint, or storage destination and is triggered by events such as scheduled Liveboard jobs. -* Liveboard schedule alerts [beta betaBackground]^Beta^ + -ThoughtSpot supports using a xref:webhooks-lb-schedule.adoc[webhook for delivering scheduled Liveboard notifications] to external applications and communication channels. +== Overview -* KPI alerts + -For KPI charts in a Liveboard or Answer, ThoughtSpot allows creating and scheduling alerts. KPI Monitor alerts notify users when a KPI metric meets a threshold condition or periodically as per the schedule configured by the user. You can send these alerts using a webhook and notify external applications when a KPI meets a defined threshold or changes value. For more information, see xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. +ThoughtSpot allows using webhooks for the following purposes: +Liveboard schedule notifications [beta betaBackground]^Beta^:: +ThoughtSpot supports using webhooks to deliver scheduled Liveboard notifications to external applications and communication channels. For more information, see +xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an external application]. -== Webhook configuration +KPI monitor alerts:: -ThoughtSpot users with developer or administrator privileges can create webhooks via REST APIs or from the *Develop* page in the UI. +You can use a webhook to trigger KPI monitor alerts to an external application when a KPI metric meets a threshold condition or changes value. For more information, see xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. -Webhooks configured via the REST API:: -The REST API framework webhook configuration is intended for automation and integration scenarios; for example, delivering attachments to an external application or storage destinations such as the Amazon Web Services (AWS) S3 bucket. Currently, the Webhook REST APIs support creating and managing webhooks for Liveboard schedule events only. +Webhook delivery to Cloud Storage destinations:: +ThoughtSpot supports delivering webhook payloads to the following cloud storage destinations: ++ +* *Amazon S3*: Available on AWS-hosted and GCP-hosted ThoughtSpot Cloud instances. For configuration steps, see +xref:webhooks-s3-storage.adoc[Deliver content to cloud storage using webhooks]. +* *Google Cloud Storage (GCS)*: Available on GCP-hosted ThoughtSpot Cloud instances. For more information, see xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery]. -Webhooks created from the Develop > Webhook page:: -Webhooks created from the Develop page in the UI are typically used for integrating with KPI alerts. These webhooks are managed through the UI and can be selected as custom channels when configuring KPI alert notifications in the UI. +== Webhook configuration and management +ThoughtSpot supports creating and managing webhooks through the UI or REST APIs. [NOTE] ==== -* Webhooks created from the **Develop** page are different from the webhooks configured via REST APIs and follow a separate flow. Use REST APIs to create webhooks for custom notification channels or external storage destinations. * To set up a webhook for Liveboard schedule notifications, you must first configure the xref:webhooks-comm-channel.adoc[webhook communication channel using the communication-channel preferences API]. +* Only one webhook configuration is allowed per Org. ==== -== Integration with Amazon S3 bucket [beta betaBackground]^Beta^ +=== Webhooks UI +For managing webhooks via UI, use the following options in the **Develop** page of the ThoughtSpot UI: -Starting with the ThoughtSpot 26.3.0.cl release, ThoughtSpot supports configuring an Amazon S3 bucket as the storage destination for delivering webhook attachments via REST APIs. +* **Webhooks** [earlyAccess earlyAccessBackground]^Early Access^: + +The new *Webhooks* option in the *Develop* page provides centralized view of webhooks configured in ThoughtSpot, including the options to create, monitor, and manage webhooks, and view stats and delivery logs in your ThoughtSpot Org. -For more information, see xref:webhooks-s3-storage.adoc[S3 storage integration for Webhook delivery]. ++ +[IMPORTANT] +==== +* The new Webhooks UI experience is an Early Access feature and is disabled by default. To enable this feature, contact ThoughtSpot Support. +* The new Webhooks UI experience is available on only ThoughtSpot Cloud instances running 26.7.0.cl and later. +* In the current version, the new experience allows creating and managing created webhooks for Liveboard Schedule events only. +==== + ++ +For more information, see xref:webhooks-ux.adoc[Webhook configuration and management through the UI]. + +* **Legacy Webhooks**: +The **Legacy webhooks** page displays a list of webhooks created for KPI alerts and the menu actions to create, view, and edit the webhooks created for KPI alerts. These webhooks are managed through the UI and can be selected as custom channels to send KPI alerts when a KPI metric meets the threshold. For more information, see xref:webhooks.adoc[Webhook configuration and management through the UI] and xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. -== Response after webhook delivery +=== Webhook REST APIs +The REST API framework is intended for automation and integration scenarios, for example, creating webhooks programmatically or delivering Liveboard report attachments to a cloud storage destination. See the following for more information: +xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an +external application] for REST API reference and examples. -When a webhook delivery is attempted for a Liveboard schedule event, the webhook endpoint must respond with an HTTP 2xx status code within 5 seconds to confirm successful receipt and processing of the request. +== Webhook delivery behavior +When ThoughtSpot attempts to deliver a webhook event, the destination endpoint must respond with an HTTP 2xx status code within 5 seconds to confirm successful receipt. -If your server takes longer than 5 seconds to respond, returns a response code other than 2xx, or times out, ThoughtSpot may still deliver the Liveboard data and files. However, the notification status will be recorded as `FAILED` in the ThoughtSpot notification, and the request will be retried. +If the endpoint takes longer than 5 seconds to respond, returns a non-2xx status code, or times out, ThoughtSpot records the delivery status as `FAILED` and retries the request. -To ensure a timely response, we recommend processing webhook payloads asynchronously. Your server can immediately return a 2xx response upon receipt of the webhook and then handle the payload in the background without blocking subsequent webhook deliveries. +To ensure a timely response, process webhook payloads asynchronously. Your server can return a 2xx response immediately on receipt and handle the payload in the background, without blocking subsequent webhook deliveries. + +For information about retry behavior and delivery logs, see xref:webhooks-manage.adoc[Manage webhooks]. == Webhook payload -For information about the payload content delivered to a target destination, see xref:webhooks-payload.adoc[Webhook payload for Liveboard events]. + +For information about the payload structure delivered to a destination, see +xref:webhooks-payload.adoc[Webhook payload for Liveboard events]. + +== Next steps +* xref:webhooks-comm-channel.adoc[Configure webhook communication channels] +* xref:webhooks-s3-storage.adoc[Deliver content to cloud storage using webhooks] +* xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an external application] +* xref:webhooks-kpi-alerts.adoc[Send KPI monitor alerts using a webhook] + diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 213c12cfd..8eb540dc8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,6 +23,7 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ +== July 2026 [.cl-table, cols="2,4", frame=none, grid=none] |===== @@ -33,87 +34,143 @@ a| a| [discrete] -==== Spotter file upload in embedded apps [.version-badge.new]#New# +==== SpotterViz for Liveboards [.version-badge.new]#New# +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 describe what they want in natural language, and SpotterViz generates the Liveboard for them, including new tabs, chart types, styling, data filters, and scheduled deliveries. + +SpotterViz customization:: +The Visual Embed SDK also provides several customization options in the xref:SpotterVizConfig.adoc[SpotterVizConfig] and xref:SpotterVizStarterPrompt.adoc[SpotterVizStarterPrompt] interfaces to customize the SpotterViz panel experience. + +Insight tiles in Liveboards:: +When SpotterViz is enabled, your application users can add and configure the **Insight tile** for automated textual analysis of the data on your Liveboard. For example, you can specify a prompt or context that defines what the tile should analyze. + +For more information, see xref:embed-spotterViz.adoc[Customizing SpotterViz]. + +[NOTE] +==== +SpotterViz is an Early Access feature and is available to users with edit permissions on a Liveboard. +==== +--- -// SOURCE: https://github.com/thoughtspot/developer-docs/blob/main/modules/ROOT/pages/api-changelog.adoc (SDK v1.49.x section) +[discrete] +==== Spotter file upload in embedded apps [.version-badge.new]#New# Embedded Spotter applications can now allow users to upload files directly in the Spotter chat panel. The SDK introduces two new configuration parameters in `SpotterChatViewConfig` to enable and control this capability: -* `spotterFileUploadEnabled` — When set to `true`, enables the file upload feature in the Spotter chat panel. -* `spotterFileUploadFileTypes` — Restricts the file types allowed for upload. Accepts a `SpotterFileUploadFileTypes` object. +* `spotterFileUploadEnabled`: + +When set to `true`, enables the file upload feature in the Spotter chat panel. +* `spotterFileUploadFileTypes`: + +Restricts the file types allowed for upload. Accepts a `SpotterFileUploadFileTypes` object. For more information, see xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[Enable file upload in Spotter chat]. --- [discrete] -==== SpotterViz branding and customization [.version-badge.new]#New# +==== Focused homepage experience [.version-badge.new]#New# +In full application embedding, when the V3 navigation and home page experience is enabled, ThoughtSpot provides an additional option to switch to the new focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:customize-homepage-full-embed.adoc[Customize home page experience]. + +[NOTE] +==== +The focussed homepage experience is in beta and disabled by default. To enable this experience in your embedding application, the feature must be enabled on your ThoughtSpot instance and in the Visual Embed SDK. +==== +--- -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. -Using `SpotterVizConfig`, you can now: +[discrete] +==== Centralized Webhooks page [.version-badge.new]#New# -* Set a custom brand name and headline for the SpotterViz panel. -* Add a custom description and input chat placeholder text. -* Show, hide, or replace the default starter prompts with -application-specific suggestions using `SpotterVizStarterPrompt`. +[earlyAccess earlyAccessBackground]^Early Access^ +The *Develop* tab now includes a dedicated *Webhooks* page for creating, managing, and +monitoring all webhooks in your ThoughtSpot Org from one place. -The `spotterViz` property is available on both `AppViewConfig` and -`LiveboardViewConfig`. +Key capabilities include: -For more information, see xref:embed-spotter-viz.adoc[Customizing SpotterViz]. -// TODO: verify target page ID with the developer-docs team. +* *Webhooks tab* — A paginated table listing all Org webhooks with columns for name, event +type, delivery status, state, author, and timestamps. Supports sorting, filtering, bulk +selection, and row-level actions including edit, delete, test, and enable/disable. +* *Enable and disable webhooks* — Activate or deactivate a webhook without deleting it, using +the state toggle on the table row or the bulk actions bar. +* *Stats cards* — Four metric cards at the top of the page show Delivery Rate, Delivered +count, Failed count, and retry queue size across all Org webhooks. Stats refresh every 30 +seconds. +* *Logs tab* — Delivery attempt history with status badges, event type, attempt count, and +error messages. A details modal shows the full payload, response headers, and retry history. +Logs are retained for 3 days. +* *Create/Edit webhook modal* — A unified form covering authentication (No Auth, API Key, +Basic Auth, Bearer Token, OAuth 2.0 client credentials), optional cloud storage destination +(AWS S3 or GCP GCS), signature verification, custom headers, and URL parameters. +* *Test event* — Send a one-click test payload to verify endpoint connectivity, with +categorized feedback for auth errors, timeouts, and 4xx/5xx responses. +For more information, see xref:webhooks-manage.adoc[Manage webhooks] and +xref:webhooks.adoc[Webhooks overview]. --- -[discrete] -==== Focused homepage experience [.version-badge.new]#New# -A new `HomePage.Focused` enum member (`v4`) is introduced in `AppEmbed` -to enable the V4 homepage experience, which merges the Watchlist and Recents -sections into a single focused view. -[NOTE] -==== -The V4 homepage experience requires Spotter to be enabled on your -ThoughtSpot instance. -==== +[discrete] +==== Liveboard browser cache refresh — Early Access [.version-badge.new]#New# + +// SOURCE: SCAL-305659 -For more information, see xref:embed-app.adoc#_discovery_experience[Discovery experience]. -// TODO: verify target anchor with the developer-docs team. +The Liveboard browser cache feature is now in Early Access. When `enableLiveboardDataCache` is set to `true` in your `LiveboardEmbed` configuration, ThoughtSpot caches Liveboard visualization data in the browser to significantly reduce reload times on revisit. +For SDK event and action IDs, see the xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Visual Embed changelog — Liveboard browser cache refresh]. --- + +[discrete] +==== Webhooks enhancements [.version-badge.new]#New# + +ThoughtSpot 26.7.0.cl introduces several enhancements to the Webhooks REST API and the Webhooks page in the Developer tab. + +* **Retrieve storage configuration** — A new `GET /api/rest/2.0/webhooks/storage-config` endpoint returns the AWS ARN or GCP service account details that administrators need to configure cross-account storage access. For more information, see xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[Webhooks API documentation]. +* **GCS bucket storage destination** — Webhook payloads can now be delivered directly to a Google Cloud Storage (GCS) bucket on GCP-hosted instances. Specify `storage_type: GCP_GCS` with a `gcp_gcs_config` object in the `storage_destination` parameter. For more information, see xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery]. +* **Enable and disable webhooks** — The create, update, and search webhook APIs now support a `status` parameter (`ENABLED` or `DISABLED`), letting you activate or deactivate webhooks without deleting them. The Webhooks page in the Developer tab also surfaces the webhook status with a toggle. +* **Selective configuration reset** — The update webhook API now supports a `reset_options` parameter, which removes specific optional configuration sections (`AUTHENTICATION`, `SIGNATURE_VERIFICATION`, or `STORAGE_DESTINATION`) from a webhook without replacing the full configuration. + +//// [discrete] -==== New EmbedEvents for SpotterViz [.version-badge.new]#New# +==== GCS storage integration for webhook delivery [.version-badge.new]#New# -The SDK introduces two new event identifiers for monitoring SpotterViz -panel activity in embedded Liveboards: +Administratos can now configure Google Cloud Storage (GCS) buckets can now be configured as a storage destination for webhook payload delivery on GCP-hosted ThoughtSpot clusters. This extends the existing Amazon S3 webhook storage integration to bring GCS parity for GCP environments. + +A storage config API endpoint returns the GCP Service Account details required to configure IAM permissions on your GCS bucket. -* `EmbedEvent.SpotterVizMount` + -Emitted when the SpotterViz panel mounts in embed mode. -* `EmbedEvent.SpotterVizPromptSubmit` + -Emitted when a user submits a prompt in the SpotterViz panel. --- +//// + +[discrete] +==== Saved Chat public APIs [.version-badge.new]#New# + +// SOURCE: SCAL-290720, SCAL-313991 + +ThoughtSpot now provides public REST API endpoints and Visual Embed SDK host events to manage saved Spotter conversations from a host application. Embed developers can build fully headless conversation history experiences outside the ThoughtSpot iframe. +New REST API endpoint::: +`GET /api/rest/2.0/ai/agent/conversations` — Retrieve a paginated list of saved conversations for the authenticated user. + +New SDK host events::: +* `HostEvent.LoadChat` — Load a specific conversation by ID into the embedded Spotter interface. +* `HostEvent.DeleteChat` — Delete a specific conversation by ID. +* `HostEvent.RenameChat` — Rename a specific conversation by ID. + +For more information, see xref:saved-conversations-api.adoc[Saved Chat public APIs]. + +--- [discrete] ==== REST API v2 -// TODO: verify if any new Spotter REST API v2 endpoints are introduced specifically in 26.7.0.cl beyond those documented in 26.6.0.cl — confirm with engineering - For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. --- - [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]. +==== Visual Embed SDK [.version-badge.breaking]#Breaking# +The Visual Embed SDK version 1.50.0 includes several new features, enhancements, and a breaking change. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +⚠️ *Breaking change*: `EmbedEvent.SpotterData` has been removed. This event was never emitted in Spotter 3 and was superseded by `EmbedEvent.PreviewSpotterData`. Update your integration code to use `EmbedEvent.PreviewSpotterData`. |===== @@ -184,6 +241,75 @@ This release introduces new API endpoints for Spotter, connections and trusted a |===== + + + + +== 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-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] +==== 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 + @@ -656,4 +782,4 @@ For information about the new features and enhancements introduced in Visual Emb ==== REST API For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== +|=== \ No newline at end of file