diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 0b682e3ed..da7ec9f9f 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -1,12 +1,36 @@ -= Visual Embed changelog += Visual Embed SDK changelog :toc: true -:toclevels: 1 +:toclevels: 2 -:page-title: Changelog +:page-title: Visual Embed SDK changelog :page-pageid: embed-sdk-changelog -:page-description: Changes to the SDK and APIs +: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.50.x, July 2026 + +[width="100%", cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== SpotterViz embed customization +The Visual Embed SDK 1.50.0 introduces the `SpotterVizConfig` interface and `SpotterVizStarterPrompt` interface to allow embed developers to customize the SpotterViz panel on embedded Liveboards and full-application embeds. + +A new `SpotterVizConfig` interface is available on `LiveboardViewConfig` and `AppViewConfig` for the `spotterViz` object. This object provides branding customization controls for customizing the SpotterViz panel experience. + +To customize app interactions, visibility of the UI elements, and style and appearance of the SpotterViz panel, the SDK also introduces CSS variables, action IDs, and embed and host event identifiers. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Home page customization in full application embedding +For full application embedding, ThoughtSpot provides a focused and streamlined home page experience. To enable this feature, use the `HomePage.Focused` option with the `homePage` attribute in the `discoveryExperience` object. + +For more information, see xref:full-app-customize.adoc[Customize full application embedding]. +|==== == Version 1.49.x, June 2026 @@ -30,42 +54,36 @@ The `visualOverrides` object provides the following customization controls to mo * `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 +For embedded Liveboards, the SDK provides `enableLiveboardDataCache` to clear browser cache and fetch new data for the visualizations on the Liveboard. -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:: +The SDK also provides the following events and action ID to programmatically trigger cache refresh and control the visibility of the **Refresh** button. * `EmbedEvent.RefreshLiveboardBrowserCache` + -Emitted when a user clicks the *Refresh* button in the Liveboard header to clear the browser cache. - +Emitted when the Liveboard browser cache is refreshed. * `HostEvent.RefreshLiveboardBrowserCache` + -Allows the host application to programmatically trigger a browser cache refresh for all visualization containers on the embedded Liveboard. - -New action ID:: - +Trigger a manual cache refresh from the host application. * `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. +Action ID to show or hide the cache refresh button. + +For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. |[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. +The SDK introduces the following configuration parameters in `SpotterChatConfig` object to enable and control file uploads in the embedded Spotter chat interface. * `spotterFileUploadEnabled` + When set to `true`, enables the file upload feature in the Spotter chat panel. * `spotterFileUploadFileTypes` + -Restricts the file types allowed for upload in the Spotter chat panel. Accepts a `SpotterFileUploadFileTypes` object. +Restricts the file types allowed for upload in the Spotter chat panel. + +For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploads in Spotter chats]. + |==== @@ -1846,4 +1864,4 @@ Users with edit permissions can view and access the *Edit* action. The *Download When a user accesses the embedded application from a web browser that has third-party cookies disabled, the Visual Embed SDK emits the `NoCookieAccess` event to notify the developer. Cookies are disabled by default in Safari. Users can enable third-party cookies in Safari’s Preferences setting page or use another web browser. To know how to enable this setting by default on Safari for a ThoughtSpot embedded instance, contact ThoughtSpot Support. -|==== +|==== \ No newline at end of file diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index d5c58ad2d..c5624f897 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -16,7 +16,7 @@ While you can delete users, it is preferable to deactivate a user, which maintai When configuring xref:configure-saml.adoc[SAML SSO] in ThoughtSpot UI, you can select the *Automatically add SAML users to ThoughtSpot upon first authentication* option, which will use the values in the SAML assertion to create a user if they do not already exist on ThoughtSpot. ThoughtSpot can also add users to groups sent within the SAML assertion. To enable and configure the SAML group attributes, contact your ThoughtSpot team. -By default, ThoughtSpot sends e-mail messages to a new user and enables onboarding workflows when they log in for the first time, even when you are embedding ThoughtSpot content. To alter this behavior at a system-wide level, you need to xref:customize-email-settings.adoc[Customize the onboarding settings]. +By default, ThoughtSpot sends e-mail messages to a new user and enables onboarding workflows when they log in for the first time, even when you are embedding ThoughtSpot content. To alter this behavior at a system-wide level, you need to xref:customize-email-settings.adoc[Customize the onboarding settings]. The user update API also allows setting onboarding experience values for an individual user. If you need to modify the default behavior beyond the available UI options, contact your ThoughtSpot team. [NOTE] @@ -108,9 +108,9 @@ image::./images/unsuspend.png[Unsuspended state] === User migration to IAMv2 -ThoughtSpot is gradually migrating its user to link:https://docs.thoughtspot.com/cloud/latest/okta-iam[Identity and Access Management v2 (IAMv2), window=_blank] to provide a more secure login and authentication experience through internal authentication with Okta. The following are some of the important points to note with this upgrade: +ThoughtSpot is gradually migrating its users to link:https://docs.thoughtspot.com/cloud/latest/okta-iam[Identity and Access Management v2 (IAMv2), window=_blank] to provide a more secure login and authentication experience through internal authentication with Okta. The following are some of the important points to note with this upgrade: -* The `email` attribute is mandatory when creating a user in ThoughtSpot Okta. ThoughtSpot recommends users to provide a valid email address during the user creation. +* The `email` attribute is mandatory when creating a user in ThoughtSpot Okta. ThoughtSpot recommends that users provide a valid email address during user creation. * You must set a password during user creation if you do not want to trigger an activation email. * The default value for `usertype` will be `OIDC_USER`. @@ -127,6 +127,26 @@ To update user details: * +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) * xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) +[NOTE] +==== +Updating the username of an SSO user, `account_type` set to `SAML_USER` or `OIDC_USER`, requires changes in both the IdP and ThoughtSpot. + +If you rename an SSO user through the REST API and that user then logs in through the IdP: + +* If Just-in-Time (JIT) provisioning is enabled, ThoughtSpot creates a new duplicate account. The duplicate account does not inherit the original user's content, groups, or permissions. +* If JIT provisioning is disabled, the user cannot log in. + +To safely update the username of an SSO user: + +. Update the username in your IdP. +. Before the user logs in again, update the username in ThoughtSpot to match the new value using the REST API or Admin UI. + +Both updates must be complete before the user's next SSO login. +The order of the two steps can be reversed — you may update ThoughtSpot first and the IdP second — provided the user does not log in during the interval between the two changes. + +For SSO users, ThoughtSpot derives email address and display name directly from the IdP. Update these attributes in your IdP only. +ThoughtSpot automatically reflects the new values when the user next logs in through SSO. +Do not use the REST API or the Admin UI to update the email address or display name of an SSO user. [NOTE] ==== @@ -191,7 +211,7 @@ To remove a user from a group, use the update group REST v2 endpoint, or the fol * xref:group-api.adoc#delete-user-assoc[POST /tspublic/v1/group/{groupid}/user/{userid}] + removes a user from a specific group * xref:group-api.adoc#removeMembers[POST /tspublic/v1/group/removememberships] + -removes a list of users] from many groups at once. +removes a list of users from many groups at once. == Access control (sharing) Access to objects is determined by content *shared* directly to the user or the groups they belong to. It is easier to manage and audit sharing through groups rather than object sharing at the individual user level. @@ -215,6 +235,17 @@ ThoughtSpot also has a default group called `All`. When you create new users in ==== == Roles -If Role-Based Access Control (RBAC) is enabled on your instance, administrators can define Role privileges and assign these to users via Groups. +If Role-Based Access Control (RBAC) is enabled on your instance, administrators can define role privileges and assign them to users via groups. Roles are always scoped to an Org; a role created in one Org cannot be assigned in another. + +=== Assign roles to groups via REST API +When creating or updating a group using the REST API v2 endpoints, use the `role_identifiers` parameter to assign one or more roles to the group. The parameter accepts an array of role GUIDs or role names. For more information, see: + +* link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fcreate-user-group[`POST /api/rest/2.0/groups/create`]: include `role_identifiers` in the request body. +* link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[`POST /api/rest/2.0/groups/{group_identifier}/update`]: include `role_identifiers` to add roles to an existing group. + +[NOTE] +==== +Roles must be available before they can be assigned. Use the xref:roles-api.adoc[Roles API] to create roles programmatically before calling the group create or update endpoints. +==== -For more information, see xref:roles.adoc[Role-based access control] and link:https://docs.thoughtspot.com/cloud/latest/rbac[ThoughtSpot Product documentation, window=_blank]. +For a complete list of available privileges and role categories, see xref:roles.adoc[Role-based access control]. \ No newline at end of file diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index fc6cdc283..4f5f8a246 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -14,6 +14,7 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] * link:{{navprefix}}/embed-liveboard[Embed Analytics] ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] ** link:{{navprefix}}/full-app-customize[Customize your embed] @@ -41,6 +42,34 @@ Embed without SDK ** link:{{navprefix}}/embed-without-sdk[Embed without SDK] ** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] + +[.sidebar-title] +Authentication and data security + +* link:{{navprefix}}/embed-auth[Authentication] +** link:{{navprefix}}/trusted-auth[Trusted authentication] +*** link:{{navprefix}}/trusted-auth-secret-key[Secret key management] +*** link:{{navprefix}}/trusted-auth-sdk[Front-end trusted authentication integration] +*** link:{{navprefix}}/trusted-auth-token-request-service[Token request service] +*** link:{{navprefix}}/trusted-auth-troubleshoot[Troubleshoot trusted authentication] +** link:{{navprefix}}/saml-sso[SAML SSO authentication] +** link:{{navprefix}}/oidc-auth[OpenID Connect authentication] +** link:{{navprefix}}/just-in-time-provisioning[Just-in-time provisioning] +* link:{{navprefix}}/security-settings[Security settings] + +* link:{{navprefix}}/embed-object-access[Authorization] +** link:{{navprefix}}/access-control-sharing[Access control and sharing] +** link:{{navprefix}}/privileges-and-roles[Privileges and Roles] +** link:{{navprefix}}/data-security[Data security] +*** link:{{navprefix}}/rls-rules[RLS Rules] +*** link:{{navprefix}}/abac-via-rls-variables[ABAC via RLS with variables] +*** link:{{navprefix}}/jwt-abac-migration-guide[ABAC JWT migration guide] +**** link:{{navprefix}}/jwt-filter-parameters-rules-migration-guide[JWT ABAC with filter rules -> ABAC via RLS] +**** link:{{navprefix}}/jwt-abac-beta-migration-guide[JWT ABAC beta implementation -> ABAC via RLS] +*** link:{{navprefix}}/abac-user-parameters[ABAC via JWT with filter rules and parameters] +* link:{{navprefix}}/selective-user-access[User access] +* link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] + [.sidebar-title] Customize and integrate @@ -89,32 +118,6 @@ Customize and integrate ** link:{{navprefix}}/prefetch[Prefetch static resources] * link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] -[.sidebar-title] -Authentication and data security - -* link:{{navprefix}}/embed-auth[Authentication] -** link:{{navprefix}}/trusted-auth[Trusted authentication] -*** link:{{navprefix}}/trusted-auth-secret-key[Secret key management] -*** link:{{navprefix}}/trusted-auth-sdk[Front-end trusted authentication integration] -*** link:{{navprefix}}/trusted-auth-token-request-service[Token request service] -*** link:{{navprefix}}/trusted-auth-troubleshoot[Troubleshoot trusted authentication] -** link:{{navprefix}}/saml-sso[SAML SSO authentication] -** link:{{navprefix}}/oidc-auth[OpenID Connect authentication] -** link:{{navprefix}}/just-in-time-provisioning[Just-in-time provisioning] -* link:{{navprefix}}/security-settings[Security settings] - -* link:{{navprefix}}/embed-object-access[Authorization] -** link:{{navprefix}}/access-control-sharing[Access control and sharing] -** link:{{navprefix}}/privileges-and-roles[Privileges and Roles] -** link:{{navprefix}}/data-security[Data security] -*** link:{{navprefix}}/rls-rules[RLS Rules] -*** link:{{navprefix}}/abac-via-rls-variables[ABAC via RLS with variables] -*** link:{{navprefix}}/jwt-abac-migration-guide[ABAC JWT migration guide] -**** link:{{navprefix}}/jwt-filter-parameters-rules-migration-guide[JWT ABAC with filter rules -> ABAC via RLS] -**** link:{{navprefix}}/jwt-abac-beta-migration-guide[JWT ABAC beta implementation -> ABAC via RLS] -*** link:{{navprefix}}/abac-user-parameters[ABAC via JWT with filter rules and parameters] -* link:{{navprefix}}/selective-user-access[User access] -* link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] [.sidebar-title] Embedding tutorials @@ -170,10 +173,6 @@ include::generated/typedoc/CustomSideNav.adoc[] [.sidebar-title] Additional resources -* link:{{navprefix}}/embed-ts[About ThoughtSpot embedding] -* link:{{navprefix}}/get-started-tse[Embed licenses] -* link:{{navprefix}}/license-feature-matrix[Feature matrix] * link:{{navprefix}}/faqs[FAQs] -* link:{{navprefix}}/code-samples[Code samples] * link:https://codesandbox.io/s/big-tse-react-demo-i4g9xi[React CodeSandbox, window=_blank] -* link:https://codesandbox.io/s/graphqlcookieembed-wf4fk9?file=/src/App.js:418-426[GraphQL CodeSandbox, window=_blank] +* link:https://github.com/thoughtspot/developer-examples[Developer examples, window=_blank] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc new file mode 100644 index 000000000..cf7312ff9 --- /dev/null +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -0,0 +1,308 @@ + +:page-pageid: nav-in-product-help +:page-description: In-product navigation + +[navSection] + +[.sidebar-title] +Release notes and changelogs + +* link:{{navprefix}}/whats-new[What's new] +* Changelog +** link:{{navprefix}}/embed-sdk-changelog[Visual Embed SDK changelog] +** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog] +** link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] +* link:{{navprefix}}/deprecated-features[Deprecation announcements] + +[.sidebar-title] +Live Playgrounds + +* +++Visual Embed Playground+++ +** link:{{navprefix}}/dev-playground[How to use] +* link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction[REST API v2 Playground] +** link:{{navprefix}}/rest-playground[How to use] +* +++Theme Builder+++ +** link:{{navprefix}}/theme-builder-doc[How to use] + +[.sidebar-title] +Embed ThoughtSpot in a web app + +* link:{{navprefix}}/getting-started[Embed with Visual Embed SDK] +* link:{{navprefix}}/tsembed[Quickstart guide] +* link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] +** link:{{navprefix}}/embed-spotter[Embed Spotter experience] +** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] +* link:{{navprefix}}/embed-liveboard[Embed Analytics] +** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] +** link:{{navprefix}}/embed-a-viz[Embed a visualization] +* link:{{navprefix}}/full-embed[Embed full application] +** link:{{navprefix}}/full-app-customize[Customize your embed] +** link:{{navprefix}}/customize-nav-controls[Customize navigation panels] +** link:{{navprefix}}/set-default-page[Customize default page and navigation path] +** link:{{navprefix}}/customize-homepage-experience[Customize home page experience] +* Embed token-based Search +** link:{{navprefix}}/search-embed[Embed Search] +** link:{{navprefix}}/embed-searchbar[Embed search bar] +** link:{{navprefix}}/visualization-overrides[Visualization overrides] +* link:{{navprefix}}/react-app-embed[Embed with React components] + +[.sidebar-title] +Embed ThoughtSpot in a mobile app + +* link:{{navprefix}}/mobile-embed[Overview] +* link:{{navprefix}}/embed-ts-mobile-react-native[React Native SDK] +* link:{{navprefix}}/embed-ts-flutter[Flutter embed SDK] +* link:{{navprefix}}/embed-ts-swift[Swift Embed SDK] +* link:{{navprefix}}/embed-ts-android[Android Embed SDK] + +[.sidebar-title] +Embed without SDK + +** link:{{navprefix}}/embed-without-sdk[Embed without SDK] +** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] + +[.sidebar-title] +Authentication and data security + +* link:{{navprefix}}/embed-auth[Authentication] +** link:{{navprefix}}/trusted-auth[Trusted authentication] +*** link:{{navprefix}}/trusted-auth-secret-key[Secret key management] +*** link:{{navprefix}}/trusted-auth-sdk[Front-end trusted authentication integration] +*** link:{{navprefix}}/trusted-auth-token-request-service[Token request service] +*** link:{{navprefix}}/trusted-auth-troubleshoot[Troubleshoot trusted authentication] +** link:{{navprefix}}/saml-sso[SAML SSO authentication] +** link:{{navprefix}}/oidc-auth[OpenID Connect authentication] +** link:{{navprefix}}/just-in-time-provisioning[Just-in-time provisioning] +* link:{{navprefix}}/security-settings[Security settings] + +* link:{{navprefix}}/embed-object-access[Authorization] +** link:{{navprefix}}/access-control-sharing[Access control and sharing] +** link:{{navprefix}}/privileges-and-roles[Privileges and Roles] +** link:{{navprefix}}/data-security[Data security] +*** link:{{navprefix}}/rls-rules[RLS Rules] +*** link:{{navprefix}}/abac-via-rls-variables[ABAC via RLS with variables] +*** link:{{navprefix}}/jwt-abac-migration-guide[ABAC JWT migration guide] +**** link:{{navprefix}}/jwt-filter-parameters-rules-migration-guide[JWT ABAC with filter rules -> ABAC via RLS] +**** link:{{navprefix}}/jwt-abac-beta-migration-guide[JWT ABAC beta implementation -> ABAC via RLS] +*** link:{{navprefix}}/abac-user-parameters[ABAC via JWT with filter rules and parameters] +* link:{{navprefix}}/selective-user-access[User access] +* link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] + +[.sidebar-title] +Customize and integrate + +* link:{{navprefix}}/style-customization[Customize UI layout and styles] +** link:{{navprefix}}/customize-style[Customize basic styles] +** link:{{navprefix}}/custom-css[CSS customization framework] +** link:{{navprefix}}/theme-builder-doc[Theme builder] +** link:{{navprefix}}/customize-icons[Customize icons] +** link:{{navprefix}}/customize-text[Customize text strings] +** link:{{navprefix}}/css-variables-reference[CSS variables reference] + +* link:{{navprefix}}/filters-overview[Filters types and application layers] +** link:{{navprefix}}/runtime-overrides[Runtime overrides] +** link:{{navprefix}}/runtime-filters[Runtime filters] +** link:{{navprefix}}/runtime-params[Runtime Parameters] +* link:{{navprefix}}/action-config[Customize menus] +** link:{{navprefix}}/actions[Action IDs in the SDK] +* link:{{navprefix}}/events-app-integration[Events and app interactions] +** link:{{navprefix}}/embed-events[Using embed events] +** link:{{navprefix}}/host-events[Using host events] +** link:{{navprefix}}/context-aware-event-routing[Context-based execution of host events] +** link:{{navprefix}}/hostEventsV2-migration[Migrating from Host Event v1 to Host Events v2 framework] +** link:{{navprefix}}/handling-embed-errors[Handling embed errors] +** link:{{navprefix}}/api-search-intercept[API intercept and data fetch requests] + +* link:{{navprefix}}/custom-action-intro[Custom actions] +** link:{{navprefix}}/customize-actions[Custom actions through the UI] +*** link:{{navprefix}}/custom-action-url[URL actions] +*** link:{{navprefix}}/custom-action-callback[Callback actions] +*** link:{{navprefix}}/edit-custom-action[Set the position of a custom action] +*** link:{{navprefix}}/add-action-viz[Add a local action to a visualization] +*** link:{{navprefix}}/add-action-worksheet[Add a local action to a model] +** link:{{navprefix}}/code-based-custom-action[Code based custom actions] +** link:{{navprefix}}/custom-action-payload[Callback response payload] + +* link:{{navprefix}}/customize-links[Customize links] +* link:{{navprefix}}/set-locale[Customize locale] +* link:{{navprefix}}/custom-domain-config[Custom domain configuration] +* link:{{navprefix}}/customize-emails[Customize onboarding settings] +* link:{{navprefix}}/customize-email-apis[Customize email template] +* link:{{navprefix}}/in-app-navigation[Create dynamic menus and navigation] +* link:{{navprefix}}/best-practices[Performance optimization] +** link:{{navprefix}}/best-practices[Best practices] +** link:{{navprefix}}/prerender[Prerender components] +** link:{{navprefix}}/lazy-load-fullHeight[Full height and lazy loading options] +** link:{{navprefix}}/prefetch[Prefetch static resources] +* link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] + +[.sidebar-title] +Visual Embed SDK reference guide + +* link:{{navprefix}}/VisualEmbedSdk[Visual Embed SDK Reference] +include::generated/typedoc/CustomSideNav.adoc[] +** Custom styles +*** [.typedoc-Interface]#link:{{navprefix}}/Interface_CustomStyles[CustomStyles]# +*** [.typedoc-Interface]#link:{{navprefix}}/Interface_CustomisationsInterface[CustomisationsInterface]# +*** [.typedoc-Interface]#link:{{navprefix}}/Interface_customCssInterface[customCssInterface]# +*** [.typedoc-Interface]#link:{{navprefix}}/Interface_CustomCssVariables[customCssVariables]# +** Runtime filters +*** [.typedoc-Interface]#link:{{navprefix}}/Interface_RuntimeFilter[RuntimeFilter]# +*** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_RuntimeFilterOp[RuntimeFilterOp]# +** Others +*** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_Action[Action]# +*** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_ContextMenuTriggerOptions[ContextMenuTriggerOptions]# +*** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_DataSourceVisualMode[DataSourceVisualMode]# +*** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_Page[Page]# +*** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_PrefetchFeatures[PrefetchFeatures]# +*** [.typedoc-Function]#link:{{navprefix}}/Function_executeTML[executeTML]# +*** [.typedoc-Function]#link:{{navprefix}}/Function_exportTML[exportTML]# + + +[.sidebar-title] +Multi-tenancy + +* link:{{navprefix}}/multi-tenancy[Overview] +* link:{{navprefix}}/orgs[Multi-tenancy with Orgs] +** link:{{navprefix}}/orgs-api-op[Org administration] +** link:{{navprefix}}/multitenancy-within-an-org[Multi-tenancy within an Org] +** 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[Overview] +* link:{{navprefix}}/webhooks-ui[Webhooks UI] +* link:{{navprefix}}/webhooks-comm-channel[Webhook communication channels] +* link:{{navprefix}}/webhooks-lb-schedule[Webhook connection for Liveboard scheduled events] +* 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 connection for KPI alerts] + +[.sidebar-title] +Integration with external tools + +** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] +** link:{{navprefix}}/pendo-integration[Pendo integration with embed] +** link:{{navprefix}}/sf-integration[Integration with Salesforce] +** link:{{navprefix}}/vercel-integration[Vercel integration] + +[.sidebar-title] +Build and deploy + +** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects] +** link:{{navprefix}}/timezone-aware-filtering[Timezone-aware keywords and filters] +** link:{{navprefix}}/variables[Variables] +** link:{{navprefix}}/parameterize-metadata[Parameterize metadata] +* link:{{navprefix}}/development-and-deployment[Development and deployment] +** link:{{navprefix}}/deploy-with-tml-apis[Deploy with TML APIs] +*** link:{{navprefix}}/git-provider-integration[Git provider integration] +*** link:{{navprefix}}/modify-tml[TML modification] +* link:{{navprefix}}/publish-data-overview[Publish content to Orgs] +** link:{{navprefix}}/publish-to-orgs[Publish objects to Orgs] +* link:{{navprefix}}/git-integration[Deploy with GitHub APIs (legacy)] +** link:{{navprefix}}/git-configuration[Configure GitHub integration] +** link:{{navprefix}}/git-api[GitHub REST APIs] +** link:{{navprefix}}/guid-mapping[GUID mapping] + +[.sidebar-title] +REST APIs + +* link:{{navprefix}}/rest-apis[Overview] +* link:{{navprefix}}/rest-apiv2-getstarted[Get started] +* link:{{navprefix}}/api-authv2[REST API v2.0 authentication] +* link:{{navprefix}}/rest-apiv2-reference[REST API v2.0 Reference] +** link:{{navprefix}}/api-user-management[Users and group privileges] +** link:{{navprefix}}/rbac[Role-based access control] +** link:{{navprefix}}/rest-apiv2-search[Search API endpoints] +*** link:{{navprefix}}/rest-apiv2-users-search[Search users] +*** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] +*** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] +** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/spotter-api[Spotter APIs] +*** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] +*** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] +*** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] +*** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] +** link:{{navprefix}}/style-customization-apis[Style customization APIs] +** link:{{navprefix}}/audit-logs[Audit logs] +** link:{{navprefix}}/tml[TML] +** link:{{navprefix}}/collections[Collections ^BETA^] +** link:{{navprefix}}/connections[Connections] +** link:{{navprefix}}/connection-config[Connection configuration] +** link:{{navprefix}}/runtime-sort[Runtime sorting] +* link:{{navprefix}}/manual-translation-api[Manual translations] +* link:{{navprefix}}/webhooks-rest-api[Webhook APIs] + +[.sidebar-title] +REST API SDK + +* link:{{navprefix}}/rest-api-sdk[Overview] +* link:{{navprefix}}/rest-api-sdk-typescript[TypeScript SDK] +* link:{{navprefix}}/rest-api-sdk-java[Java SDK] +* link:{{navprefix}}/rest-apiv2-js[REST API v2.0 in JavaScript] + +[.sidebar-title] +REST API v1 (DEPRECATED) + +* link:{{navprefix}}/rest-api-getstarted[Get started] +* link:{{navprefix}}/api-auth-session[REST API v1 authentication] +* link:{{navprefix}}/catalog-and-audit[Catalog and audit content] +* link:{{navprefix}}/rest-api-pagination[Paginate API response] +* link:{{navprefix}}/rest-api-reference[REST API v1 Reference] +* link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog] +* link:{{navprefix}}/v1v2-comparison[REST v1 and v2.0 comparison] + + +[.sidebar-title] +SpotterCode + +* link:{{navprefix}}/SpotterCode[SpotterCode for IDEs] +* link:{{navprefix}}/integrate-SpotterCode[Integrating SpotterCode] +* link:{{navprefix}}/spottercode-prompting-guide[SpotterCode prompting guide] + +[.sidebar-title] +Tutorials + +* link:{{navprefix}}/tutorials/tutorials-overview[Embedding tutorials] +** link:{{navprefix}}/tutorials/tse-fundamentals/intro[Embedding Fundamentals] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-01[01 - Overview] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-02[02 - Set up for course] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-03[03 - Security setup] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-04[04 - Start coding] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-05[05 - Embed Search] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-06[06 - Embed Natural Language Search] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-07[07 - Embed Liveboard] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-08[08 - Embed Visualization] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-09[09 - Embed full application] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-10[10 - Style embedded app] +*** link:{{navprefix}}/tutorials/tse-fundamentals/lesson-11[11 - Course summary] +*** link:{{navprefix}}/tutorials/style-customization/tutorial[Style customization] +** link:{{navprefix}}/tutorials/react-components/intro[React components] +*** link:{{navprefix}}/tutorials/react-components/lesson-01[01 - Initialize Visual Embed SDK] +*** link:{{navprefix}}/tutorials/react-components/lesson-02[02 - ThoughtSpot component pages] +*** link:{{navprefix}}/tutorials/react-components/lesson-03[03 - Menus and navigation elements] +*** link:{{navprefix}}/tutorials/react-components/lesson-04[04 - Event handling] +** link:{{navprefix}}/tutorials/spotter/integrate-into-chatbot[Integrate Spotter into your Chatbot] + +* link:{{navprefix}}/tutorials/rest-api/intro[REST API Tutorials] +** link:{{navprefix}}/tutorials/rest-api/lesson-01[01 - REST API overview] +** link:{{navprefix}}/tutorials/rest-api/lesson-02[02 - Simple Python implementation] +** link:{{navprefix}}/tutorials/rest-api/lesson-03[03 - Complex REST API workflows] + + +[.sidebar-title] +Additional resources + +* link:{{navprefix}}/embed-ts[About ThoughtSpot embedding] +* link:{{navprefix}}/faqs[FAQs] +* link:https://codesandbox.io/s/big-tse-react-demo-i4g9xi[React CodeSandbox, window=_blank] +* link:https://community.thoughtspot.com/customers/s/[Community, window=_blank] +* link:https://training.thoughtspot.com/page/developer[Training resources, window=_blank] +* link:https://docs.thoughtspot.com[Product Documentation, window=_blank] +* link:https://github.com/thoughtspot/developer-examples[Developer examples, window=_blank] + diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index e93dd9a77..faa813ba1 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -12,23 +12,29 @@ REST APIs * link:{{navprefix}}/api-authv2[REST API v2.0 authentication] * link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fgetting-started%2Fintroduction[REST API v2 Playground] -* link:{{navprefix}}/api-user-management[Users and group privileges] -* link:{{navprefix}}/rbac[Role-based access control] -* link:{{navprefix}}/rest-apiv2-search[Search API endpoints] -** link:{{navprefix}}/rest-apiv2-users-search[Search users] -** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] -** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] -* link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] -* link:{{navprefix}}/spotter-api[Spotter APIs] -** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +* link:{{navprefix}}/rest-apiv2-reference[REST API v2.0 Reference] +** link:{{navprefix}}/api-user-management[Users and group privileges] +** link:{{navprefix}}/rbac[Role-based access control] +** link:{{navprefix}}/rest-apiv2-search[Search API endpoints] +*** link:{{navprefix}}/rest-apiv2-users-search[Search users] +*** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] +*** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] +** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/spotter-api[Spotter APIs] +*** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] +*** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] +*** link:{{navprefix}}/spotter-agent-conversation-mgmt-apis[APIs for managing saved conversations] ** link:{{navprefix}}/spotter-apis-classic[AI APIs (Spotter Classic) ^BETA^] -** link:{{navprefix}}/spotter-nl-instructions[Spotter instructions APIs ^BETA^] -* link:{{navprefix}}/audit-logs[Audit logs] -* link:{{navprefix}}/tml[TML] -* link:{{navprefix}}/collections[Collections ^BETA^] -* link:{{navprefix}}/connections[Connections] -* link:{{navprefix}}/connection-config[Connection configuration] -* link:{{navprefix}}/runtime-sort[Runtime sorting] +** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] +** link:{{navprefix}}/style-customization-apis[Style customization APIs] +** link:{{navprefix}}/audit-logs[Audit logs] +** link:{{navprefix}}/tml[TML] +** link:{{navprefix}}/collections[Collections ^BETA^] +** link:{{navprefix}}/connections[Connections] +** link:{{navprefix}}/connection-config[Connection configuration] +** link:{{navprefix}}/runtime-sort[Runtime sorting] +** link:{{navprefix}}/manual-translation-api[Manual translations] +** link:{{navprefix}}/webhooks-rest-api[Webhook APIs] [.sidebar-title] @@ -39,16 +45,6 @@ REST API SDK * link:{{navprefix}}/rest-api-sdk-java[Java SDK] * link:{{navprefix}}/rest-apiv2-js[REST API v2.0 in JavaScript] -[.sidebar-title] -Webhooks - -* link:{{navprefix}}/webhooks[Overview] -* link:{{navprefix}}/webhooks-comm-channel[Configure and monitor webhook communication channels] -* link:{{navprefix}}/webhooks-s3-integration[Deliver Liveboard reports to AWS S3 Storage] -* link:{{navprefix}}/webhooks-lb-schedule[Deliver Liveboard reports to external application] -* link:{{navprefix}}/webhooks-lb-payload[Webhook response payload] -* link:{{navprefix}}/webhooks-kpi[Webhook for KPI alerts] - [.sidebar-title] REST API Tutorials @@ -65,28 +61,14 @@ REST API v1 (DEPRECATED) * link:{{navprefix}}/catalog-and-audit[Catalog and audit content] * link:{{navprefix}}/rest-api-pagination[Paginate API response] * link:{{navprefix}}/rest-api-reference[REST API v1 Reference] -** link:{{navprefix}}/orgs-api[Orgs API] -** link:{{navprefix}}/user-api[User API] -** link:{{navprefix}}/group-api[Group API] -** link:{{navprefix}}/role-api[Role API] -** link:{{navprefix}}/session-api[Session API] -** link:{{navprefix}}/connections-api[Data connection API] -** link:{{navprefix}}/metadata-api[Metadata API] -** link:{{navprefix}}/admin-api[Admin API] -** link:{{navprefix}}/tml-api[TML API] -** link:{{navprefix}}/dependent-objects-api[Dependent objects API] -** link:{{navprefix}}/search-data-api[Search data API] -** link:{{navprefix}}/liveboard-data-api[Liveboard data API] -** link:{{navprefix}}/liveboard-export-api[Liveboard export API] -** link:{{navprefix}}/security-api[Security API] -** link:{{navprefix}}/logs-api[Audit logs API] -** link:{{navprefix}}/materialization-api[Materialization API] -** link:{{navprefix}}/database-api[Database API] -** link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog] -** link:{{navprefix}}/v1v2-comparison[REST v1 and v2.0 comparison] - - -//** link:{{navprefix}}/graphql-guide[GraphQL API ^Beta^] +* link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog] +* link:{{navprefix}}/v1v2-comparison[REST v1 and v2.0 comparison] + +[.sidebar-title] +Additional resources + +* link:{{navprefix}}/faqs[FAQs] +* link:https://github.com/thoughtspot/developer-examples[Developer examples, window=_blank] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 46054b4c0..141aada68 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -75,7 +75,21 @@ Multi-tenancy ** link:{{navprefix}}/single-tenant-data-models[Single-tenant data models with Orgs] * link:{{navprefix}}/tse-cluster[Cluster maintenance and upgrade] -* Integration with external tools +[.sidebar-title] +Webhooks + +* link:{{navprefix}}/webhooks-overview[Overview] +* link:{{navprefix}}/webhooks-ui[Webhooks UI] +* link:{{navprefix}}/webhooks-comm-channel[Webhook communication channels] +* link:{{navprefix}}/webhooks-lb-schedule[Webhook connection for Liveboard scheduled events] +* 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 connection for KPI alerts] + +[.sidebar-title] +Integration with external tools + ** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] ** link:{{navprefix}}/pendo-integration[Pendo integration with embed] ** link:{{navprefix}}/sf-integration[Integration with Salesforce] @@ -86,11 +100,7 @@ Additional resources * link:{{navprefix}}/faqs[FAQs] * link:https://codesandbox.io/s/big-tse-react-demo-i4g9xi[React CodeSandbox, window=_blank] -//** link:https://codesandbox.io/s/graphqlcookieembed-wf4fk9?file=/src/App.js:418-426[GraphQL CodeSandbox, window=_blank] - * link:https://community.thoughtspot.com/customers/s/[Community, window=_blank] * link:https://training.thoughtspot.com/page/developer[Training resources, window=_blank] * link:https://docs.thoughtspot.com[Product Documentation, window=_blank] -* link:https://developers.thoughtspot.com[ThoughtSpot Developers, window=_blank] -* Deprecated feature docs -** link:{{navprefix}}/abac-user-parameters-beta[ABAC via tokens (pre-10.4.0.cl) (Deprecated)] +* link:https://github.com/thoughtspot/developer-examples[Developer examples, window=_blank] diff --git a/modules/ROOT/pages/configure-saml.adoc b/modules/ROOT/pages/configure-saml.adoc index 404aef6fb..68746d6d2 100644 --- a/modules/ROOT/pages/configure-saml.adoc +++ b/modules/ROOT/pages/configure-saml.adoc @@ -114,12 +114,36 @@ disableSAMLAutoRedirect=true Make a note of all of the redirects within the SAML workflow. Each server must be configured properly to allow the inbound and outbound portions of the SAML flow. If you encounter errors while configuring and testing, go to the *Network* tab of the browser's developer tools to see which server within the workflow is generating the error. ==== +[#per-org-idp-org-isolation] +=== Org isolation for per-org IdP authentication + +// SOURCE: SCAL-291968 — OIDCClient.java, OrgUtils.java, SecurityEventTypeEnum.java +When your ThoughtSpot cluster uses per-org IdP configuration — where each Org is bound to its own identity provider — ThoughtSpot enforces strict org isolation on all incoming SAML and OIDC group and org claims. + +==== How it works + +When a user authenticates through a per-org IdP, ThoughtSpot identifies the **authorized Org** associated with that IdP. It then evaluates every group and org claim in the assertion: + +* Claims that reference the authorized Org are accepted and processed normally. +* Claims that reference any other Org are **silently dropped**. They do not grant access to those Orgs, and they are not used for group provisioning in those Orgs. +* Group claims that carry no Org suffix are automatically scoped to the authorized Org. + +For example, if a user logs in through IdP-A, which is bound to Org X, a claim of `PowerUser@X` is accepted. A claim of `Admin@Y` is dropped. + +NOTE: Org isolation applies only to per-org IdP logins. Cluster-wide (single IdP) SSO configurations are not affected. + +==== Effect on existing org memberships + +Logging in through a per-org IdP can affect existing Org memberships. When a user authenticates via a per-org IdP, ThoughtSpot evaluates and reconciles the user's Org memberships based on the claims scoped to that IdP's authorized Org. + +Alternatively, authenticating through a cluster-wide (primary Org) IdP does not alter existing group memberships. + == Configuration steps To configure SAML SSO authentication on the ThoughtSpot embedded instance, complete the following steps: * xref:configure-saml.adoc#admin-portal[Enable SAML authentication on ThoughtSpot with IAMv1] -* xref:configure-saml.adoc#IAMv2[Enable SAML authentication on ThoughtSpot with IAMv2] (Requires assistance from ThoughtSpot Support) +* xref:configure-saml.adoc#IAMv2[Enable SAML authentication on ThoughtSpot with IAMv2] * xref:configure-saml.adoc#idp-config[Configure the IdP server for SAML authentication] * xref:configure-saml.adoc#auth-config-sdk[Enable SSO authentication in Visual Embed SDK] * xref:configure-saml.adoc#saml-redirect[Add SAML redirect domain to the allowed list in ThoughtSpot] @@ -282,6 +306,7 @@ The accepted format is `PEM / .cer / .crt`. Your users can sign in using the updated certificate immediately. If users experience sign-in failures after a certificate rotation, verify that the certificate in ThoughtSpot matches the certificate currently active on your IdP. + [#idp-config] === Configure the IdP server for SAML authentication To enable IdP to recognize your host application and ThoughtSpot as a valid service provider, you must configure the IdP with the required attributes and metadata. diff --git a/modules/ROOT/pages/customize-homepage-full-embed.adoc b/modules/ROOT/pages/customize-homepage-full-embed.adoc index 954cb8da5..70d9b1bbf 100644 --- a/modules/ROOT/pages/customize-homepage-full-embed.adoc +++ b/modules/ROOT/pages/customize-homepage-full-embed.adoc @@ -13,18 +13,25 @@ Developers can customize the home page experience in full application embedding The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. ==== +[NOTE] +==== +The focused homepage experience is an Early Access feature and is disabled by default. To enable this experience in your embedding application, ensure that the feature is enabled on your ThoughtSpot instance and in the Visual Embed SDK. +==== + == Home page layout In the classic (V1) experience, the home page has a static layout and does not support SDK modular customization settings. -In the V3 experience, the SDK provides the xref:HomePage.adoc[homePage] attribute to set the desired home page layout: +The SDK provides the xref:HomePage.adoc[homePage] attribute to set the desired home page layout: +* `homePage: HomePage.Focused` [earlyAccess eaBackground]#Early Access# + +Enables the V4 home page experience. * `homePage: HomePage.ModularWithStylingChanges` + Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout. * `homePage: HomePage.Modular` + Enables the basic modular home page experience with customizable components. -After migrating from V2 to V3 experience, the home page experience shows the following changes: +Both V2 and V3 home page experience show customization modules. The V3 home page experience improves the layout with the following enhancements: * The charts in the **Watchlist** module are arranged horizontally. Each chart includes menu actions to remove the KPI charts from the watchlist and create alerts, and allows drag-and-drop reordering. + @@ -45,6 +52,32 @@ image::./images/favoritesV3.png[V2 and V3 Trending module, scaledwidth=50%] In both V2 and V3, the SDK allows customization to include or exclude modules, change their order, and adjust the overall layout. +[#_enable_focused_home_page] +=== V4 focused home page experience +The V4 focused home page (`HomePage.Focused`) provides a contemporary experience designed to highlight the most relevant content immediately. It provides quick access to the Spotter interface and consolidates the **Watchlist KPIs** and **Recents** sections into a unified, focused layout. + +The following example shows how to enable the V4 focused home page experience: + +[source,javascript] +---- +import { + AppEmbed, + PrimaryNavbarVersion, // Enum for V3 navigation experience + HomePage, // Enum for home page experience settings + HomepageModule // Enum for home page modules +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Enable V3 navigation and V4 home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience + homePage: HomePage.Focused, // Enable V4 focused home page experience + }, + showPrimaryNavbar: true, + //... other embed view configuration attributes +}); +---- + == Customization settings for home page The following customization settings are available for the modular home page in the V2 and V3 experience modes. @@ -89,6 +122,53 @@ Hides xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on | [tag greenBackground tick]#✓# Supported |==== +//// +[width="100%", cols="2,2,2,2,2"] +[options='header'] +|==== +|SDK property|Classic (V1) experience|V2 experience|V3 experience|V4 experience + +(`HomePage.Focused`) +| `hiddenHomepageModules` + +Controls the visibility of the modules on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| +| `reorderedHomepageModules` + +Arranges home page modules in the specified order. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `homePageSearchBarMode` + +Sets the home page search bar experience to object search, Spotter/AI search, or none. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `isUnifiedSearchExperienceEnabled` + +Enables a combined interface with both Object Search and Natural Language Search. The unified experience is disabled by default. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + + +| `hideHomepageLeftNav` + +Hides the xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on_home_page[left navigation panel] on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `hiddenHomeLeftNavItems` + +Hides xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on_home_page[specific menu items of the left navigation panel] on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| // TODO: verify with engineering — confirm which nav items are available in V4 +|==== +//// + == Control the visibility of home page modules In the V2 and V3 experience modes, the home page includes sections such as *Watchlist*, *Favorites*, *Library*, *Trending* charts, and more. You can hide a specific section of the home page and reorder these modules as needed using the xref:AppViewConfig.adoc#_hiddenhomepagemodules[hiddenHomepageModules] and xref:AppViewConfig.adoc#_reorderedhomepagemodules[reorderedHomepageModules] configuration options in the embed SDK. @@ -147,7 +227,7 @@ The following example shows the configuration properties for customizing the hom ---- import { AppEmbed, // Main class to embed the full ThoughtSpot app - PrimaryNavbarVersion // Enum for V3 experience setting + PrimaryNavbarVersion, // Enum for V3 experience setting HomePage, // Enum for home page experience settings HomepageModule // Enum for home page modules } from '@thoughtspot/visual-embed-sdk'; @@ -186,7 +266,7 @@ The following example shows the configuration properties for customizing the hom } from '@thoughtspot/visual-embed-sdk'; const embed = new AppEmbed("#embed", { // Enable V2 experience - modularHomeExperience: true + modularHomeExperience: true, // Hide modules from the home page hiddenHomepageModules: [ HomepageModule.Learning, @@ -224,7 +304,7 @@ To hide the search bar on the home page, you can also use the xref:customize-hom [NOTE] ==== -If your instance is using the Classic (v1) experience and if the `homePageSearchBarMode` parameter does not set the search context defined in the attribute, set `isUnifiedSearchExperienceEnabled` to `false`. +If your instance is using the Classic (v1) experience and if the `homePageSearchBarMode` parameter does not set the search context defined in the attribute, set `isUnifiedSearchExperienceEnabled` to `false`. ==== ==== Examples diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index 29b2e42cd..cb4b45ceb 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -44,10 +44,16 @@ a| * Left navigation ** A sliding left navigation panel controlled via the hamburger icon ** Persona-based app selection icons in the panel header -** Left navigation menu that adjusts its contents according to the application context. +** Left navigation menu that adjusts its contents according to the application context |==== +[NOTE] +==== +The V4 focused home page experience (`HomePage.Focused`) uses the same navigation customization controls as the V3 experience. All SDK properties listed in this article apply to the V4 experience when `PrimaryNavbarVersion.Sliding` is also configured. +==== + == Customize the top navigation bar + The following customization settings are available for the top navigation bar. [width="100%", cols="2,2,2,2"] @@ -74,7 +80,7 @@ In the V3 experience, hides the app selection icons on the left navigation panel To show or hide the help and user profile icons in top navigation bar. | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported + -Also hides or shows *Help* menu on the left navigation panel of the home page. +Also hides or shows the *Help* menu on the left navigation panel of the home page. | [tag greenBackground tick]#✓# Supported + | `hideOrgSwitcher` + @@ -98,8 +104,8 @@ The object search bar is hidden by default. | `hideHamburger` + To show or hide the hamburger icon in the top navigation bar. -| __ Not applicable__ -| __ Not applicable__ +| __Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported + Hides the hamburger icon available on pages where the left navigation panel is hidden by default. |==== @@ -144,62 +150,62 @@ If you want to include the left navigation, but hide only a specific section in | `HomeLeftNavItem.Create` + To show or hide the `+` icon that allows users to create a Liveboard or Answer in the *Insights* panel. -| __ Not applicable__ -| __ Not applicable__ +| __Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Home` + To show or hide the *Home* menu in the *Insights* panel. -| __ Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Spotter` + To show or hide the *Spotter* menu item in the *Insights* panel. -| __ Not applicable__ -| __ Not applicable__ +| __Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.SearchData` + To show or hide the *Search Data* in the *Insights* panel. -| __ Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Liveboards` + To show or hide the *Liveboards* menu in the *Insights* panel. -| __ Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Answers` + To show or hide the *Answers* menu in the *Insights* panel. -| __ Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.LiveboardSchedules` + -To show or hide the *LiveboardSchedules* menu in the *Insights* panel. -| __ Not applicable__ +To show or hide the *Liveboard Schedules* menu in the *Insights* panel. +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.MonitorSubscription` + To show or hide the *Monitor subscriptions* in the *Insights* panel. -| __ Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.SpotIQAnalysis` + To show or hide the *SpotIQ analyses* in the *Insights* panel. -| __ Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Favorites` + To show or hide the `Favorites` section in the *Insights* panel. -| __ Not applicable__ -| __ Not applicable__ +| __Not applicable__ +| __Not applicable__ | [tag greenBackground tick]#✓# Supported |=== diff --git a/modules/ROOT/pages/customize-style-api.adoc b/modules/ROOT/pages/customize-style-api.adoc new file mode 100644 index 000000000..252c7f3d7 --- /dev/null +++ b/modules/ROOT/pages/customize-style-api.adoc @@ -0,0 +1,409 @@ += Style customization APIs +:toc: true +:toclevels: 3 + +:page-title: Customize styles and layout through REST APIs +:page-pageid: style-customization-apis +:page-description: Customize styles, design, and layout of embedded ThoughtSpot app using REST APIs + +// SOURCE: SCAL-293070, SCAL-293071 + + +ThoughtSpot provides REST API v2.0 endpoints to manage style customization settings programmatically. These APIs expose the same branding and theming controls available in the *Develop* > *Customizations* > *Styles* page, enabling you to automate branding and white-labeling — including across multiple Orgs — without logging in to the ThoughtSpot UI. + +[NOTE] +==== +All style customization API endpoints require administrator or developer privileges. +==== + +=== Style configuration + +Use the following endpoints to search and update style settings at the cluster or Org scope. + +==== Search style configuration +To get the current style configuration for the cluster and the active Org send an API request to `POST /api/rest/2.0/customization/styles/search` endpoint. +When called from the Primary Org (Org 0), the response returns one record with `"scope": "CLUSTER"` and one with `"scope": "ORG"`. + +==== Update style configuration +To update the style settings send an API request to `POST /api/rest/2.0/customization/styles/update` endpoint. + +Request parameters:: + +[cols="2,1,4"] +|===== +|Parameter|Required|Description +|`scope`|Yes|`CLUSTER` or `ORG`. +//|`org_identifier`|Conditional|Required when `scope` is `ORG`. +|`operation`|Yes|`REPLACE` overwrites existing settings. `RESET` reverts specific fields to defaults. +|`navigation_panel`|No|Top navigation panel color. Can be `DARK`, `TWO_TONE` or `CUSTOM`. A valid hex value for `base_color` is needed only when `theme` is `CUSTOM`. +|`chart_color_palette`|No|Array of hex color values for charts. When provided with `REPLACE`, exactly 8 `primary` color entries must be specified in colors. `secondary` color entries, if provided, should be exactly 4 in number for each `primary` color. If `secondary` shades are omitted, the server auto-generates 4 shades from the primary color. +|`embedded_footer_text`|No|Footer text for embedded content. +|`visualization_fonts`|No|Font assignments for visualization elements. Provide only the areas to update; omitted areas remain unchanged. +|`default_logo`|No|Binary image file for the square application logo. Accepted formats are PNG, JPG, and JPEG only. +|`wide_logo`|No|Binary image file for the wide logo (email and PDF exports). +|`reset_options`|No|Resets specified settings to ThoughtSpot defaults. Used when `operation` is `RESET`. +|===== + +Example API request:: To set a custom navigation panel color at cluster scope + + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "operation": "REPLACE", + "navigation_panel": { + "theme": "CUSTOM", + "base_color": "#2359B6" + } +} +---- + +Example API request:: To update chart color palette for a specific Org (REPLACE) + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "ORG", + "operation": "REPLACE", + -F 'embedded_footer_text=Test%20footer%20text' \ + -F 'chart_color_palette={ + "colors":[ + {"primary":"#9F2B68", + "secondary":["#00FFFF","#00FFFF","#00FFFF","#FF0000"]}, + {"primary":"#FF0080"}, + {"primary":"#FF8000"}, + {"primary":"#FF0000"}, + {"primary":"#FFFF00"}, + {"primary":"#00FF80"}, + {"primary":"#FF00FF"}, + {"primary":"#2359B6"}], + "disable_color_rotation":false}' \ + -F 'visualization_fonts={ + "chart_visualization_fonts":[{"visualization_area":"CHART_X_AXIS_LABELS","font_identifier":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}], + "table_visualization_fonts":[{"visualization_area":"TABLE_VALUE_CELLS","font_identifier":"Acme Sans"}], + "advanced_chart_visualization_fonts":[{"visualization_area":"ADVANCED_CHART_LABELS","font_identifier":"Acme Sans"}] + }' + } +---- + +Example API request:: To reset style options at the org level + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + -F 'scope=ORG' \ + -F 'operation=RESET' \ + -F 'reset_options={"style":["CHART_COLOR_PALETTE"],"visualization_areas":["CHART_X_AXIS_LABELS"]}' + } +---- + +API response:: +If the API request is successful, ThoughtSpot returns a 200 or 204 success code. + +=== Custom fonts + +==== Upload a custom font +To upload a font file (multipart/form-data) send an API request to `POST /api/rest/2.0/customization/styles/fonts/upload` endpoint. + +Request parameters:: + +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`name` +|Yes +|Display name for the font. + +|`file_content` +|Yes +|Binary font file. Accepted formats: WOFF and WOFF2 only. + +|`scope` +|No +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. +Defaults to `ORG` when Orgs are enabled; defaults to `CLUSTER` when Orgs are disabled. + +|`weight` +|No +|Font weight. Valid values: `NORMAL`, `LIGHT`, `BOLD`. + +|`style` +|No +|Font style. Valid values: `NORMAL`, `ITALIC`, `OBLIQUE`. + +|`color` +|No +|Default color for the font as a 6-digit hex string. Example: `#333333`. + +|===== + +Example API request:: +[source,cURL] +---- +curl -X POST 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/upload' \ +-H 'Authorization: Bearer {token}' \ +-H 'Accept: application/json' \ +-H 'Accept: application/json'\ +-H 'Content-Type: application/json' \ +--data-raw '{ +-F 'name=Acme Sans' \ +-F 'file_content=@/path/to/acme-sans-bold.woff2' +-F 'scope=ORG' \ +-F 'weight=BOLD' \ +-F 'style=NORMAL' \ +-F 'color=#333333' \ +} +---- + +API response:: +If the API request is successful, ThoughtSpot returns the details of the uploaded font. + +[source,JSON] +---- +{ +"id": "c3d4e5f6-1111-1111-1111-111111111111", +"name": "Acme Sans" +} +---- + +==== Search custom fonts +To get custom fonts uploaded to the instance or the Org, send an API request to the `POST /api/rest/2.0/customization/styles/fonts/search` endpoint. + +Request parameter:: +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`scope` +|Yes +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. + + +|`font_identifier` +|No +|Filter by exact font GUID or exact display name (case-insensitive). +Cannot be used together with `name_pattern`. + +|`name_pattern` +|No +|Filter by partial, case-insensitive substring match on font display name. +Cannot be used together with `font_identifier`. + +|`include_font_assignments` +|No +|If `true`, each font in the response includes the visualization areas it is assigned to. +Default: `false`. + +|===== + +Example API request:: +Return all fonts with their visualization assignments + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/search' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "include_font_assignments": true +} +---- + +Example API request:: Filter by name pattern +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/search' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "ORG", + "org_identifier": "Sales Org", + "name_pattern": "acme", + "include_font_assignments": false +} +---- + +API response:: +If the API request is successful, ThoughtSpot returns the font and its assignment details. + +[source,JSON] +---- +[ + { + "id": "c3d4e5f6-1111-1111-1111-111111111111", + "scope": "ORG", + "org": { + "id": 1234567890, + "name": "Sales" + }, + "name": "Acme Sans", + "weight": "NORMAL", + "style": "NORMAL", + "color": "#333333", + "creation_time_in_millis": 1714000000000, + "assignments": [ + { + "org": { + "id": 1234567890, + "name": "Sales" + }, + "visualization_areas": [ + "CHART_X_AXIS_LABELS", + "CHART_Y_AXIS_LABELS" + ] + } + ] + }, + { + "id": "d4e5f6a7-2222-2222-2222-222222222222", + "scope": "CLUSTER", + "name": "Corporate Bold", + "weight": "BOLD", + "style": "NORMAL", + "color": "#000000", + "creation_time_in_millis": 1713500000000, + "assignments": [] + } +] +---- + +==== Update a custom font +To update an existing font's display name, weight, style, or color send an API request to the `POST /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` endpoint. + +Request parameters:: + +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`font_identifier` +|Yes +|GUID or display name of the font to update. Passed as a path parameter. + +|`scope` +|Yes +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. + +|`name` +|No +|New display name for the font. Omit to leave unchanged. + +|`weight` +|No +|Updated font weight. Valid values: `NORMAL`, `LIGHT`, `BOLD`. +Omit to leave unchanged. + +|`style` +|No +|Updated font style. Valid values: `NORMAL`, `ITALIC`, `OBLIQUE`. +Omit to leave unchanged. + +|`color` +|No +|Updated default color as a 6-digit hex string. Example: `#333333`. +Omit to leave unchanged. + +|===== + +Example API request:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "name": "Acme Sans Revised", + "weight": "BOLD", + "color": "#111111" + } + +---- + +==== Delete custom fonts +To delete one or more custom fonts from the font library send an API request to the `POST /api/rest/2.0/customization/styles/fonts/delete` endpoint. + +Request parameter:: +[cols="2,1,4"] +|===== +|Parameter|Required|Description + +|`scope` +|Yes +|Scope of the font library. Valid values: `CLUSTER`, `ORG`. To delete a `CLUSTER` level font, you require `ADMINISTRATION` privilege. + + +|`font_identifiers` +|Yes +|List of font GUIDs or display names to delete. +Duplicate values are deduplicated automatically. + +|`dry_run` +|No +|If `true`, returns the list of affected visualization assignments without deleting any fonts. When a font is deleted, all visualization areas that used it are automatically reset to the system default font. Set to `false` to commit the deletion. +Default: `true`. + +|===== + + +Example API request:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/fonts/delete' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER", + "font_identifiers": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "b2c3d4e5-f6a7-8901-bcde-f12345678901" + ], + "dry_run": true +} +---- + +=== Logo export +To get the configured logos at the requested scope as a ZIP archive containing the default and wide logo images, send an API request to the `POST /api/rest/2.0/customization/styles/logos/export` endpoint. +If no custom logo is configured for the Org, the system falls back to the cluster logo. If a cluster logo is also unavailable, the endpoint returns an empty response with a `200 OK` status. + +Example API request:: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/styles/logos/export' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "scope": "CLUSTER" +} +---- \ No newline at end of file diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index a1e1e494e..b95b51895 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -13,6 +13,8 @@ ThoughtSpot provides the following REST API v2 endpoints to fetch data: * xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. * xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. +If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. + === Search data API The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. @@ -231,6 +233,8 @@ To download a personalized view of the Liveboard, specify the view name in the ` * The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. * If the Liveboard includes Note tiles, ensure that you do not pass the GUID of Note tiles as `visualization_identifiers` in the API request. Attempting to do so will lead to an error, and the API will return 400 error code in response. * Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. +* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Liveboard exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. ==== ==== File Formats @@ -461,6 +465,12 @@ In the request body, specify the GUID or name of the Answer object as `metadata_ The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. +[IMPORTANT] +==== +* If Role-Based Access Control (RBAC) is enabled, `DATADOWNLOADING` (Can download Data) privilege is required for Answer exports. +* If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. +==== + ==== Example [source,cURL] diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index 480e99dc8..d90d833e3 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -14,6 +14,8 @@ As ThoughtSpot applications evolve, some existing features will be deprecated an [options='header'] |===== |Feature|Impacted interface and release versions|Deprecation date |End of Support / removal from the product +a|xref:deprecated-features.adoc#liveboardAnswerDiscoverable[Liveboard and answer discoverability] +a|ThoughtSpot Cloud 26.2.0.cl and later | February 2026 | August 2026 a|xref:deprecated-features.adoc#everynmins[Minute-level schedule frequency] |ThoughtSpot Cloud 26.8.0.cl and later | August 2026 | - a|xref:deprecated-features.adoc#hostEventv1[HostEvent v1 framework] @@ -89,9 +91,19 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic |||| |===== +[#liveboardDiscoverable] +== Liveboard and answer discoverability +The **Make this Liveboard discoverable** and **Make this answer discoverable** checkboxes that appear in the Liveboard and Answer create and share workflows are deprecated and will be removed in ThoughtSpot Cloud 26.8.0.cl. + +Impact on your instance:: +When this feature is removed from the UI, your application users will no longer be able to find the objects that are marked as discoverable in the object search results. Object visibility and discoverability will be determined solely by explicit view, edit, or other owner-granted permissions. + +Recommended action:: +Before your instance is upgraded to ThoughtSpot Cloud 26.8.0.cl, identify Liveboards and Answers that are currently set as discoverable and share them with the relevant users or groups. + [#everynmins] == Minute-level schedule frequency -The `POST /api/rest/2.0/schedules/create` and `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoint no longer accept `minute` as a valid `frequency` value for schedule intervals. +The `POST /api/rest/2.0/schedules/create` and `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoints no longer accept `minute` as a valid `frequency` value for schedule intervals. Impact on your instance:: Starting ThoughtSpot 26.8.0.cl, all existing Liveboard schedules set to `minute` as the frequency will be automatically changed to an hourly frequency. @@ -135,7 +147,7 @@ Impact on your instance:: * For new users, API calls to the `POST /api/rest/2.0/report/liveboard` endpoint for PNG exports with `include_cover_page` and `include_filter_page` will result in an error. Use the new PNG export options. //If you still have to use these options for your ThoughtSpot instance contact ThoughtSpot support to revert to these legacy settings. -For more information on PNG export, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API] +For more information on PNG export, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. Recommended action:: * We recommend transitioning to the new flow for PNG exports, as the `include_cover_page` and `include_filter_page` attributes will be removed in a future release. @@ -199,7 +211,7 @@ Starting with 10.4.0.cl, Worksheets are deprecated and disabled by default in Th Impact on your instance:: -All existing Worksheets on your instance will be migrated automatically to Models, and Worksheets will no longer be available in the ThoughtSpot UI after the 10.12.0.cl release. Note that even adding a dbt connection will result in the creation of a Model. However, if you are using Worksheets in Git workflows or CI/CD pipelines that rely on import or create, those will continue to work temporarily until 10.13.0.cl. +All existing Worksheets on your instance will be migrated automatically to Models, and Worksheets will no longer be available in the ThoughtSpot UI after the 10.12.0.cl release. Note that even adding a dbt connection will result in the creation of a Model. However, if you are using Worksheets in Git workflows or CI/CD pipelines that rely on import or create operations, those will continue to work temporarily until 10.13.0.cl. + Starting with 10.13.0.cl, import of worksheet TMLs will be blocked. Any such operations will fail with an error, requiring users to convert Worksheets to Models before importing. You may want to update your CI/CD and Git workflows to use Model TMLs instead of Worksheets. @@ -315,7 +327,7 @@ Note that this change will not impact full application embedding if your host ap == Application background customization via UI -The application background customization option that is currently available on the **Admin** > **Style customization** and **Develop** > **Customizations** > **Styles** will be deprecated in the upcoming version. +The application background customization option that is currently available on the **Admin** > **Style customization** and **Develop** > **Customizations** > **Styles** page will be deprecated in the upcoming version. Effective from:: * ThoughtSpot Cloud 10.3.0.cl @@ -365,7 +377,7 @@ For more information, see xref:abac-user-parameters.adoc[ABAC via token ^Beta^]. == Deprecated parameters in Version Control APIs -The `default_branch_name` and `guid_mapping_branch_name` parameters available with the `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` endpoints are deprecated. +The `default_branch_name` and `guid_mapping_branch_name` parameters available with the `/api/rest/2.0/vcs/git/config/create` and `/api/rest/2.0/vcs/git/config/update` endpoints are deprecated. Effective from:: * ThoughtSpot Cloud 9.10.5.cl diff --git a/modules/ROOT/pages/developer-playground.adoc b/modules/ROOT/pages/developer-playground.adoc index 3394c7bd4..ae6544fd9 100644 --- a/modules/ROOT/pages/developer-playground.adoc +++ b/modules/ROOT/pages/developer-playground.adoc @@ -54,7 +54,7 @@ a|**Add search tokens** + Allows passing search tokens as a query string and executing search. -The following example shows how to create a search a `searchTokenString` and execute search: +The following example shows how to create a `searchTokenString` and execute search: [source, Javascript] ---- @@ -102,7 +102,7 @@ Allows you to view the code for a custom action event. If the embedded instance a|**Use Host Event** -Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. +Allows registering a host event. The registered event triggers an action in the embedded view when **Try Event** is clicked. ++++ Try it out @@ -178,7 +178,7 @@ Allows you to view the code for a custom action event. If the embedded instance a|**Use Host Event** -Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. +Allows registering a host event. The registered event triggers an action in the embedded view when **Try Event** is clicked. a|**Apply custom styles** @@ -228,7 +228,7 @@ Allows you to view the code for a custom action event. If the embedded instance a|**Use Host Event** -Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. +Allows registering a host event. The registered event triggers an action in the embedded view when **Try Event** is clicked. a|**Apply custom styles** @@ -270,7 +270,7 @@ Allows you to view the code for a custom action event. If the embedded instance a|**Use Host Event** -Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. +Allows registering a host event. The registered event triggers an action in the embedded view when **Try Event** is clicked. ++++ Try it out @@ -328,7 +328,7 @@ include::{path}/set-runtime-overrides.adoc[] Try it out ++++ -a|**Modify available actions ** +a|**Modify available actions** include::{path}/modify-available-actions.adoc[] @@ -342,7 +342,7 @@ Allows you to view the code for a custom action event. If the embedded instance a|**Use Host Event** + -Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. +Allows registering a host event. The registered event triggers an action in the embedded view when **Try Event** is clicked. ++++ Try it out @@ -415,7 +415,7 @@ Allows you to view the code for a custom action event. If the embedded instance ++++ a|**Use Host Event** + -Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. +Allows registering a host event. The registered event triggers an action in the embedded view when **Try Event** is clicked. ++++ Try it out @@ -431,6 +431,79 @@ For more information about CSS variables, styles, and customizations options, se ++++ |==== +[#spottercode-panel] +== SpotterCode panel +If SpotterCode Agent for Visual Embed Playground is enabled on your instance, the Playground page displays the SpotterCode slideout panel on the right side of the Playground area. SpotterCode Agent is an AI-powered coding assistant built into the Visual SDK Playground to help developers build embedding code rapidly and iterate on embed configurations without writing boilerplate code manually. + +To open SpotterCode in the Playground: + +. Go to *Develop* > *Playground* > *Visual embed*. +. Select the component you want to embed. +. Click *SpotterCode* on the right side of the Playground to open the panel. ++ +The SpotterCode panel opens on the right. The header shows *SpotterCode* on the left and a collapse/expand control on the right. + +=== Quick starter prompts +The SpotterCode panel displays a set of quick starter prompts for each embed component by default. + +[cols="1,3", options="header"] +|==== +| Embed component | Quick-starter prompts +| *Search Data* +a| +* Embed a search view with runtime filters +* Display search results in a structured table with sorting enabled +* Keep the data panel collapsed for a cleaner search view + +| *Liveboard* +a| +* Embed this Liveboard with default filters +* Add a custom action to send Liveboard data to Slack +* Apply runtime filters to this Liveboard + +| *Visualization* +a| +* Embed a single visualization from this Liveboard +* Add a custom action to send this chart data to Slack +* Apply runtime filters to this visualization + +| *Full App* +a| +* Embed full app with navigation enabled +* Enable Spotter in the embedded app +* Change the "Edit" label to "Modify" + +| *Spotter* +a| +* Embed Spotter as an AI assistant in my app +* Configure Spotter to open in a side panel +* Add a button to launch Spotter in the UI +|==== + +When a user clicks a quick-starter prompt, a query is sent to SpotterCode. + +=== Response generation +The chat interface includes the following options: + +* To get precise results: +** Be specific about the component, configuration, and desired behavior. +** Use one prompt per change. Break complex requests into smaller sequential steps. For prompt writing tips and examples, see xref:spottercode-prompt-guide.adoc[SpotterCode prompting guide]. +* To edit a request, click the edit icon to modify your prompt and resend it. +* To clear a chat and reset the conversation context, click *Reset chat*. +* To cancel a request or stop code generation, click the pause button in the chat prompt. + +When SpotterCode processes your prompt, it: + +. generates the embed code for your request. +. updates the code editor panel on the left with the generated code. +. scrolls automatically to show new content in the chat panel. + +After SpotterCode updates the code editor: + +. Review the generated code in the left panel. If SpotterCode detects a conflict between the generated code and the existing code in the editor, it does not update the editor. Ensure that you review the current code in the editor, clear conflicting sections, and try your prompt again. +. Click *Run* to execute the code and preview the embedded component in the preview panel. +. Iterate by entering a follow-up prompt or editing the code directly. + == Additional resources For more information about the configuration settings and parameters, see the following pages: diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 79715ec88..131108899 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -56,6 +56,7 @@ const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { liveboardId: '<%=liveboardGUID%>', }); ---- + For more information about the Liveboard embed object, classes, methods, interface properties, and enumeration members, see the following pages: * xref:LiveboardEmbed.adoc[LiveboardEmbed] @@ -103,7 +104,7 @@ image::./images/embed-lb.png[Liveboard embed] [#common-customizations] == Common customization options -The *xref:LiveboardViewConfig.adoc[LiveboardViewConfig]* object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide header, and more. +The *xref:LiveboardViewConfig.adoc[LiveboardViewConfig]* object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide the header, and more. === Show/hide large UI elements Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderSticky`, `showLiveboardTitle`, and `showLiveboardDescription` control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether `true` enables or disables the particular feature. @@ -159,7 +160,7 @@ The `activeTabId` property is available only in the `LiveboardEmbed` package and === Reduce visible tabs and visualizations `visibleVizs` and `visibleTabs` allow you to limit the experience for certain users on a Liveboard with many more elements. -For example, a template Liveboard with many different KPIs could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization GUIDs as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). +For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). [#noteTiles] === Add Note tiles @@ -170,57 +171,70 @@ You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liv * If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. === Redefine Liveboard breakpoint widths -When enabled, the `enable2ColumnLayout` allows customizing the Liveboard breakpoint width for embedded users. +The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards. -These breakpoint widths are customisable for the embedded customers. Contact ThoughtSpot support for assistance with customisation. - +These breakpoint widths are customizable for the embedded customers. Contact ThoughtSpot support for assistance with customization. -//// -[#lbv2] -== Liveboard experience -Starting from 10.1.0.cl, the link:https://docs.thoughtspot.com/cloud/latest/deprecation#_removed_in_10_1_0_cl[classic experience for liveboards has been deprecated]. +[#liveboard-data-cache] +=== Liveboard browser cache and refresh +ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. -The new Liveboard experience provides an improved interface with several new features and enhancements. The following figure shows the menu actions available on a Liveboard page in the new experience: - -[.bordered] -[.widthAuto] -image:./images/liveboard-exp.png[Liveboard experience comparison] +[NOTE] +==== +Liveboard browser cache and refresh is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot support. +==== +To enable Liveboard data caching, set `enableLiveboardDataCache` to `true`. -=== Features in New Experience mode +[source,javascript] +---- +const liveboardEmbed = new LiveboardEmbed('#embed-container', { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '', // + enableLiveboardDataCache: true, // +}); +---- -* Liveboard edit + -To edit a Liveboard in the new experience mode, click the *Edit* button on the Liveboard page. For example, to delete a visualization on a Liveboard, the user must click *Edit*, and then navigate to the *Delete* option on a visualization. +When data caching is enabled, the refresh icon appears in the Liveboard header. Users can click this button to clear the browser cache and fetch fresh data. -* Filter application in the new experience mode + -To apply filters, the application users must switch to the edit mode. Only users with edit access to the Liveboard can apply filters. When a user creates a copy of a Liveboard, the filters applied on its visualizations are also copied. For more information about Liveboard filters, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filter configuration options, window=_blank]. -* Actions + -The following actions are deprecated in the new experience mode: -** The *Copy embed link* and *Copy link* menu actions in the More image:./images/icon-more-10px.png[the more options menu] menu of a Liveboard -** The edit title icon on visualization tiles -** The *Share* button on visualizations +[.bordered] +[.widthAuto] +-- +image::./images/liveboard-refresh.png[Liveboard refresh] +-- +The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow. -=== Liveboard tabs +[width="100%",cols="2,1,4"] +|==== +|API | Description -Liveboard tabs allow you to logically group visualization into specific categories and allow users to access them easily. +|`Action.RefreshLiveboardBrowserCache` +|xref:Action.adoc#_refreshliveboardbrowsercache[Action] +|Action ID to show, hide, or disable the *Refresh* button in the Liveboard header. -To create, edit, or move visualizations to a tab, you require edit access to a Liveboard. +|`EmbedEvent.RefreshLiveboardBrowserCache` +|xref:EmbedEvent.adoc#_refreshliveboardbrowsercache[EmbedEvent] +|Emitted when a user clicks the *Refresh* button in the Liveboard header. -* To add a tab, click *Edit* and then click *Add tab* on the Liveboard page. -* To add a visualization to a tab on a Liveboard, click *Move to tab* from the More image:./images/icon-more-10px.png[the more options menu] menu. -+ -You can also pin a visualization to a Liveboard tab using the **Pin** action on the Answer page. -//// +|`HostEvent.RefreshLiveboardBrowserCache` +|xref:HostEvent.adoc#_refreshliveboardbrowsercache[HostEvent] +|Triggers a browser cache refresh programmatically for all visualization containers on the embedded Liveboard. +|==== === Customize filters - To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. -WARNING: The SDK processes at most 49 entries per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. See -xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. +[IMPORTANT] +==== +The SDK processes up to 49 runtime filters per embed. Any objects at index 50 or +beyond are silently dropped without an error or warning. For more information, see +xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. +==== ==== Customizing filter visibility To hide filters in an embedded Liveboard, you can use the following options: @@ -255,18 +269,17 @@ Use the following host events in the Visual Embed SDK to update filters: For more information and examples, see xref:filters_overview.adoc[Filter types and application layers]. -== Liveboard download options +=== Liveboard download options Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view. - [NOTE] ==== -Starting with the 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. +Starting with ThoughtSpot Cloud version 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. ==== -=== XLSX and CSV in Liveboard scheduled exports -To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` to `true`. +==== XLSX and CSV in Liveboard scheduled exports +To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` is set to `true`. [source,javascript] ---- @@ -276,10 +289,10 @@ const embed = new LiveboardEmbed('#tsEmbed', { }); ---- -=== Download actions and behavior +==== Download actions and behavior [width=100%, cols="2,2,4"] -[options='header'] +[options="header"] |===== | Download actions | SDK parameter @@ -307,7 +320,7 @@ a|`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV a| Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog. |===== -=== Example +==== Example The following example enables the **PDF (Continuous)**, **XLSX**, and **CSV** options in the Liveboard **Download** modal. @@ -349,127 +362,33 @@ const embed = new LiveboardEmbed('#tsEmbed', { Action.DownloadLiveboard,// Disables the Download parent action in the more options menu Action.DownloadLiveboardAsContinuousPDF, // Disables the Continuous PDF download option in the Download modal Action.DownloadLiveboardAsCsv, // Disables the CSV download option in the Download modal - Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal) + Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal ], }); ---- -=== HostEvent workflow for the download actions +==== HostEvent workflow for the download actions Use the HostEvent IDs to trigger download actions on an embedded Liveboard. * `HostEvent.DownloadLiveboardAsContinuousPDF` + To open the **Download** modal with the continuous PDF download option selected. * `HostEvent.DownloadAsPdf` + -To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of visualization in the `vizId` key. +To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of the visualization in the `vizId` key. * `HostEvent.DownloadAsXlsx` + To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view. * `HostEvent.DownloadAsCsv` + To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view. +=== Liveboard grouping and styling +[earlyAccess eaBackground]#Early Access# -//// -==== Customize filter visibility in Liveboard tabs -Filters and parameters that are not relevant to the visualizations in a tab can be hidden by default on an embedded Liveboard. This feature is disabled by default on ThoughtSpot embedded instances. To enable this feature, set `hideIrrelevantChipsInLiveboardTabs` to `true`. - -[NOTE] -==== -This feature is supported only if compact header is enabled on your Liveboard. To enable compact header, use the `isLiveboardCompactHeaderEnabled` attribute. -==== - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '<%=liveboardGUID%>', // Replace it with your Liveboard ID - isLiveboardCompactHeaderEnabled: true, - hideIrrelevantChipsInLiveboardTabs: true, - // ... other embed view configuration settings -}); ----- - -//// - - -//// - -| `EXACT_DATE_TIME` |Specify the date and time in epoch or the regular date and time format. For example, 2023/07/31 22:50:05. a|[source,JavaScript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filter: { - column: "date", - oper: "EQ", - values: ["2023/07/31 22:50:05"], - type: "EXACT_DATE_TIME" - } - }); ----- - -|`EXACT_TIME` |Specify the time value in epoch or `hh:mm:ss` format. -a|[source,JavaScript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filter: { - column: "date", - oper: "EQ", - values: ["22:50:05"], - type: "EXACT_TIME" - } - }); ----- - -|`MONTH_ONLY` |Specify the month. For example, July. -a|[source,JavaScript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filter: { - column: "date", - oper: "EQ", - values: ["July"], - type: "MONTH_ONLY" - } - }); ----- -|`LAST_PERIOD` |Specify the time period. For example, Last week. You must also include the `datePeriod` attribute based on the time period specified in the filter object. Valid values for `datePeriod` are `DAY`, WEEK`, `MONTH`, QUARTER, and YEAR. - -a|[source,JavaScript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filter: { - column: "date", - oper: "EQ", - values: [""], - datePeriod: "DAY", - type: "LAST_PERIOD" - } - }); ----- - -|`NEXT_PERIOD` |Specify the time period. For example, next week. You must also include the `datePeriod` attribute based on the time period specified in the filter object. Valid values for `datePeriod` are `DAY`, WEEK`, `MONTH`, QUARTER, and YEAR. -a|[source,JavaScript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filter: { - column: "date", - oper: "EQ", - values: [""], - datePeriod: "DAY", - type: "LAST_PERIOD" - } - }); - -//// - -=== Liveboard grouping and styling [earlyAccess eaBackground]#Early Access# You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. -* All tiles on the Liveboard will now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. -* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of properly sizing Note tiles to avoid content being visually cut off. -* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard will fail to load and throw an error. +* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. +* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. +* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. + [.bordered] [.widthAuto] @@ -477,17 +396,11 @@ Note the following changes that occur in the Liveboard UI and layout when this f image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] -- + -To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard will not render correctly. +To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. -To understand about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. - -=== Liveboard comments - -ThoughtSpot does not support adding comments, replying, or subscribing to comment threads on embedded Liveboards. - -//if the Liveboard is embedded in another application, the comment icon will not be visible to the embedded application users regardless of their access privileges. +For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. == Additional resources * For information about runtime overrides, see xref:runtime-filters.adoc[Runtime filters] and xref:runtime-parameters.adoc[Runtime Parameter overrides]. diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index e5c42876d..eaaf2b1a0 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -163,7 +163,7 @@ spotterEmbed.render(); * Verify whether the customization settings are applied. [#configControls] -== Customizing embedded Spotter interface +== Customizing the embedded Spotter interface When you embed Spotter, you'll notice that the embedded component loads an initial page with a prompt interface. The look and feel of this page vary depending on the Spotter version used for embedding. === Spotter Classic and Spotter 2 experiences @@ -217,7 +217,7 @@ image::./images/spotter3-new-interface.png[Spotter 3 new interface] You can also include the *Chat history* panel to allow your users to access the chat history from their previous sessions. -To enable chat history features, set the `enablePastConversationsSidebar` attributes to `true`. Additionally, you can also customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig.adoc#_spottersidebarconfig[spotterSidebarConfig] object. +To enable chat history features, set the `enablePastConversationsSidebar` attribute to `true`. Additionally, you can customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig.adoc#_spottersidebarconfig[spotterSidebarConfig] object. [source,JavaScript] ---- @@ -282,7 +282,7 @@ If the new prompt interface in Spotter 3 is enabled, the Spotter page displays t The MCP connector module and the '+' icon are displayed by default if the new prompt interface is enabled in your embed. However, we do not recommend using this feature in your production environments. ==== -Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use the CSS selectors to hide these elements: +Currently, the Visual Embed SDK does not provide any attributes or action IDs to hide these elements. As a workaround, you can use CSS selectors to hide these elements: [source,JavaScript] ---- @@ -385,7 +385,7 @@ The following figures show the customized Spotter icon: [.bordered] image::./images/spotter-icon-customization.png[Spotter icon customization] -=== Hiding the Spotter icon and ThoughtSpot branding chat interface +=== Hiding the Spotter icon and ThoughtSpot branding from the chat interface To hide the Spotter logo and branding in the chat interface, use the following parameters in the `SpotterChatViewConfig` interface: * `hideToolResponseCardBranding` + @@ -412,38 +412,23 @@ spotterChatConfig: { } ---- +[#fileUpload] +=== Allowing file uploads in Spotter chats +To enable file uploads in the Spotter chat panel: + +. Ensure that `spotterFileUploadEnabled` is set to `true` in the `spotterChatConfig` object. This setting enables ** + Add files** option in the Spotter chat panel. +. Optionally, you can restrict the types of files users can upload by specifying the file types in the `SpotterFileUploadFileTypes` array. If no file format is specified, all supported file types are allowed for uploads. -//// [source,JavaScript] ---- -init({ - //... embed configuration attributes - customizations: { - style: { - customCSS: { - rules_UNSTABLE: { - // Hide the Spotter icon in the tool call card under reasoning - "svg.chat-module__spotterIcon.icon-module__iconStyle.icon-module__xxl.icon-module__white": { - "display": "none !important" - }, - // Control the visibility for the ThoughtSpot text in the tool call card under reasoning - // Hide the element completely if MCP connectors are enabled, since the text-indent works for ThoughtSpot text only - ".collapsible-item-response-module__title": { - "text-indent": "-89px", - "overflow": "hidden", - "margin-left": "-24px" - }, - // Hide the ThoughtSpot (or Connector) icon in the tool call card under reasoning - ".collapsible-item-response-module__customIconWrapper": { - "display": "none" - }, - }, - }, +const embed = spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + //... + spotterChatConfig: { + spotterFileUploadEnabled: true, + spotterFileUploadFileTypes: { types: ['pdf', 'png', 'xlsx'] }, - } }); ---- -//// [#spotterMenuActions] === Customizing menu actions and elements @@ -473,11 +458,16 @@ For a comprehensive list of supported actions, see xref:Action.adoc[Spotter menu ---- import { SpotterEmbed, + SpotterEmbedViewConfig, + SpotterChatViewConfig, AuthType, init, + prefetch, EmbedEvent, HostEvent -} from '@thoughtspot/visual-embed-sdk'; +} +from '@thoughtspot/visual-embed-sdk'; + // Initialize the ThoughtSpot Visual Embed SDK with your ThoughtSpot URL and authentication type. init({ thoughtSpotHost: 'https://your-thoughtspot-host', // Replace with your ThoughtSpot application URL diff --git a/modules/ROOT/pages/embed-spotterViz.adoc b/modules/ROOT/pages/embed-spotterViz.adoc new file mode 100644 index 000000000..9c74008b6 --- /dev/null +++ b/modules/ROOT/pages/embed-spotterViz.adoc @@ -0,0 +1,488 @@ += SpotterViz AI agent in Liveboards +:toc: true +:toclevels: 2 + +:page-title: SpotterViz agent in Liveboards +:page-pageid: spotterViz-agent +:page-description: Customize the SpotterViz panel in embedded Liveboards using the Visual Embed SDK. + +[earlyAccess eaBackground]#Early Access# + +The SpotterViz panel is supported in Liveboards embedded using `LiveboardEmbed` or `AppEmbed` components. ThoughtSpot link:https://docs.thoughtspot.com/cloud/26.6.0.cl/spotter-viz[SpotterViz, window=_blank] is the AI-powered analysis panel that appears when a user opens the Liveboard in edit mode. It provides Liveboard users with an in-context AI assistant and a prompt interface to ask questions on Liveboard data and receive automatically generated visualizations and insights in response. + +[NOTE] +==== +* SpotterViz is an early access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +* The SpotterViz panel in Liveboard embedding is supported in Visual Embed SDK v1.50.0 and ThoughtSpot instances with 26.7.0.cl or later versions only. +==== + +== Before you begin +* Ensure that the Spotter feature is enabled on your ThoughtSpot instance. +* Ensure that the SpotterViz feature is enabled on your instance. Contact your ThoughtSpot administrator if SpotterViz is not enabled. + +== Accessing SpotterViz panel +If the SpotterViz feature is enabled on the instance, the panel is displayed by default when a Liveboard is opened in the edit mode in the embedded view. + +[.bordered] +[.widthAuto] +-- +image::./images/spotterviz-embed-mode.png[SpotterViz in embed view] +-- + +To disable or hide SpotterViz in embedded view, use the `Action.SpotterViz` action ID in the `disabledActions` or `hiddenActions` array. + +== Customizing the SpotterViz panel contents +For SpotterViz panel customization, pass the `spotterViz` configuration object with the following properties as needed: + +Brand name:: +To replace the default **SpotterViz** label with your product or assistant name, specify the brand name string in `brandName`. + +Greeting headline:: Customize the greeting prefix displayed before the brand name using `brandHeadline`. For example, setting `brandHeadline: "Hi there! I'm"` combined with `brandName: "Dashboard Builder"` renders as "Hi there! I'm Dashboard Builder". + +Description:: Use `description` to include your custom description text below the greeting. This helps users understand what the AI assistant can do. + +Input placeholder:: Use `inputChatPlaceholder` to customize the placeholder text shown in the chat input box when it is empty. By default, this text is displayed as "Let me help you build this Liveboard". + +Starter prompts:: +SpotterViz displays the question suggestions in the panel to help users begin an AI-assisted analysis. Each prompt has a short display label (`displayText`) and a full prompt string (`fullPrompt`) sent to Spotter when clicked. + +* To hide starter prompts, set `hideStarterPrompts` to `true`. +* To customize the starter prompt text, use `customStarterPrompts`. The `customStarterPrompts` includes the following attributes: +** `id`. __String__. Unique identifier for the prompt within the `customStarterPrompts` array. We recommend setting the ID to values such as `'1'`, `'2'`, and `'3'`. +** `displayText`. __String__. Short label shown to the user as a clickable suggestion chip. +** `fullPrompt`. __String__. Full prompt text sent to Spotter when the user clicks the suggestion. ++ +For example, you can set the display text as `displayText: 'Regional breakdown'` and `fullPrompt` to `Show me revenue broken down by region`. + +Button and other interface elements:: +The SpotterViz panel displays the restore button on checkpoint cards and thumbs-up and thumbs-down feedback buttons by default. To disable or hide these elements, use the following action IDs in the SDK: +* `Action.SpotterVizCheckpointRestore` +* `Action.SpotterVizFeedback` + +=== SpotterViz in Liveboard embedding +[source,javascript] +---- +import { + LiveboardEmbed, + AuthType, + init, + SpotterVizConfig +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://', //Replace with your ThoughtSpot instance URL + authType: AuthType.None, +}); + +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '', // Replace with your Liveboard ID + spotterViz: { + brandName: 'Dashboard Builder', + brandHeadline: "Hi there! I'm", + description: 'Ask me anything about your data.', + inputChatPlaceholder: 'Ask a question...', + hideStarterPrompts: false, + customStarterPrompts: [ + { + id: '1', + displayText: 'Top products', + fullPrompt: 'What are the top 10 products by revenue this quarter?', + }, + { + id: '2', + displayText: 'Regional breakdown', + fullPrompt: 'Show me revenue broken down by region.', + }, + ], + }, + hideActions: [Action.SpotterVizCheckpointRestore], +}); +embed.render(); +---- + +=== SpotterViz in full application embedding + +[source,javascript] +---- +import { + AppEmbed, + AuthType, + init, + SpotterVizConfig +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/ts-token').then(r => r.json()).then(d => d.token), +}); + +const embed = new AppEmbed('#embed-container', { + pageId: Page.Liveboards, + spotterViz: { + brandName: 'Dashboard Builder', + description: 'Explore your data with AI.', + hideStarterPrompts: true, + }, + hideActions: [Action.SpotterVizCheckpointRestore] +}); + +embed.render(); +---- + +== Customizing the style and appearance +You can customize the visual appearance of the SpotterViz panel using the CSS customization framework in the SDK. Use any of the following CSS variables in the `customizations` object of the `init()` call to customize the panel style and appearance. + +[IMPORTANT] +==== +CSS variable customizations applied in `init()` are scoped to the embedded ThoughtSpot application. Changes to SpotterViz variables affect only the SpotterViz panel and Liveboard edit toolbar. However, changes to other variables, such as `--ts-var-root-background`, affect the entire embedded application. Therefore, you must test the styling changes against all embedded components to avoid unintended visual side effects. +==== + +The following tables list all CSS variables available for customizing the SpotterViz panel. Variables are grouped by the UI area they control. + +=== Panel and layout + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-panel-background` +| Background color of the SpotterViz panel. + +| `--ts-var-spotterviz-border-color` +| Shared border color used throughout SpotterViz. Controls the chat input box +border, user message border, header underline, left panel border, and +thinking step connector lines and dots. + +| `--ts-var-spotterviz-footer-text-color` +| Text color of the SpotterViz panel footer. +|=== + +=== Text colors + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-text-primary` +| Primary text color in the SpotterViz panel. Applied to the SpotterViz panel header, close icon, user message text, agent response text, thinking step headers, checkpoint "Liveboard updated" text, brand name and description, text in the empty state, starter prompt text, and upvote/downvote icons. + +| `--ts-var-spotterviz-text-secondary` +| Secondary text color in the SpotterViz panel. Applied to checkpoint version labels ("version N"), tool call display, and the copy action color on input/JSON/output panels. + +| `--ts-var-spotterviz-emptystate-spotterviz-color` +| Text color of the SpotterViz brand label shown in the empty state, displayed below the SpotterViz icon. +|=== + +=== Chat input + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-input-background` +| Background color of the chat input field. + +| `--ts-var-spotterviz-input-placeholder-color` +| Placeholder text color in the chat input field. + +| `--ts-var-spotterviz-input-cta-color` +| Color of the submit (CTA) button in the chat input field. + +| `--ts-var-spotterviz-input-cta-hover-color` +| Hover color of the submit (CTA) button in the chat input field. + +| `--ts-var-spotterviz-reference-icon-hover-background` +| Background color of the reference-mode toggle button in the chat input when it is in the unselected state and the user hovers over it. + +| `--ts-var-spotterviz-reference-icon-selected-color` +| Icon color for the reference-mode selected state. Applies to the toggle button when active and to the icon badge on referenced entity chips in the chat input. + +| `--ts-var-spotterviz-reference-icon-selected-background` +| Background color for the reference-mode selected state. Applies to the reference-mode toggle button when active and to the icon badge on referenced entity chips in the chat input. +|=== + +=== Starter prompts + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-prompt-card-background` +| Background color of the starter prompt suggestion cards. + +| `--ts-var-spotterviz-prompt-card-hover-background` +| Background color of starter prompt suggestion cards on hover. + +|=== + +=== User messages +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-message-background` +| Background color of the user's chat message bubbles. + +| `--ts-var-spotterviz-usermessage-icon-hover` +| Hover color of the expand button on user chat message bubbles. + +| `--ts-var-spotterviz-usermessage-icon-background` +| Background color of the expand button on user chat message bubbles. + +|=== + +=== Thinking and progress states + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-thinking-inprogress-header-color` +| Color of the thinking step header text while the agent is still working. + +| `--ts-var-spotterviz-thinking-completed-header-color` +| Color of the thinking step header text once the step is complete. Also +applied to the arrow icon on the "work done" state. + +| `--ts-var-spotterviz-thinking-work-done-icon-color` +| Color of the final completion indicator icon (the green circle) shown +when all agent work is done. + +| `--ts-var-spotterviz-thinking-cta-hover-background` +| Hover background color for the working/work done CTA element. +|=== + +=== Tool calls + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-spotterviz-tool-call-background` +| Background color of tool call panels. + +| `--ts-var-spotterviz-tool-title-color` +| Color of tool titles and icons inside tool call panels. + +| `--ts-var-spotterviz-tool-border-color` +| Border color of tool call panels. + +| `--ts-var-spotterviz-tool-json-input-background` +| Background color of the JSON input/output panel inside a tool call. + +| `--ts-var-spotterviz-tool-json-input-color` +| Text color of the JSON input/output panel inside a tool call. + +| `--ts-var-spotterviz-tool-feedback-button-background` +| Background color of the upvote/downvote feedback buttons. + +| `--ts-var-spotterviz-tool-feedback-button-hover` +| Hover background color of the upvote/downvote feedback buttons. + +|=== + +=== Checkpoints + +[cols="3,3", options="header"] +|=== +| CSS variable | Description +| `--ts-var-spotterviz-last-checkpoint-background` +| Background color of the last checkpoint summary section. +| `--ts-var-spotterviz-last-checkpoint-border` +| Border color of the last checkpoint summary section. +|=== + +=== Liveboard edit toolbar + +The Liveboard edit toolbar hosts the SpotterViz trigger button and other Liveboard editing controls. You can customize it independently from the SpotterViz panel itself. + +[cols="3,3", options="header"] +|=== +| CSS variable | Description + +| `--ts-var-liveboard-edit-toolbar-border` +| Border color of the Liveboard edit header toolbar. + +| `--ts-var-liveboard-edit-toolbar-selected-background` +| Background color of the selected (active) section in the Liveboard edit header toolbar. + +| `--ts-var-liveboard-edit-toolbar-selected-text-color` +| Text color of the selected section in the Liveboard edit header toolbar. Also applied to the Add button and toolbar icons in the selected state. + +| `--ts-var-liveboard-edit-toolbar-text` +| Text color of unselected items in the Liveboard edit header toolbar. Also applied to the Add button and toolbar icons in the unselected state. + +| `--ts-var-liveboard-edit-toolbar-hover-background` +| Hover background color of unselected items in the Liveboard edit header +toolbar. Also applied to the Add button and toolbar icons on hover. + +| `--ts-var-liveboard-edit-toolbar-hover-text-color` +| Hover text color of unselected items in the Liveboard edit header toolbar. + +|=== + +=== Apply CSS variable customizations + +Pass CSS variables using the `customCSSVariables` map inside the +`customizations.style` object of the `init()` call. + +[source,javascript] +---- +import { + LiveboardEmbed, + AuthType, + init, +} from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://.thoughtspot.cloud', + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: () => fetch('/api/ts-token').then(r => r.json()).then(d => d.token), + customizations: { + style: { + customCSSVariables: { + // Panel and layout + '--ts-var-spotterviz-panel-background': '#1a1a2e', + '--ts-var-spotterviz-border-color': '#3a3a5c', + '--ts-var-spotterviz-footer-text-color': '#a0a0c0', + + // Text colors + '--ts-var-spotterviz-text-primary': '#ffffff', + '--ts-var-spotterviz-text-secondary': '#a0a0c0', + '--ts-var-spotterviz-emptystate-spotterviz-color': '#8080b0', + + // Chat input + '--ts-var-spotterviz-input-background': '#16213e', + '--ts-var-spotterviz-input-placeholder-color': '#606080', + '--ts-var-spotterviz-input-cta-color': '#6c63ff', + '--ts-var-spotterviz-input-cta-hover-color': '#8a84ff', + + // Starter prompts + '--ts-var-spotterviz-prompt-card-background': '#0f3460', + '--ts-var-spotterviz-prompt-card-hover-background': '#1a4a7a', + + // User messages + '--ts-var-spotterviz-message-background': '#0f3460', + + // Thinking / progress states + '--ts-var-spotterviz-thinking-inprogress-header-color': '#a0a0ff', + '--ts-var-spotterviz-thinking-completed-header-color': '#4caf50', + '--ts-var-spotterviz-thinking-work-done-icon-color': '#4caf50', + '--ts-var-spotterviz-thinking-cta-hover-background': '#2a2a4e', + + // Tool calls + '--ts-var-spotterviz-tool-call-background': '#12122a', + '--ts-var-spotterviz-tool-title-color': '#c0c0ff', + '--ts-var-spotterviz-tool-border-color': '#3a3a5c', + '--ts-var-spotterviz-tool-json-input-background': '#0d0d1a', + '--ts-var-spotterviz-tool-json-input-color': '#c0ffc0', + '--ts-var-spotterviz-tool-feedback-button-background': '#2a2a4e', + '--ts-var-spotterviz-tool-feedback-button-hover': '#3a3a6e', + + // Checkpoints + '--ts-var-spotterviz-last-checkpoint-background': '#1a2a3e', + '--ts-var-spotterviz-last-checkpoint-border': '#3a5a7c', + + // Liveboard edit toolbar + '--ts-var-liveboard-edit-toolbar-border': '#3a3a5c', + '--ts-var-liveboard-edit-toolbar-selected-background': '#6c63ff', + '--ts-var-liveboard-edit-toolbar-selected-text-color': '#ffffff', + '--ts-var-liveboard-edit-toolbar-text': '#a0a0c0', + '--ts-var-liveboard-edit-toolbar-hover-background': '#2a2a4e', + '--ts-var-liveboard-edit-toolbar-hover-text-color': '#ffffff', + }, + }, + }, +}); +---- + +=== SpotterViz button customization +The SpotterViz trigger button renders in the Liveboard edit toolbar. You can customize it in two ways: + +Button icon:: +The SpotterViz button uses the `rd-icon-spotter-viz` icon from the icon sprite. To replace it with a custom icon, set the `iconSpriteUrl` property in your `customizations` object pointing to a sprite that includes the `rd-icon-spotter-viz` icon ID. +For more information, see xref:customize-icons.adoc[Customize icons]. + +Button text:: +The button label follows the `brandName` value you set in the `spotterViz` configuration object. Setting `brandName` in your embed configuration automatically updates the button text to match, keeping your custom brand name consistent across the panel and the toolbar button. + +Button colors:: +Use the `--ts-var-liveboard-edit-toolbar-*` variables described in the <<_liveboard_edit_toolbar,Liveboard edit toolbar>> table above to control the button's background, text, and hover colors in both the selected and unselected states. + +== Customizing app interactions +The following embed events are emitted by the SpotterViz panel. + +* `EmbedEvent.SpotterVizCheckpointCreated` + +Emitted when a checkpoint is created in the SpotterViz panel. +* `EmbedEvent.SpotterVizCheckpointRestored` + +Emitted when a checkpoint is restored in the SpotterViz panel. +* `EmbedEvent.SpotterVizClosed` + +Emitted when the SpotterViz panel is closed. +* `EmbedEvent.SpotterVizError` + +Emitted when an error occurs in the SpotterViz panel. +* `EmbedEvent.SpotterVizInit` + +Emitted when the SpotterViz panel mounts in embed mode. +* `EmbedEvent.SpotterVizQueryTriggered` + +Emitted when the user submits a prompt in the SpotterViz panel. +* `EmbedEvent.SpotterVizResponseComplete` + +Emitted when the SpotterViz response ends. + +[source,javascript] +---- +liveboardEmbed.on(EmbedEvent.SpotterVizInit, (payload) => { + console.log('SpotterViz initialized', payload); + // payload: { liveboardId: string } +}); + +liveboardEmbed.on(EmbedEvent.SpotterVizError, (payload) => { + console.log('SpotterViz error', payload); +}); + +liveboardEmbed.on(EmbedEvent.SpotterVizQueryTriggered, (payload) => { + console.log('SpotterViz query triggered', payload); + // payload: { query: string, sessionId: string } +}); + +liveboardEmbed.on(EmbedEvent.SpotterVizResponseComplete, (payload) => { + console.log('SpotterViz response complete', payload); + // payload: { sessionId: string, messageId: string } +}); +---- + +The following host events programmatically trigger workflows in embedded view: + +* `HostEvent.InitSpotterVizConversation` + +Initializes a new SpotterViz conversation. +* `HostEvent.SpotterVizSendUserMessage` + +Sends a prompt to the SpotterViz panel. +* `HostEvent.OpenSpotterVizPanel` + +Opens the SpotterViz panel. +* `HostEvent.CloseSpotterVizPanel` + +Closes the SpotterViz panel. + +[source,javascript] +---- +liveboardEmbed.trigger(HostEvent.InitSpotterVizConversation); +liveboardEmbed.trigger(HostEvent.SpotterVizSendUserMessage, { + query: 'Show me revenue by region', +}); +---- + +//// +[#runtime-filters] +== Runtime filters and insight tiles +Runtime filters and parameters passed to `LiveboardEmbed` are in SpotterViz-generated insight tiles. When a runtime filter is applied, Spotter automatically regenerates the tile's insights using the filtered data context. + +No additional configuration is required. Runtime filters specified via `runtimeFilters` in `LiveboardViewConfig` are automatically applied to all Insight Tiles on the same Liveboard. +//// + +== Additional resources + +See the following documentation for additional information about embedding Liveboards and customizing Liveboard experience: + +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:full-embed.adoc[Embed full ThoughtSpot experience] +* xref:embed-events.adoc[Embed events reference] +* xref:events-hostEvents.adoc[Host events reference] +* xref:SpotterVizConfig.adoc[SpotterVizConfig interface] diff --git a/modules/ROOT/pages/faqs.adoc b/modules/ROOT/pages/faqs.adoc index cc93a5b21..b5943d7ce 100644 --- a/modules/ROOT/pages/faqs.adoc +++ b/modules/ROOT/pages/faqs.adoc @@ -8,10 +8,9 @@ This article includes answers to some of the most commonly asked questions about embedding ThoughtSpot in an app. -For more FAQS and community help with deployment-related issues, visit the link:https://community.thoughtspot.com/customers/s/topic/0TO3n000000erVyGAI/developers?tabset-80a3b=2[ThoughtSpot Community site, window=_blank]. +For more FAQs and community help with deployment-related issues, visit the link:https://community.thoughtspot.com/customers/s/topic/0TO3n000000erVyGAI/developers?tabset-80a3b=2[ThoughtSpot Community site, window=_blank]. == ThoughtSpot application - [#tsHostName] .What is my ThoughtSpot instance? @@ -20,11 +19,10 @@ For more FAQS and community help with deployment-related issues, visit the link: A ThoughtSpot instance is allocated to customers upon registration and license purchase. Users with a valid license can use their ThoughtSpot application URL to access their instance, whereas evaluating users can use the free-trial instance to try out ThoughtSpot features. For example, `\https://Xyz-company.thoughtspot.cloud/`, `my1.thoughtspot.cloud` (free-trial instance). You can find your instance URL in account activation emails sent to your registered email address. ==== - -.What is ThoughtSpot Host? +.What is a ThoughtSpot Host? [%collapsible] ==== -Your ThoughtSpot application instance URL is also referred to as `ThoughtSpot Host`, `thoughtspotHost`, `tsURL` `TS_HOST`. The instance URL is required to initialize your embedded application and sign in to ThoughtSpot extensions, such as the Vercel integration, business app integration, and ThoughtSpot Google plugins. +Your ThoughtSpot application instance URL is also referred to as `ThoughtSpot Host`, `thoughtspotHost`, `tsURL`, `TS_HOST`. The instance URL is required to initialize your embedded application and sign in to ThoughtSpot extensions, such as the Vercel integration, business app integration, and ThoughtSpot Google plugins. ==== [#lbDef] @@ -43,7 +41,6 @@ image::./images/lb-image.png[Liveboard] ==== A data source is a data object, such as a Model, Table, or View, from which users can search data and create Answers and visualizations. ==== - == APIs and SDK @@ -51,24 +48,31 @@ A data source is a data object, such as a Model, Table, or View, from which user [%collapsible] ==== -You can embed any of the following components, or the entire ThoughtSpot experience: + +You can embed any of the following components, or the entire ThoughtSpot experience: * Search page * Liveboard * Individual visualizations from a Liveboard +* Spotter (AI-powered natural language search and analytics) * Specific pages of the application or the full application + +ThoughtSpot provides the following embedding options: + +* xref:onboarding-guide.adoc[Visual Embed SDK] for JavaScript and TypeScript web applications +* xref:embed-ts-react-app.adoc[React client library] for React applications +* xref:mobile-embed.adoc[For embedding ThoughtSpot in mobile apps] ==== .What is Visual Embed SDK? [%collapsible] ==== -The xref:VisualEmbedSdk.adoc[Visual Embed SDK] is a Javascript library using which you can embed ThoughtSpot application and its components in your web app. +The xref:VisualEmbedSdk.adoc[Visual Embed SDK] is a JavaScript library using which you can embed ThoughtSpot application and its components in your web app. ==== -.My app doesn't allow custom Javascript. Can I embed ThoughtSpot in my app? +.My app doesn't allow custom JavaScript. Can I embed ThoughtSpot in my app? [%collapsible] ==== -We recommend using Visual Embed SDK to embed ThoughtSpot in your app. However, if your application doesn't allow custom Javascript, you can embed ThoughtSpot in an iFrame without using the SDK. + +We recommend using Visual Embed SDK to embed ThoughtSpot in your app. However, if your application doesn't allow custom JavaScript, you can embed ThoughtSpot in an iFrame without using the SDK. + To embed ThoughtSpot without using the Visual Embed SDK: + @@ -97,6 +101,42 @@ The Visual Embed SDK not only allows you to embed ThoughtSpot, but also provides Yes. ThoughtSpot provides a client library using which you can embed ThoughtSpot components in a React app. For more information, see xref:embed-ts-react-app.adoc[Embed ThoughtSpot in a React app]. ==== +.What is Spotter? +[%collapsible] +==== +Spotter is ThoughtSpot's AI-powered natural language search and conversational analytics engine. It provides a chat interface for users to ask questions about their data in plain language and receive instant, business-ready insights and visualizations. + +For more information, see link:https://docs.thoughtspot.com/cloud/26.7.0.cl/spotter[Spotter documentation, window=_blank]. +==== + +.Can I embed Spotter in my application? +[%collapsible] +==== +Yes. You can embed the Spotter interface in your application using the `SpotterEmbed` component in the Visual Embed SDK. For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Embed Spotter experience]. +==== + +.Which Spotter version should I embed? +[%collapsible] +==== +The right Spotter version depends on your use case. + +* Spotter 3 (Recommended) + +Use when you want the most advanced AI analytics experience, including automatic data model discovery, deep research mode, chat history, and MCP connector support. Available from ThoughtSpot Cloud 26.2.0.cl and later. + +* Spotter 2 (Spotter Agent) + +Use when you want agentic AI analytics with richer contextual insights but do not require Spotter 3 features. + +* Spotter Classic + +Use when you need only metadata-level insights and do not require agentic workflows. + +Contact your ThoughtSpot administrator to enable the required Spotter version on your instance. For more information, see xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[Spotter in embed mode]. +==== + +.Can I integrate Spotter into a custom chatbot? +[%collapsible] +==== +Yes. You can integrate Spotter in your custom application or chatbot by using the ThoughtSpot Spotter MCP Server. For more information, see xref:mcp-connect-custom-chatbot.adoc[Integrating Spotter MCP Server in a custom application or chatbot]. +==== == ThoughtSpot Embedded @@ -129,7 +169,7 @@ For a complete list of features, see xref:feature-matrix-license.adoc[Feature ma .Do I need a license to embed ThoughtSpot in my app? [%collapsible] ==== -To embed ThoughtSpot, you require ThoughtSpot Embedded license. For more information, see xref:get-started-tse.adoc[Get started with ThoughtSpot Embedded]. +To embed ThoughtSpot, you require a ThoughtSpot Embedded license. For more information, see xref:get-started-tse.adoc[Get started with ThoughtSpot Embedded]. ==== .Can I preview the SDK and APIs? @@ -156,9 +196,9 @@ Starting from 8.4.1-sw release, customers with license to embed ThoughtSpot can .Do I need a ThoughtSpot Embedded license to customize and rebrand my ThoughtSpot instance? [%collapsible] ==== -If you want to rebrand UI elements, customize fonts and color scheme of your charts, you can use the *Style customization* functionality available in the *Develop* or *Admin* tab. This option is available on all instances and doesn't require a ThoughtSpot Embedded license. +If you want to rebrand UI elements, customize the fonts and color scheme of your charts, you can use the *Style customization* functionality available in the *Develop* or *Admin* tab. This option is available on all instances and doesn't require a ThoughtSpot Embedded license. -However, for advanced customization controls, we recommend using ThoughtSpot Embedded features. For more information, contact ThoughtSpot Support. +However, for advanced customization controls, we recommend using ThoughtSpot Embedded features. For more information, contact ThoughtSpot Support. ==== @@ -173,10 +213,29 @@ However, for advanced customization controls, we recommend using ThoughtSpot Emb * xref:configure-oidc.adoc[OpenID connect authentication] ==== +.What is cookieless authentication and when should I use it? +[%collapsible] +==== +Cookieless authentication (`AuthType.TrustedAuthTokenCookieless`) uses a bearer token instead of session cookies to authenticate embedded ThoughtSpot content. Use this method when: + +* Your embedded application is served from a different domain than your ThoughtSpot instance, and the user's browser blocks third-party cookies. +* You require a stateless authentication flow that does not depend on cookie persistence. + +To use cookieless authentication: + +. Enable xref:trusted-authentication.adoc[Trusted authentication] on your ThoughtSpot instance. +. Set `authType` to `AuthType.TrustedAuthTokenCookieless` when initializing the SDK. +. Set `refreshAuthTokenOnNearExpiry: true` to enable proactive token refresh and prevent session interruptions. + +For more information, see xref:embed-authentication.adoc[Authentication]. +==== + .Can I sync users and groups with ThoughtSpot? [%collapsible] ==== -Yes. You can use the xref:user-api.adoc#user-sync[/tspublic/v1/user/sync] to sync users and groups from external systems with ThoughtSpot. To sync users and groups from Active Directory, you may need to use an AD sync script provided by ThoughtSpot. For more information and assistance, please contact ThoughtSpot Support. +Yes. You can use the `/api/rest/2.0/users/import` endpoint to create or update users and groups programmatically. This is the recommended approach for new integrations. For more information, see xref:rest-api-v2-reference.adoc[REST API v2.0 Reference]. + +To sync users and groups from Active Directory, you may need to use an AD sync script provided by ThoughtSpot. For assistance, contact ThoughtSpot Support. ==== .What is the default SSO experience with embedded ThoughtSpot instances? @@ -220,10 +279,48 @@ You can map a user’s groups in the SAML assertion with ThoughtSpot. For more i .Can I restrict my embed application users from accessing the non-embedded ThoughtSpot instance? [%collapsible] ==== -If you have a single ThoughtSpot cluster and you have embedded the full ThoughtSpot application in another app, you may want to prevent external users from accessing your non-embedded ThoughtSpot instance. ThoughtSpot allows you to restrict embed users from accessing your non-embedded ThoughtSpot instance using a TSCLI command. Please contact ThoughtSpot support to enable this flag on your instance. +If you have a single ThoughtSpot cluster and you have embedded the full ThoughtSpot application in another app, you may want to prevent external users from accessing your non-embedded ThoughtSpot instance. ThoughtSpot allows you to restrict embed users from accessing your non-embedded ThoughtSpot instance using a TSCLI command. Contact ThoughtSpot Support to enable this flag on your instance. +==== + +== Orgs and multi-tenancy + +.What are Orgs? +[%collapsible] +==== +Orgs is ThoughtSpot's multi-tenancy feature. It allows you to create isolated tenant containers within a single ThoughtSpot instance, each with its own users, groups, and data objects. Orgs are typically used for: + +* Logical separation of departments within a single organization +* Supporting multiple distinct customer tenants from a single ThoughtSpot deployment + +Each Org functions as an independent environment. Users assigned only to one Org experience ThoughtSpot as if it were a single-tenant deployment. Users with access to multiple Orgs can switch between them using a menu. + +Orgs are enabled by default on new ThoughtSpot Enterprise cloud instances. For more information, see xref:orgs.adoc[Multi-tenancy with Orgs]. +==== + +.Do I need a special license to use Orgs? +[%collapsible] +==== +Yes. The Orgs multi-tenancy feature requires the ThoughtSpot Analytics Enterprise Edition or ThoughtSpot Embedded license. For more information, see link:https://www.thoughtspot.com/pricing[License types and pricing, window=_blank]. +==== + +.How do Orgs work with the Visual Embed SDK? +[%collapsible] +==== +When embedding ThoughtSpot in a multi-tenant deployment using Orgs, you can scope authentication tokens and API requests to a specific Org. Use the `orgId` parameter in your trusted authentication token request to authenticate users into the correct Org context. + +For more information, see xref:orgs.adoc[Multi-tenancy with Orgs] and xref:orgs-api-op.adoc[Org administration via API]. +==== + +.Can I manage Orgs programmatically? +[%collapsible] +==== +Yes. ThoughtSpot REST API v2.0 provides endpoints to create, update, and manage Orgs. You must have cluster administrator privileges to create and manage Orgs. + +For more information, see xref:orgs-api-op.adoc[Org administration via API]. ==== == Customization and rebranding + .Can I change the look and feel of ThoughtSpot? [%collapsible] ==== @@ -240,9 +337,9 @@ No. The Style customization feature is available on ThoughtSpot Cloud and Though [%collapsible] ==== * UI Layout and style customization + -The style customization feature allows rebranding UI elements, logo, fonts, and color scheme of charts and tables. If you want to remove the Powered by ThoughtSpot logo, contact ThoughtSpot support. +The style customization feature allows rebranding UI elements, logo, fonts, and color scheme of charts and tables. If you want to remove the Powered by ThoughtSpot logo, contact ThoughtSpot Support. * Email customization + -If you want to use a xref:custom-domain-configuration.adoc#_email_customization[specific domain name and sender ID in the system-generated email notifications], contact ThoughtSpot support. +If you want to use a xref:custom-domain-configuration.adoc#_email_customization[specific domain name and sender ID in the system-generated email notifications], contact ThoughtSpot Support. * URL with custom domain name + To xref:custom-domain-configuration.adoc[customize the domain name of your ThoughtSpot instance], contact ThoughtSpot Support. ==== @@ -299,14 +396,18 @@ Yes. You can set the custom action availability to one or several groups. Users .Can I trigger custom actions programmatically? [%collapsible] ==== -You can use the xref:pinboarddata.adoc[/tspublic/v1/pinboarddata] API and the xref:search-data-api.adoc#search-data-api-ref[/tspublic/v1/searchdata] to pull data out of ThoughtSpot, read it, and then take action on it conditionally based on the results. For example, you could send a programmatic query to read Sales data of last week and then send an email if they were over or under a certain threshold. +You can use the xref:pinboarddata.adoc[/tspublic/v1/pinboarddata] API and the xref:search-data-api.adoc#search-data-api-ref[/tspublic/v1/searchdata] API to pull data out of ThoughtSpot, read it, and then take action on it conditionally based on the results. For example, you could send a programmatic query to read Sales data from last week and then send an email if they were over or under a certain threshold. ==== .Can I use custom actions to connect to third-party applications? [%collapsible] ==== -The upcoming ThoughtSpot Sync features allow you to connect ThoughtSpot with third-party business applications such as Slack, SalesForce, and Google Sheets. -Custom actions require writing a bit of code, but can be used to send data to applications that do not have a native integration via ThoughtSpot Sync. +Yes. ThoughtSpot custom actions allow you to send data from ThoughtSpot visualizations and Liveboards to third-party applications. + +* *URL actions*: Send data to an external URL endpoint. Useful for connecting to applications that expose a webhook or REST endpoint. +* *Callback actions*: Pass data back to your host application using the Visual Embed SDK event system, where your application code handles the data and routes it to the target system. + +For more information, see xref:custom-actions.adoc[Custom actions]. ==== .Can I pass authentication information with custom action? @@ -327,13 +428,13 @@ The URL-based custom actions allow you to pass query parameters as key-value pai .What is ThoughtSpot REST API? [%collapsible] ==== -The ThoughtSpot REST API allows you to send API requests directly to the ThoughtSpot server from your application client. You can use it to query the data, automate deployments using TML, manage users, groups, sessions, and objects, view logs and so on. +The ThoughtSpot REST API allows you to send API requests directly to the ThoughtSpot server from your application client. You can use it to query the data, automate deployments using TML, manage users, groups, sessions, and objects, view logs and so on. ==== .What’s the difference between the REST API and the Visual Embed SDK? [%collapsible] ==== -The Visual Embed SDK is a Javascript library specifically used for embedding ThoughtSpot web components into your web app, such as Search, Pinboards, and Visualizations. +The Visual Embed SDK is a JavaScript library specifically used for embedding ThoughtSpot web components into your web app, such as Search, Liveboards, and Visualizations. You can use REST APIs along with Visual Embed SDK to programmatically deploy, manage, and control embedded objects. ==== @@ -353,22 +454,52 @@ The REST API v2.0 framework is built upon the existing core API functionality an For more information, see xref:rest-api-v2.adoc[REST API v2.0] and xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison]. ==== -//// -.Can I embed ThoughtSpot components using the REST API? +.What is REST API v2? [%collapsible] ==== -ThoughtSpot REST API framework supports data APIs, using which you can embed an Answer, Liveboard, or a specific visualization from a Liveboard. You can use these APIs with or without the Visual Embed SDK to embed ThoughtSpot content in your app. +The REST API v2.0 is the recommended API framework for API workflows and integration. It includes several structural enhancements with simplified request and response workflows, improved developer experience with an easy-to-use, interactive Playground. -For more information, see the following pages: +For more information, see xref:rest-api-v2.adoc[REST API v2.0]. +==== -* xref:embed-rest-api.adoc[Embed using REST APIs] -* xref:custom-viz-rest-api.adoc[Create a custom visualization using REST APIs] +.How do I authenticate REST API v2.0 requests? +[%collapsible] ==== -//// +REST API v2.0 supports basic and token-based authentication. + +You can obtain a bearer token by sending a `POST` request to one of the following endpoints and pass this token in the `Authorization: Bearer {AUTH_TOKEN}` header in the subsequent API requests: +* `/api/rest/2.0/auth/token/full`: Returns a token that grants full access to ThoughtSpot. +* `/api/rest/2.0/auth/token/object`: Returns a token scoped to a specific metadata object such as a Liveboard or saved Answer. -.Are there any Certificate requirements for REST API calls +For more information, see xref:authentication.adoc[REST API v2.0 authentication]. +==== + +.Where can I try out REST API v2.0 endpoints? +[%collapsible] +==== +Use the *REST API v2.0 Playground* available from *Develop* > *REST API* > *REST Playground v2.0* in your ThoughtSpot instance. The Playground lets you explore endpoints, try out API requests, view request and response workflows, and generate code samples. + +You can also preview the Playground on the link:https://try-everywhere.thoughtspot.cloud/v2/#/everywhere[public ThoughtSpot developer site, window=_blank] without signing in. +==== + +.Should I migrate from REST API v1 to REST API v2? +[%collapsible] +==== +ThoughtSpot strongly recommends using REST API v2.0. REST API v2 provides a robust framework with the following features: + +* Token-based bearer authentication +* Standardized request and response JSON structures +* An interactive Playground with code generation +* Logical endpoint groupings (for example, all metadata operations under `/metadata/`) + +Authentication tokens generated from REST API v1 endpoints can be used to authorize REST API v2.0 requests, which simplifies incremental migration. For a full comparison, see xref:rest-api-v1v2-comparison.adoc[REST API v1 and v2.0 comparison]. +==== + + + +.Are there any certificate requirements for REST API calls? [%collapsible] ==== @@ -411,27 +542,35 @@ You must add the SSL certificates obtained from your ThoughtSpot instance to Tru == Documentation and code samples -.Where can I find more information about Visual Embed SDK? +.Where can I find more information about the Visual Embed SDK? [%collapsible] ==== To learn more about the SDK, see the following resources: + * xref:getting-started.adoc[Embed using Visual Embed SDK] in Developer Documentation * xref:VisualEmbedSdk.adoc[Visual Embed SDK Reference Guide] -* link:https://developers.thoughtspot.com/guides[Quick starts and tutorials, window=_blank] ==== -.Where can I find code samples for Visual Embed SDK? +.Where can I find code samples for the Visual Embed SDK? [%collapsible] ==== Check the following resources for code samples: + -* link:https://developers.thoughtspot.com/codespot[CodeSpot, window=_blank] -* xref:VisualEmbedSdk.adoc[Developer Documentation] -* link:https://github.com/thoughtspot/visual-embed-sdk[Visual Embed SDK GitHub repository, window=_blank] -* link:https://github.com/thoughtspot/ts_everywhere_resources[ThoughtSpot Embedded Resources on GitHub, window=_blank] -* link:https://developers.thoughtspot.com/guides[Visual Embed Tutorials, window=_blank] +* link:https://developers.thoughtspot.com/docs[Developer documentation] +* xref:VisualEmbedSdk.adoc[Visual Embed SDK documentation] * link:{{previewPrefix}}/playground/search[Visual Embed Playground, window=_blank] +* xref:spottercode.adoc[SpotterCode] for code samples and scaffolding boilerplate code for embedding. +* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/spotter/spotter-agent-embed[Developer examples on GitHub, window=_blank] +==== + +.Where can I find resources for embedding Spotter? +[%collapsible] +==== +To learn more about embedding Spotter, refer to the following resources: + +* xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] for an overview of Spotter versions and SDK components +* xref:embed-spotter.adoc[Embed Spotter experience] for information about embedding Spotter experience in your app +* xref:mcp-integration.adoc[ThoughtSpot Spotter MCP Server] for information about integrating Spotter using Spotter MCP server in your application or MCP client. ==== .Where can I find more information about ThoughtSpot REST APIs? diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 44d9e2530..b4e60b77e 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -40,10 +40,14 @@ Includes a left navigation panel that dynamically adjusts its menu based on cont Limited customization controls |Redesigned top navigation bar with an app selector and other icons + Separate left navigation panel for each application context| Sliding left navigation panel with persona-based application icons + A dynamic left navigation menu that adjusts its contents according to the application context. -|**Home page experience**| Static home page with limited customization control | Modular home page with customizable components |Modular home page with customizable components, enhanced styling, and visual elements. +|**Home page experience** | Static home page with limited customization control a| Modular home page with customizable components |Modular home page with customizable components, enhanced styling, and visual elements. -|**Feature availability**| Enabled by default| Disabled by default | Disabled by default +[NOTE] +==== +The SDK also supports a V4 focused home page experience [earlyAccess eaBackground]#Early Access#. For more information, see xref:full-app-customize.adoc#_enable_the_v4_focused_home_page_experience[Enable the V4 focused home page experience]. +==== +|**Feature availability**| Enabled by default| Disabled by default | Disabled by default |===== -- @@ -62,7 +66,6 @@ image::./images/v2-experience.png[V2 UI experience] [.widthAuto] image::./images/v1-experience.png[Classic experience] - == Customize the embedded application UI for your users Before updating the UI experience, review the xref:full-app-customize.adoc#_ui_experience_modes[key features, limitations], and available SDK controls for customizing xref:customize-nav-full-embed.adoc[navigation] and the xref:customize-homepage-full-embed.adoc[home page]. @@ -84,21 +87,22 @@ Before you begin: To enable the V3 experience, you must use the `discoveryExperience` object in the SDK. This object supports the following properties: * `primaryNavbarVersion` + -Enables the V3 experience. The valid value for the V3 experience is `PrimaryNavbarVersion.Sliding`. + -If this attribute is not set, no changes will be applied, and the currently enabled UI experience in your app will be retained. - +Enables the V3 experience. The valid value is `PrimaryNavbarVersion.Sliding`. + * `homePage` + -Enables the modular home page experience. Valid values include: -** `HomePage.ModularWithStylingChanges` (__Recommended__) + +Enables the modular or focused home page experience. Valid values include: +** `HomePage.ModularWithStylingChanges` (__Recommended for V3__) + Enables the V3 modular home page experience. You must include `primaryNavbarVersion` to update the UI experience to the V3 home page. +** `HomePage.Focused` [earlyAccess eaBackground]#Early Access# +Enables the V4 focused home page experience, which consolidates the **Watchlist** and **Recents** sections into a single, focused view. + ** `HomePage.Modular` + -Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming 2026 release. +Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming release. + [IMPORTANT] ==== -* To enable the full V3 experience, both `primaryNavbarVersion` and `homePage` attributes must be set in the SDK. Not setting `primaryNavbarVersion` will result in no changes to the UI experience. +* To enable the full V3 experience, both `primaryNavbarVersion` and `homePage` attributes must be set in the SDK. Not setting `primaryNavbarVersion` will result in no changes to the UI experience. * If you include only the `homePage: HomePage.ModularWithStylingChanges` attribute in `discoveryExperience`, it will be ignored. + -* If you include only the homePage attribute with its value as `HomePage.Modular`, the v2 modular home page experience will be enabled. +* If you include only the homePage attribute with its value as `HomePage.Modular`, the V2 modular home page experience will be enabled. For information about these configuration combinations and their effects, see xref:full-app-customize.adoc#_ui_customization_options_and_resulting_experience[UI customization options and resulting experience]. ==== @@ -154,30 +158,37 @@ const embed = new AppEmbed("#embed", { //... other embed view configuration attributes }); ---- -//// -* `homePage: HomePage.Modular` for the V2 modular home page layout. This option doesn't include the customizable components available in the V3 experience. -+ + +[#_enable_the_v4_focused_home_page_experience] +=== Enable the V4 focused home page experience + +The V4 focused home page experience is available with Visual Embed SDK v1.50.0 and ThoughtSpot Cloud 26.7.0.cl. This experience consolidates the **Watchlist** and **Recents** sections into a unified, focused view designed to surface the most relevant content for users. + +[IMPORTANT] +==== +The focused home page experience is an Early Access feature and is disabled by default. To enable this feature, contact your ThoughtSpot administrator. +==== + +To enable the V4 focused home page, set `homePage` to `HomePage.Focused` in the `discoveryExperience` object: + [source,JavaScript] ---- -// Import required components and enums for V3 experience +// Import required components and enums import { - AppEmbed, // Main class to embed the full ThoughtSpot app + AppEmbed, HomePage, // Enum for home page experience settings PrimaryNavbarVersion // Enum for V3 navigation experience } from '@thoughtspot/visual-embed-sdk'; const embed = new AppEmbed("#embed", { - // Enable V3 navigation and home page experience discoveryExperience: { - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enables V3 navigation - homePage: HomePage.ModularWithStylingChanges, // Enables V2 modular home page + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience + homePage: HomePage.Focused, // Enable V4 focused home page experience }, - // Show navigation panels showPrimaryNavbar: true, //... other embed view configuration attributes }); ---- -//// ==== Post migration checks After you enable the V3 experience: @@ -195,24 +206,7 @@ image::./images/new-nav3.png[New home page] * Verify that all the customization settings are applied correctly. * If you have set up custom routes for navigation within your embedded app, verify navigation workflows and check for breaking changes. - //// -* A sliding left navigation panel with the following components: -** The app selector icons for *Insights*, *Data workspace*, and *Develop* appear in the left navigation panel header. -** The *Liveboards*, *Answers*, *Search Data*, and *Spotter* menu options in the *Insights* section. The *Insights* panel also includes a list of users' favorites. -** The *Home* menu option in the *Insights* section. - -* A top navigation header with the following components: -** A hamburger icon to slide in or close the navigation overlay -** Object search bar -** The alert icon that shows notifications -** Help and user profile icons. The user profile menu includes the *Admin settings* menu. This option is visible only to users with administration privileges. -** Org switcher to switch between Org contexts - -* Home page experience -** Modular home page with specific sections for Search, Watchlist, Favorites, and so on. -//// - === Upgrade from classic (V1) experience to V2 experience Setting `modularHomeExperience` to `true` in the SDK enables the V2 experience. @@ -229,7 +223,7 @@ const embed = new AppEmbed("#embed", { ==== The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features. ==== -//// + The following figure shows the user interface with the V2 experience enabled: [.bordered] @@ -246,12 +240,8 @@ The following table summarizes the resulting UI experience for different configu [width="100%", cols="6,7,6"] [options='header'] |=== -|If `modularHomeExperience` is | And `discoveryExperience` is| UI experience will be - -|`true` / `false` + -Not set / Incorrect a| - - +|`discoveryExperience` setting| `modularHomeExperience` state | Resulting UI experience +a| [source,JavaScript] ---- discoveryExperience: { @@ -261,11 +251,25 @@ discoveryExperience: { homePage: HomePage.ModularWithStylingChanges } ---- +|`true` / `false` + +Not set / Incorrect | V3 navigation and V3 modular home page -|`true` / `false` + -Not set / Incorrect a| +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 experience and navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // V4 home page experience + homePage: HomePage.Focused + } +---- +|`true` / `false` + +Not set / Incorrect +| V3 navigation and V4 home page experience +a| [source,JavaScript] ---- discoveryExperience: { @@ -275,11 +279,12 @@ discoveryExperience: { homePage: HomePage.Modular }, ---- +|`true` / `false` + +Not set / Incorrect | V3 navigation and a modular home page that is similar to the V2 experience -|`true` / `false` + -/ Not set / incorrect a| +a| [source,JavaScript] ---- discoveryExperience: { @@ -287,10 +292,11 @@ discoveryExperience: { primaryNavbarVersion: PrimaryNavbarVersion.Sliding }, ---- +|`true` / `false` + +Not set / Incorrect |V3 navigation and a modular home page that is similar to the V2 experience -|`true` / `false` + -/ Not set / incorrect a| +a| [source,JavaScript] ---- @@ -299,10 +305,11 @@ discoveryExperience: { homePage: HomePage.Modular }, ---- +|`true` / `false` + +Not set / Incorrect | V2 navigation and V2 modular home page - -a|`true` a| +a| [source,JavaScript] ---- @@ -311,9 +318,10 @@ discoveryExperience: { homePage: HomePage.ModularWithStylingChanges }, ---- +a|`true` | V2 navigation and V2 modular home page -a| `false` / Not set / incorrect a| +a| [source,JavaScript] ---- @@ -322,15 +330,30 @@ discoveryExperience: { homePage: HomePage.ModularWithStylingChanges }, ---- +a| `false` / Not set / incorrect |Classic (V1) experience. +a| Not set +a|`true` | V2 navigation and V2 modular home page -a|`true` a| Not set | V2 navigation and V2 modular home page +a| Not set a|`false` / Not set / incorrect | Classic (V1) experience -a|`false` / Not set / incorrect a| Not set | Classic (V1) experience +a| +[source,JavaScript] +---- +discoveryExperience: { + // V3 navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // V4 modular home page + homePage: HomePage.Focused + }, +---- +a|`false` +| V3 navigation and V4 home page experience |=== -- + == Customize navigation experience For information about the navigation elements in each UI experience mode and the related customization settings in the SDK, see xref:customize-nav-full-embed.adoc[Customize navigation experience]. diff --git a/modules/ROOT/pages/full-embed.adoc b/modules/ROOT/pages/full-embed.adoc index 1a6aadcc8..2f79ad030 100644 --- a/modules/ROOT/pages/full-embed.adoc +++ b/modules/ROOT/pages/full-embed.adoc @@ -4,7 +4,7 @@ :page-title: Embed Full Application :page-pageid: full-embed -:page-description: You can embed full ThoughtSpot experience in your application and allow your users to create content for live analytics +:page-description: You can embed the full ThoughtSpot experience in your application and allow your users to create content for live analytics Full app embedding allows you to embed the entire ThoughtSpot application or individual application pages in your app. It provides access to all core ThoughtSpot features, along with additional customization options through the Visual Embed SDK, including custom actions and CSS styling rules. @@ -20,7 +20,7 @@ The layout and feature set of the various pages in full app embedding are relati == Before you embed Before embedding the full ThoughtSpot application: -* Review ThoughtSpot UI, xref:full-app-customize.adoc[different experience modes and customization options] available in the SDK. +* Review the ThoughtSpot UI, xref:full-app-customize.adoc[different experience modes and customization options] available in the SDK. * Determine the xref:customize-nav-full-embed.adoc[navigation elements] and xref:customize-homepage-full-embed.adoc[modules] to enable or customize in the embed view == Import the AppEmbed package @@ -32,6 +32,8 @@ Import the AppEmbed SDK library to your application environment: import { AppEmbed, Page, + HomePage, + PrimaryNavbarVersion, AuthType, init, prefetch, @@ -109,13 +111,13 @@ https://{ThoughtSpot-Host}/?embedApp=true&primaryNavHidden=true&profileAndHelpIn ---- //// -The `AppEmbed` component allows you to embed a specific application page or the entire application experience. If you are embedding full experience, you can xref:set-default-page.adoc[set a specific application page as the default page when the embedded content loads] using the `pageId` or `path` property. +The `AppEmbed` component allows you to embed a specific application page or the entire application experience. If you are embedding the full experience, you can xref:set-default-page.adoc[set a specific application page as the default page when the embedded content loads] using the `pageId` or `path` property. == Customize your embed view (Optional) The `xref:AppViewConfig.adoc[AppViewConfig]` object in the `AppEmbed` component various attributes and properties to xref:css-customization.adoc[the look and feel of the embedded app], xref:embed-actions.adoc[control the visibility of menu actions] and features, and xref:embed-events.adoc[manage interactions between the host and embedded app]. -By default, ThoughtSpot application loads in the classic (V1) experience mode. If the V3 navigation and modular home page feature is enabled on your instance, you can choose to enable this experience for your embedding application users and customize the UI experience as per your needs. +By default, ThoughtSpot application loads in the classic (V1) experience mode. If the V3 navigation and home page features are enabled on your instance, you can choose to enable these experiences for your embedded application users and customize the UI as needed. The SDK also supports the V4 focused home page experience (`HomePage.Focused`), which requires Spotter to be enabled on your instance. For more information, see the following pages: @@ -273,13 +275,13 @@ appEmbed.on(EmbedEvent.load, hideLoader) For more information about events, see the following pages: -* xref:HostEvent.adoc[HostEvent] -* xref:EmbedEvent.adoc[EmbedEvent] +* xref:event-embedEvents.adoc[Embed events] +* xref:events-hostEvents.adoc[Host events] * xref:embed-events.adoc[Events and app integration] == Code sample -The following example shows the minimal code required to embed full ThoughtSpot experience in an app. +The following example shows the minimal code required to embed the full ThoughtSpot experience in an app. [source,JavaScript] ---- @@ -292,7 +294,7 @@ import { // Alternatively, you can use the ES6 import from CDN as shown below: // import { AppEmbed, AuthType, init } from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; -// Initialize th Visual Embed SDK with the host and authentication type +// Initialize the Visual Embed SDK with the host and authentication type init({ thoughtSpotHost: '', // Replace with your ThoughtSpot host authType: AuthType.None, // Use 'None' if authentication is handled outside the SDK @@ -306,7 +308,7 @@ const appEmbed = new AppEmbed( width: '100%', // Set the iframe width to 100% height: '100%', // Set the iframe height to 100% }, - pageId: Page.Liveboards, // Set the initial page to the Data page + pageId: Page.Liveboards, // Set the initial page to the Liveboards page } ); diff --git a/modules/ROOT/pages/just-in-time-provisioning.adoc b/modules/ROOT/pages/just-in-time-provisioning.adoc index a5e80275f..06975498d 100644 --- a/modules/ROOT/pages/just-in-time-provisioning.adoc +++ b/modules/ROOT/pages/just-in-time-provisioning.adoc @@ -177,6 +177,14 @@ Due to the nature of assertions returned from an IdP, the JIT provisioning capab In general, the IdP assertion can create a user and add them to existing ThoughtSpot groups within existing ThoughtSpot Orgs. == SAML SSO authentication +[NOTE] +==== +// SOURCE: SCAL-291968 — OIDCClient.java, OrgUtils.java +If your ThoughtSpot cluster uses per-org IdP configuration, ThoughtSpot automatically filters SAML and OIDC group and org claims at login time. Only claims that reference the Org bound to the authenticating IdP are used for JIT provisioning. Claims referencing other Orgs are dropped and logged as security audit events. This behavior ensures that a per-org IdP cannot be used to provision users into Orgs it is not authorized to manage. + +For more information, see xref:configure-saml.adoc#per-org-idp-org-isolation[Org isolation for per-org IdP authentication]. +==== + For SAML SSO users, you can link:https://docs.thoughtspot.com/cloud/latest/authentication-integration#_enable_saml_authentication[enable SAML authentication, window=_blank] and *Automatically add SAML users to ThoughtSpot upon first authentication*. For information about how to map `username`, `displayName`, `email`, and `orgId` properties from the IdP, see link:https://docs.thoughtspot.com/cloud/latest/authentication-integration#_configure_the_idp[Configure the IdP server for SAML authentication, window=_blank]. diff --git a/modules/ROOT/pages/locale-setting.adoc b/modules/ROOT/pages/locale-setting.adoc index fb770a360..d9a40fa16 100644 --- a/modules/ROOT/pages/locale-setting.adoc +++ b/modules/ROOT/pages/locale-setting.adoc @@ -4,7 +4,7 @@ :page-title: Set locale :page-pageid: set-locale -:page-description: You can change the locale settings of your embedded app to display the UI elements in your preferred language +:page-description: You can change the locale settings of your embedded app to display the UI elements in your preferred language and use the Manual translation REST APIs to supply custom translations for ThoughtSpot UI strings. The display language of the embedded ThoughtSpot UI is determined by the user's system locale. If your browser locale matches one of the locale options supported by ThoughtSpot, the ThoughtSpot UI automatically changes to that locale. If your browser locale is not supported by ThoughtSpot, the embedded UI is displayed in US English by default. For example, if your browser locale is an unsupported Central American locale, such as Spanish (Mexico) (es-MX), ThoughtSpot launches in en-US. If your browser doesn't allow you to change the locale, ThoughtSpot launches in the OS locale. @@ -117,8 +117,7 @@ To get details of the browser language settings for a given user, administrators == Limitations -* By default, ThoughtSpot _does not_ translate column names, object titles, description text, formulas, or metadata entered by the user. For example, if you name a visualization **Sales performance** in any variant of English and subsequently change the locale to Español, the name of the visualization remains **Sales performance**. + -However, if the column name and description alias [beta betaBackground]^Beta^ feature is enabled on your instance, you can localize the text on Search and Answer interfaces. To enable this feature on your instance, contact ThoughtSpot Support. -* If you specify a currency when uploading data, that currency format does not change when the locale changes. + -* ThoughtSpot translates keywords, operators, and error messages. See link:https://docs.thoughtspot.com/cloud/latest/keywords[Keyword reference] for all supported languages. - +* By default, ThoughtSpot does not automatically translate column names, object titles, description text, formulas, or metadata entered by the user. For example, if you name a visualization *Sales performance* in any variant of English and subsequently change the locale to Español, the name of the visualization remains *Sales performance*. + +To supply custom translations for ThoughtSpot UI strings programmatically, use the xref:manual-translation-api.adoc[Manual Translation REST APIs]. +* If you specify a currency when uploading data, that currency format does not change when the locale changes. +* ThoughtSpot translates keywords, operators, and error messages. See link:https://docs.thoughtspot.com/cloud/latest/keywords[Keyword reference, window=_blank] for all supported languages. \ No newline at end of file diff --git a/modules/ROOT/pages/manual-translation.adoc b/modules/ROOT/pages/manual-translation.adoc new file mode 100644 index 000000000..1866e935f --- /dev/null +++ b/modules/ROOT/pages/manual-translation.adoc @@ -0,0 +1,184 @@ += Manual Translation REST APIs +:toc: true +:toclevels: 2 + +:page-title: Manual Translation REST APIs +:page-pageid: manual-translation-api +:page-description: Use the Manual Translation REST APIs to programmatically import, export, and manage custom locale-specific translations for ThoughtSpot UI strings. + +By default, ThoughtSpot translates system UI elements such as menu labels, button text, and navigation controls into the user's configured locale. However, user-generated content such as object titles, column names, and description text is not automatically translated. + +The Manual Translation REST APIs let administrators and developers supply custom locale-specific translations for ThoughtSpot UI strings programmatically, without using the ThoughtSpot Admin portal. You can use these APIs to: + +* Upload a CSV file containing custom translations for one or more locales +* Export existing translations for review and editing +* Retrieve a translation bundle for a specific locale at runtime +* Delete all translations for an org or a cluster + +These APIs are available from ThoughtSpot Cloud 26.7.0 onwards. + +[NOTE] +==== +To manage manual translations through the ThoughtSpot Admin portal instead of the REST API, see link:https://docs.thoughtspot.com/cloud/latest/manual-translation[Manual translation, window=_blank] in the ThoughtSpot product documentation. +==== + +== Before you begin +The import, export, and delete endpoints require `ADMINISTRATION` (**Can administer ThoughtSpot**), `ORG_ADMINISTRATION` (**Can administer Org**), or APPLICATION_ADMINISTRATION (**Can administer application**) privileges. + +The translation bundle endpoint (`POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export`) does not require administrator privileges and is accessible to all authenticated users. + +//For more information about assigning privileges, see xref:privileges-and-roles.adoc[Privileges and roles]. + +=== How manual translations work + +When a user opens an embedded ThoughtSpot component, ThoughtSpot applies translations in the following order of precedence: + +. Custom translations uploaded via the Manual Translation API for the user's configured locale +. ThoughtSpot's built-in system translations for supported locales +. The ThoughtSpot default locale, US English (`en-US`) + +If a translation key is present in the uploaded CSV file, the custom value is displayed. If it is absent, ThoughtSpot falls back to its built-in string for that locale. + +Uploaded translations are scoped to either a single org (`ORG`) or for all Orgs. See <> for details. + +[#org-scope] +=== Org scope + +All Manual Translation API endpoints accept an optional `scope` parameter in the request body. This parameter controls the organizational context of the operation. + +[width="100%", cols="1,3"] +[options="header"] +|=== +| Value | Description +| `ORG` | *(Default)* Targets the calling user's current org. Use for all standard single-org or per-org translation management. +| `CLUSTER` | Targets the All Orgs context. Translations uploaded at cluster scope apply across all orgs in a multi-org deployment. Requires Tenant Admin or Org Admin privilege. +|=== + +If the `scope` parameter is omitted, it defaults to `ORG`. + +[#csv-format] +== CSV file format + +The import and export endpoints use a CSV file to represent translation data. All files must use UTF-8 encoding and conform to RFC 4180. + +=== Required columns + +The CSV file must contain exactly three columns, with headers exactly as shown: + +[width="100%", cols="1,3"] +[options="header"] +|=== +| Column | Description +| `content` | The original ThoughtSpot UI string in the default locale. This is the lookup key for the translation. +| `locale` | The locale identifier for the translation. Must be one of the xref:locale-setting.adoc#_supported_locale_ids[supported locale IDs] and must be in lowercase (for example, `fr-fr`, `de-de`, `ja-jp`). +| `translated-content` | The translated string to display when the user's locale matches the `locale` column value. +|=== + +[NOTE] +==== +Column headers are case-sensitive. Use exactly `content`, `locale`, and `translated-content`. +==== + +=== Constraints + +* The file must have a `.csv` extension. +* Maximum file size: 30 MB. +* Maximum number of data rows per upload: 10,000. +* Maximum characters per cell: 2,000. +* HTML tags and control characters (other than tab, line feed, and carriage return) are not permitted in cell values. +* The `locale` value must be lowercase in every row. For example, use `fr-fr`, not `fr-FR`. + +=== Example + +The following example shows a valid CSV file with translations for French and German: + +[source,text] +---- +content,locale,translated-content +Sales Performance,fr-fr,Performance des ventes +Sales Performance,de-de,Vertriebsleistung +Total Revenue,fr-fr,Revenu total +Total Revenue,de-de,Gesamtumsatz +New Answer,fr-fr,Nouvelle réponse +New Answer,de-de,Neue Antwort +---- + +== API endpoints + +=== Import manual translations + +To import a custom translation file, use the `/api/rest/2.0/localizations/manual-translation/import` API endpoint. This endpoint allows you to upload a CSV file containing custom translations. The operation is an *upsert*, that is new translation entries are inserted, and existing entries that match on both the `content` and `locale` columns are updated in place. A single upload can contain translations for multiple locales. + +The request body uses `multipart/form-data` encoding. + +[width="100%", cols="2,4"] +[options="header"] +|=== +| Parameter | Description +| `translations_file` | The CSV file containing translations. Must meet the xref:manual-translation-api.adoc#csv-format[CSV format requirements]. +| `scope` |__Optional__. Org scope selector. Allowed values are `ORG` and `CLUSTER`. +|=== + +A successful request returns HTTP `204 No Content`. If the file fails validation (for example, missing headers, oversized file, or invalid locale), the API returns HTTP `400 Bad Request` with an error description. + +=== Export manual translations +To export or download manual translated terms and labels in a CSV file, use the `/api/rest/2.0/localizations/manual-translation/export` API endpoint. This endpoint downloads all existing manual translations for the specified org scope as a CSV file. The downloaded file uses the same three-column format as the import CSV and can be edited and re-uploaded. + +[width="100%", cols="2,4"] +[options="header"] +|=== +| Parameter | Description +| `scope` | Org scope selector. Allowed values are `ORG` and `CLUSTER`. +|=== + +A successful request returns HTTP `200 OK` with the CSV file in the response body and a `Content-Disposition: attachment; filename=manual-translation.csv` response header. If no translations have been uploaded for the specified scope, the API returns HTTP `404 Not Found`. + +=== Get translation bundle +To retrieve a JSON map of all manual translations for a specific locale, use the `/api/rest/2.0/localizations/manual-translation/locales/{locale}/export` API endpoint. This endpoint can be used by the embedding applications to load custom translations at runtime, for example, to apply translations during initialization of an embedded ThoughtSpot component. + +[width="100%", cols="2,4"] +[options="header"] +|=== +| Parameter | Description +| `locale` |The locale to retrieve translations for. Must be lowercase and match the pattern `^[a-z]{2,}(-[a-z0-9]{2,})?$`. For example, `fr-fr`, `de-de`, `ja-jp`. +|=== + +A successful request returns HTTP `200 OK` with a JSON object in the following structure: + +[source,json] +---- +{ + "data": { + "translations": { + "Sales Performance": "Performance des ventes", + "Total Revenue": "Revenu total", + "New Answer": "Nouvelle réponse" + } + } +} +---- + +If no translations have been uploaded for the requested locale, the response returns an empty `translations` map. + +=== Delete manual translations + +To delete all manual translations, use the `/api/rest/2.0/localizations/manual-translation/delete` API endpoint. This endpoint deletes all manual translations for the specified org scope. After the delete operation, ThoughtSpot uses the built-in UI strings for all locales until new translations are uploaded. + +[WARNING] +==== +This operation deletes *all* translations for the specified scope. It cannot be scoped to a single locale or a subset of translation keys. This operation is not reversible. +==== + +[width="100%", cols="2,4"] +[options="header"] +|=== +| Parameter | Description +| `scope` |__Optional__. Org scope selector. Allowed values: `ORG` and `CLUSTER`. +|=== + +A successful request returns HTTP `204 No Content`. + +== Additional resources + +* xref:locale-setting.adoc[Configure locale in the Visual Embed SDK and via the Users REST API] +* link:https://docs.thoughtspot.com/cloud/latest/manual-translation[Manage translations through the ThoughtSpot Admin portal, window=_blank] diff --git a/modules/ROOT/pages/orgs.adoc b/modules/ROOT/pages/orgs.adoc index d83d63f0b..8e49e6288 100644 --- a/modules/ROOT/pages/orgs.adoc +++ b/modules/ROOT/pages/orgs.adoc @@ -253,6 +253,20 @@ a|[tag greenBackground tick]#✓# |===== +[#per-org-sso-isolation] +=== SSO and Org isolation + +// SOURCE: SCAL-291968 — OIDCClient.java, SecurityEventTypeEnum.java, design doc 1R4P3Eup4-UQJAWxyoeHjGr87mzJGWIOvfPDyHQF6-cQ +ThoughtSpot supports SAML and OIDC group synchronization on multi-tenant clusters. When you use **per-org IdP configuration**, ThoughtSpot enforces strict org isolation on all incoming group and org claims to protect tenant boundaries. + +* Each Org can be bound to its own identity provider. +* When a user logs in via a per-org IdP, only claims that reference that IdP's authorized Org are honored. Claims referencing other Orgs are dropped. +* Dropped claims are recorded as security audit events +//(`OIDC_CROSS_ORG_CLAIM_DROPPED`, `SAML_CROSS_ORG_CLAIM_DROPPED`). +* Existing manually-assigned org memberships are not removed by a per-org IdP login. + +For more information, see xref:configure-saml.adoc#per-org-idp-org-isolation[Org isolation for per-org IdP authentication]. + == Authentication considerations for embedded apps //// diff --git a/modules/ROOT/pages/prerender.adoc b/modules/ROOT/pages/prerender.adoc index bff01953b..bf568f4cb 100644 --- a/modules/ROOT/pages/prerender.adoc +++ b/modules/ROOT/pages/prerender.adoc @@ -320,4 +320,4 @@ prefetch("https://:", [ == Additional Resources * link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[Pre-rendering examples on GitHub, window=_blank] -* link:https://codesandbox.io/p/sandbox/github/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[CodeSandbox: Pre-rendering, window=_blank] +* link:https://stackblitz.com/github/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[StackBlitz: Pre-rendering, window=_blank] diff --git a/modules/ROOT/pages/privileges-and-roles.adoc b/modules/ROOT/pages/privileges-and-roles.adoc index f7967bac8..f602e2b55 100644 --- a/modules/ROOT/pages/privileges-and-roles.adoc +++ b/modules/ROOT/pages/privileges-and-roles.adoc @@ -6,7 +6,7 @@ :page-pageid: privileges-and-roles :page-description: Users are granted system features via privileges which are grouped into roles -System privileges determine the workflows and actions that users can perform within the ThoughtSpot application context. +System privileges determine the workflows and actions that users can perform within the ThoughtSpot application context. == Privileges ThoughtSpot allows you to define several types of privileges: @@ -14,13 +14,14 @@ ThoughtSpot allows you to define several types of privileges: * Role-specific privileges for administrators, developers, and other user personas. * Data-related privileges to allow or prevent access to upload, download, or manage data. * Workflow-specific privileges to enable or disable access to features such as SpotIQ analysis, scheduling Liveboards, or the experimental features available for evaluation and early adoption. +* Spotter-specific privileges to control access to Spotter and administer Spotter workflows. -For more information about privileges, see link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[Understand groups and privileges, window=_blank]. +For more information about privileges, see link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[Understand groups and privileges, window=_blank] and xref:roles.adoc#_application_control[Application control privileges]. == Roles -In ThoughtSpot 9.8.0.cl and later versions, privileges can be assigned via link:https://docs.thoughtspot.com/cloud/latest/rbac[Roles, window=_blank] and assigned to groups if Role-Based Access Control (RBAC) is enabled. The RBAC feature is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +Privileges can be assigned via link:https://docs.thoughtspot.com/cloud/latest/rbac[Roles, window=_blank] and grouped using Role-Based Access Control (RBAC). -If RBAC is not enabled, administrators can configure link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[privileges, window=_blank] and assign it directly to groups. +If RBAC is not enabled, administrators can configure link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[privileges, window=_blank] and assign them directly to groups. == User and group shareability *Shareable* is a property of a user or group object which controls visibility of users and groups in the *Share* dialog. diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index 9042d1d51..92512748e 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -281,6 +281,7 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later a|ThoughtSpot Cloud: 26.4.0.cl | v2.23.0 or later diff --git a/modules/ROOT/pages/rest-api-sdk-libraries.adoc b/modules/ROOT/pages/rest-api-sdk-libraries.adoc index 306ab3862..0db64352d 100644 --- a/modules/ROOT/pages/rest-api-sdk-libraries.adoc +++ b/modules/ROOT/pages/rest-api-sdk-libraries.adoc @@ -10,7 +10,6 @@ ThoughtSpot provides native SDK libraries to help client applications call REST Currently, the REST API client libraries are available for xref:rest-api-sdk-typescript.adoc[TypeScript] and xref:rest-api-java-sdk.adoc[Java]. These SDKs provide language-specific client libraries to call APIs from client applications. - == Community SDKs You can use the following open-source, community-supported SDKs. diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index ccb55b8ca..452dba9e6 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -203,6 +203,7 @@ Note the version recommendations for your ThoughtSpot instances: [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 26.7.0.cl | v2.26.0 or later a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later a|ThoughtSpot Cloud: 26.4.0.cl | v2.23.0 or later diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index 6864a95a3..dfaf6a4ac 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -61,16 +61,6 @@ Allows sending a query to an ongoing conversation session with Spotter agent and |ThoughtSpot Cloud: __10.15.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ -//a|`PUT /api/rest/2.0/ai/agent/instructions/set` + -//Sets custom instructions for the Spotter agent. -//|ThoughtSpot Cloud: __26.7.0.cl or later__ + -//ThoughtSpot Software: __Not available__ a| +++Try it out+++ - -//a|`GET /api/rest/2.0/ai/agent/instructions/get` + -//Retrieves the custom instructions currently configured for the Spotter agent. -//|ThoughtSpot Cloud: __26.7.0.cl or later__ + -//ThoughtSpot Software: __Not available__ a| +++Try it out+++ - a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + Stops an in-progress Spotter agent response for a given conversation session. |ThoughtSpot Cloud: __26.6.0.cl or later__ + @@ -85,6 +75,37 @@ a|`POST /api/rest/2.0/ai/instructions/get` + Retrieves NL instructions from a data model. |ThoughtSpot Cloud: __10.15.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets custom instructions for the Spotter agent. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the custom instructions currently configured for the Spotter agent. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/conversations` + +Retrieves a paginated list of saved Spotter agent conversations for the authenticated user. Only conversations created with `enable_save_chat: true` are returned. Requires `CAN_USE_SPOTTER` privilege. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}` + +Retrieves the full message history of a single saved Spotter agent conversation, including user prompts and agent response items for each turn. Requires `CAN_USE_SPOTTER` privilege. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates the display title of a saved Spotter agent conversation. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +Permanently deletes a saved Spotter agent conversation and all its associated messages. This operation is irreversible. Requires `CAN_USE_SPOTTER` privilege and ownership of the conversation. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + |===== -- @@ -442,7 +463,7 @@ ThoughtSpot Software: __10.0.0.sw or later__ a| a|`POST /api/rest/2.0/dbt/generate-sync-tml` + -Resynchronizes the existing list of Models and Tables TML content for the specified DBT connection object and imports these to Thoughtspot. +Resynchronizes the existing list of Models and Tables TML content for the specified DBT connection object and imports these to ThoughtSpot. |ThoughtSpot Cloud: __9.10.0.cl or later__ + ThoughtSpot Software: __10.0.0.sw or later__ a| @@ -596,6 +617,41 @@ ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/localizations/manual-translation/export` + +Exports all manual translations for the specified org scope as a CSV file. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + +a|`POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + +Returns all manual translations for the specified locale as a JSON object. Accessible to all authenticated users. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + +a|`POST /api/rest/2.0/localizations/manual-translation/delete` + +Deletes all manual translations for the specified org scope. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ +|===== +-- + == Metadata [div boxAuto] @@ -630,7 +686,7 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| a|`POST /api/rest/2.0/metadata/tml/export/batch` + -Exports a complete set of TML for user, user group, or Role object. +Exports a complete set of TML for a user, user group, or Role object. |ThoughtSpot Cloud: __10.1.0.cl or later__ + ThoughtSpot Software: __10.1.0.sw or later__ a|+++Try it out +++ @@ -701,7 +757,7 @@ a| +++Try it out+++ a| `POST /api/rest/2.0/metadata/update-obj-id` + -Update object IDs for given metadata objects. +Updates object IDs for given metadata objects. |ThoughtSpot Cloud: __10.8.0.cl or later__ + ThoughtSpot Software: __10.10.0.sw or later__ a| @@ -896,7 +952,7 @@ Gets access permission details for metadata objects. To get object access detail ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out+++ a| `POST /api/rest/2.0/security/metadata/manage-object-privilege` + -Allows assigning object-level permissions to other users and groups and granting access to Spotter coaching information. +Allows assigning object-level permissions to other users and groups and granting access to Spotter coaching information. |ThoughtSpot Cloud: __26.3.0.cl or later__ + ThoughtSpot Software: Not available a| +++Try it out+++ @@ -924,6 +980,61 @@ Adds or updates column security rules applied on the Table specified in the API |ThoughtSpot Cloud: __10.12.0.cl or later__ a| +++Try it out +++ +|===== +-- +== Style customization + +// SOURCE: SCAL-293070, SCAL-293071 + +[div boxAuto] +-- +[width="100%" cols="8,5,3"] +[options='header'] +|===== +|API endpoint| Release version | Playground link + +a|`POST /api/rest/2.0/customization/styles/search` + +Gets the current style configuration at the cluster and active Org scope. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/update` + +Updates style settings such as the navigation panel color, chart color palette, logos, embedded footer text, and visualization font assignments at the cluster or Org scope. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/fonts/search` + +Gets custom fonts uploaded to the ThoughtSpot instance. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates the display name, weight, style, or color of an existing custom font. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive. +|ThoughtSpot Cloud: __26.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ +a| +++Try it out+++ + |===== -- @@ -957,7 +1068,7 @@ ThoughtSpot Software: __9.5.0.sw or later__ a| a| `POST /api/rest/2.0/system/config-update` + -Gets details of the current configuration running on your cluster. +Updates the current configuration of your instance. a|ThoughtSpot Cloud: __9.2.0.cl or later__ + ThoughtSpot Software: __9.5.1.sw or later__ a| +++Try it out +++ @@ -1018,7 +1129,7 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| a| `POST /api/rest/2.0/tags/{tag_identifier}/delete` + -Deletes an Org object from ThoughtSpot. +Deletes a tag object from ThoughtSpot. a|ThoughtSpot Cloud: __9.0.0.cl or later__ + ThoughtSpot Software: __9.0.1.sw or later__ a| @@ -1077,7 +1188,7 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ a|`POST /api/rest/2.0/users/import` + -Gets an authentication token from ThoughtSpot that grants access to a full application session. +Imports users from an external database to ThoughtSpot. |ThoughtSpot Cloud: __9.0.0.cl or later__ + ThoughtSpot Software: __9.0.1.sw or later__ a| @@ -1098,7 +1209,7 @@ ThoughtSpot Software: __9.0.1.sw or later__ a| +++Try it out +++ a|`POST /api/rest/2.0/users/force-logout` + -Logs out a users from their current sessions. +Logs out users from their current sessions. |ThoughtSpot Cloud: __9.0.0.cl or later__ + @@ -1238,7 +1349,7 @@ a|ThoughtSpot Cloud: __26.4.0.cl or later__ a| +++Try it out +++ | `POST /api/rest/2.0/template/variables/update-values` [tag redBackground]#DEPRECATED# + -Allows updating properties one or several variable. +Allows updating properties of one or several variables. a|ThoughtSpot Cloud: __10.9.0.cl or later__ a| +++Try it out +++ @@ -1269,6 +1380,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.7.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| ++++Try it out+++ + |`POST /api/rest/2.0/webhooks/{webhook_identifier}/update` + Allows you to edit properties of a webhook object. diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 6bc715037..0cad327a6 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -2,17 +2,39 @@ :toc: true :toclevels: 1 -:page-title: Changelog +:page-title: REST API v2.0 changelog :page-pageid: rest-v2-changelog :page-description: Changelog of REST APIs This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. -== Version 26.6.0.cl, June 2026 +== Version 26.7.0.cl, July 2026 === Spotter AI APIs -//// +Save chat AI APIs:: +ThoughtSpot introduces the following REST API endpoints and enhancements to manage saved Spotter conversations programmatically. These endpoints allow you to build custom conversation history interfaces in embedded applications without using the native Spotter UI. + +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates attributes of an existing agent conversation. +* `GET /api/rest/2.0/ai/agent/conversations` + +Retrieves the list of saved agent conversations for the currently authenticated user. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + +Retrieves the full content of a saved conversation with Spotter agent. +* `POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +Updates the display title of a saved conversation. +* `DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +Deletes a saved conversation and all its associated messages. +* `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + +Loads the full answer payload for a specific answer item in an agent conversation. + ++ +For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[Saving and managing Spotter AI chat]. + +Save chat settings in conversation create API:: + +The `POST /api/rest/2.0/ai/agent/conversation/create` API endpoint is modified to allow users to save conversations by setting `enable_save_chat: true` in the API request. + Agent instructions APIs:: The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. @@ -21,10 +43,75 @@ Sets behavioral instructions for the Spotter agent. Use this endpoint to define * `GET /api/rest/2.0/ai/agent/instructions/get` + Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. - + For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. -//// + +=== Webhooks + +New API endpoint:: +The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving the storage setup information required for configuring a GCS or S3 storage destination for webhook delivery. + +Enhancements:: + +* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. +* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activate status, resetting authentication, signature verification, and storage destination properties. +* API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. + +=== Communication channel monitoring + +The `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint supports the `end_epoch_time_in_millis` parameter, which allows fetching records with a specific end timestamp. + +=== Style customization APIs + +ThoughtSpot introduces the following REST API v2.0 endpoints to manage style customization settings programmatically. + +Style configuration:: + +* `POST /api/rest/2.0/customization/styles/search` + +Returns the current style configuration at the `CLUSTER` or active `ORG` scope. + +* `POST /api/rest/2.0/customization/styles/update` + +Updates style settings at the `CLUSTER` or `ORG` scope. + +Custom fonts:: + +* `POST /api/rest/2.0/customization/styles/fonts/upload` + +Uploads a custom font file to ThoughtSpot. + +* `POST /api/rest/2.0/customization/styles/fonts/search` + +Returns custom fonts uploaded to the instance. +//Use the `include_font_assignments` parameter to include information about which visualization elements each font is assigned to. + +* `PUT /api/rest/2.0/customization/styles/fonts/{font_identifier}/update` + +Updates the display name, weight, style, or color of an existing custom font. + +* `POST /api/rest/2.0/customization/styles/fonts/delete` + +Deletes one or more custom fonts from the font library. + +Logo export:: + +* `POST /api/rest/2.0/customization/styles/logos/export` + +Exports the current logo files as a ZIP archive containing the default logo and the wide logo. + +For more information, see xref:customize-style-api.adoc[Style customization APIs]. + +=== Manual translation APIs +The manual translation API endpoints allow you to import, export, and delete translations of terms and labels that can be presented to the user based on their locale settings. + +* `POST /api/rest/2.0/localizations/manual-translation/import` + +Allows importing a CSV file containing translated terms and labels. +* `POST /api/rest/2.0/localizations/manual-translation/locales/{locale}/export` + +Retrieves all translations for a specific locale as a JSON map. +* `POST /api/rest/2.0/localizations/manual-translation/export` + +Downloads all manually translated terms and labels in the Org context as a CSV file. +* `POST /api/rest/2.0/localizations/manual-translation/delete` + +Deletes all manual translations from the Org. + +For more information, see xref:manual-translation.adoc[Manual translations]. + +== Version 26.6.0.cl, June 2026 + +=== Spotter AI APIs Stop in-progress agent response:: @@ -33,15 +120,15 @@ Stops a Spotter agent response that is currently in progress for a given convers For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. -==== Authentication -The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allows enabling and disabling the authentication. Currently, only support trusted authentication. +=== Authentication +The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allow enabling and disabling authentication. These endpoints currently support only trusted authentication. * `POST /api/rest/2.0/auth/configure` + Enables or disables authentication at cluster or Org level for the specified auth type. -* `POST /api/rest/2.0/auth/search` + +* `POST /api/rest/2.0/auth/search` + Returns the authentication configuration for the specified auth type at cluster and Org level. -==== Connection deactivate and activate API [beta betaBackground]^Beta^ +=== Connection deactivate and activate API [beta betaBackground]^Beta^ // SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 @@ -63,23 +150,19 @@ Exports from this endpoint inherently respect Liveboard-level filters, Runtime F To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. Spotter Answer export:: -// SOURCE: SCAL-236681, SCAL-306548 XLSX and PDF export formats are now supported for Spotter (conversational) Answers. Custom PNG dimensions:: -// SOURCE: SCAL-236681, SCAL-306548 PNG exports now support custom dimensions via the following new parameters: + -* `x_resolution` — Sets the export width in pixels. Valid range: 600–3840 px. -* `y_resolution` — Sets the export height in pixels. Valid range: 600–3840 px. +* `x_resolution`: Sets the export width in pixels. Valid range: 600–3840 px. +* `y_resolution`: Sets the export height in pixels. Valid range: 600–3840 px. Display scaling:: -// SOURCE: SCAL-236681, SCAL-306548 A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. Valid range: 80–500%. Automatic file naming:: -// SOURCE: SCAL-236681, SCAL-306548 The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance. @@ -113,14 +196,13 @@ These new endpoints replace the legacy agent conversation and SSE streaming APIs ==== Deprecated endpoints [.version-badge.deprecated]#Deprecated# -* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + +* `POST /api/rest/2.0/ai/agent/{conversation_identifier}/converse` + Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`. * `POST /api/rest/2.0/ai/agent/converse/sse` + Replaced by `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` -These endpoints are deprecated and will be removed -in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. +These endpoints are deprecated and will be removed in a future release. Embedding applications and integrations using these APIs are advised to migrate to the new API endpoints for improved experience. ==== Enhancements to conversation creation API [.version-badge.breaking]#Breaking# @@ -150,7 +232,7 @@ The API response now returns the `conversation_identifier`, which is used in all subsequent send message or SSE streaming calls. === Liveboard report API enhancements [beta betaBackground]^Beta^ -The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the pdf downloads by introducing the following parameters: +The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF downloads by introducing the following parameters: * `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. * `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. @@ -194,16 +276,16 @@ You can now validate a webhook connection by sending a test payload via an API r Webhook monitoring:: To monitor the status of webhook jobs and scheduled events, ThoughtSpot introduces the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. -For more information see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. +For more information, see xref:webhooks-comm-channel.adoc[Webhook configuration validation and monitoring]. === Collections API endpoints The following APIs are introduced for Collections: * `POST /api/rest/2.0/collections/create` [beta betaBackground]^Beta^ + -Creates a new Collection +Creates a new Collection. * `POST /api/rest/2.0/collections/search` [beta betaBackground]^Beta^ + -Search for a Collection in the existing Collections +Searches for a Collection in ThoughtSpot * `POST /api/rest/2.0/collections/{collection_identifier}/update` [beta betaBackground]^Beta^ + Updates an existing Collection * `POST /api/rest/2.0/collections/delete` [beta betaBackground]^Beta^ + @@ -352,7 +434,7 @@ For more information, see xref:abac-user-parameters.adoc[ABAC via tokens]. System:: This release introduces the following endpoints for configuring communication channel preferences. -* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + +* `POST /api/rest/2.0/system/preferences/communication-channels/configure` [beta betaBackground]^Beta^ + Sets a communication channel preference for all Orgs at the cluster level or at the individual Org level. * `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + Gets details of the communication channel preferences configured on ThoughtSpot. @@ -391,7 +473,7 @@ The variable API enhancements are listed in the following sections. For addition ==== Variable creation API -* The variable creation endpoint `/api/rest/2.0/template/variables/create` doesn't support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. +* The variable creation endpoint `/api/rest/2.0/template/variables/create` does not support assigning values to a variable. To assign values to a variable, use the `/api/rest/2.0/template/variables/update-values` endpoint. * The `sensitive` parameter is renamed as `is_sensitive`. //* You can define the data type for variables using the `data_type`property. //* You can now create formula variables. To create a formula variable, use define the variable type as `FORMULA_VARIABLE` variable type in your API request . @@ -431,14 +513,14 @@ Support for `variable_values` property in `/api/rest/2.0/auth/session/user` API Spotter:: * `POST /api/rest/2.0/ai/agent/conversation/create` + -Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + * `POST /api/rest/2.0/ai/relevant-questions/` + Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. * `POST /api/rest/2.0/ai/agent/converse/sse` + -Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + +Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + //* `POST /api/rest/2.0/ai/data-source-suggestions` + //Returns a list of relevant data sources, such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + @@ -522,7 +604,7 @@ The `POST /api/rest/2.0/metadata/tml/export` API request allows exporting column The search metadata (`/api/rest/2.0/metadata/search`) API includes the following enhancements: * The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. -* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. +* The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows you to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. * The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. @@ -548,9 +630,9 @@ Allows you to personalize the ThoughtSpot notification emails content. * `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + Removes the customizations done for the ThoughtSpot notification emails. * `POST /api/rest/2.0/customization/email/search` + -Allows searching the email customization configuration if any set for ThoughtSpot. +Allows searching the email customization configuration if configured for ThoughtSpot. * `POST /api/rest/2.0/customization/email/validate` + -Validates the email customization configuration if any set for ThoughtSpot. +Validates the email customization configuration if configured for ThoughtSpot. === Group API @@ -649,7 +731,7 @@ Filters metadata objects by the user-defined object ID. This parameter returns d === TML APIs -* The `all_orgs_context` parameter in TML import APIs (` /api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. +* The `all_orgs_context` parameter in TML import APIs (`/api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. * The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. @@ -721,7 +803,7 @@ TML async import:: The `/api/rest/2.0/metadata/tml/async/import` supports setting the following properties via API requests: + * `import_policy` + -Allows you specify if all objects should be imported during the TML import operation. Valid values are: +Allows you to specify if all objects should be imported during the TML import operation. Valid values are: ** `PARTIAL_OBJECT` (default) ** `PARTIAL` @@ -773,7 +855,7 @@ Creates a conversation session. * `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + Generates responses for user queries and follow-up questions. * `POST /api/rest/2.0/ai/answer/create` + -Generate an Answer from a Natural Language Search query +Generates an Answer from a Natural Language Search query. Authentication:: The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index 6d203bc84..f5cc82a48 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -4,7 +4,7 @@ :page-title: Role-based access control :page-pageid: rbac -:page-description: Use the Robe-based access control feature for granular access control +:page-description: Use the Role-based access control feature for granular access control ThoughtSpot administrators can assign granular privileges to users with Role-Based Access Control (RBAC). @@ -47,12 +47,7 @@ Administrators can create a Role with a specific set of privileges and assign th Roles are unique to an Org and can be created only within the context of an Org. ==== -For more information about Role and Group assignment, see link:https://docs.thoughtspot.com/cloud/latest/rbac#_data_download_control_privileges[ThoughtSpot Product Documentation]. -//// -[.widthAuto] -image::./images/role-group.png[Roles] -//// - +For more information about Role and Group assignment, see link:https://docs.thoughtspot.com/cloud/latest/rbac[ThoughtSpot Product Documentation, window=_blank]. == Role categories and privileges @@ -77,13 +72,13 @@ UI: *Can manage users* | Allows users to create, edit, and manage users via UI |Group administration | API: `GROUP_ADMINISTRATION` + UI: *Can manage groups* | Allows users to create, edit, and manage groups via UI or REST API calls. |Role administration| API: `ROLE_ADMINISTRATION` + -UI: *Can manage roles* | Allows users to create, edit, and manage Roles vis UI or REST API calls. +UI: *Can manage roles* | Allows users to create, edit, and manage Roles via UI or REST API calls. |Authentication administration|API: `AUTHENTICATION_ADMINISTRATION` + UI: *Can manage authentication* | Allows users to manage authentication and authorization process for ThoughtSpot users. |Application administration|API: `APPLICATION_ADMINISTRATION` + UI: *Can manage application settings* | Provides access to manage cluster-wide application settings, activation and de-activation of features on an instance. |System monitoring|API: `SYSTEM_INFO_ADMINISTRATION` + -UI: *Can view system activities* | Allows users to manage system activities. +UI: *Can view system activities* | Allows users to view system activities and monitor health. |Billing administration|API: `BILLING_INFO_ADMINISTRATION` + UI: *Can view billing information* | Allows view access to billing information. |Trusted authentication control|API: `CONTROL_TRUSTED_AUTH` + @@ -105,7 +100,7 @@ link:https://docs.thoughtspot.com/cloud/latest/analyst-studio-getting-started[An === Application control -The application control privileges include the following: +The application control role privileges include the following: [width="100%" cols="2,4,4"] [options='header'] @@ -116,7 +111,7 @@ UI: *Has SpotIQ privilege* | Allows access to the SpotIQ feature in ThoughtSpot. |Developer| API: `DEVELOPER` + UI: *Has developer privilege* a| Allows users to access the following features and workflows: -** Access **Develop** page and Playground + +** Access *Develop* page and Playground + ** Embed a ThoughtSpot application page, object, or full experience in an external application + ** Customize styles for embedded content + ** Add custom actions to the embedded objects such as Liveboard and visualizations + @@ -126,29 +121,29 @@ UI: *Has developer privilege* a| Allows users to access the following features UI: *Can schedule for others* |Allows users to schedule, edit, and delete Liveboard jobs. |ThoughtSpot Sync|API: `SYNCMANAGEMENT` + UI: *Can manage sync settings* | Allows setting up secure pipelines to external business apps and sync data using ThoughtSpot Sync. -|ThoughtSpot Spotter|API: `CAN_USE_SPOTTER` + +|Spotter access|API: `CAN_USE_SPOTTER` + UI: *Can use Spotter* | Allows access to ThoughtSpot Spotter and natural language query and answer generation. -|Catalog management|API: `CAN_CREATE_CATALOG` + -UI: *Can manage catalog*| Allows users to create, edit, and manage a link:https://docs.thoughtspot.com/cloud/latest/catalog-integration[data connection to Alation, window=_blank], and import metadata. +|Spotter administration|API: `CAN_MANAGE_SPOTTER` + +UI: *Can manage Spotter* a| Allows a designated Spotter administrator to manage Spotter's behavior across the organization. This role provides the following capabilities: -//|R Analysis|API: `RANALYSIS` + -//UI: *Can invoke custom R analysis* |Allows invoking R scripts to explore search answers and share custom scripts. +* On data models: The user can manage global coaching, manage Spotter memory (including memory from multi-model Liveboards), and delegate coaching access to other users. +* Across all Orgs (regardless of data model access): the user can add and manage Spotter instructions. -|Liveboard verification|API: `LIVEBOARD_VERIFIER` + -UI: *Can verify Liveboards* | Allows Liveboard users to verify Liveboard access requests and mark a Liveboard as verified. -|Webhook management| API: `CAN_MANAGE_WEBHOOKS` + -UI: *Can manage webhooks* | Allows users to xref:webhooks.adoc#[create and manage a webhook]. -|Version control with Git | API: `CAN_MANAGE_VERSION_CONTROL` + -UI: *Can toggle version control for objects* | Allows users to enable version control on a Liveboard or Answer. -|=== +[NOTE] +==== +The `CAN_MANAGE_SPOTTER` privilege does not grant data model edit access, does not allow editing columns, synonyms, or descriptions, and does not override data access permissions. +==== +|Catalog management|API: `CAN_CREATE_CATALOG` + +UI: *Can manage catalog*| Allows users to create, edit, and manage a link:https://docs.thoughtspot.com/cloud/latest/catalog-integration[data connector catalog, window=_blank]. +|=== === Object access control The `SHAREWITHALL` (**Can share with all users**) Role privilege allows users to share objects with all the users and groups in ThoughtSpot. === Data control -The application control privileges include the following: +The data control privileges include the following: [width="100%" cols="2,4,4"] [options='header'] @@ -183,12 +178,20 @@ The `DATADOWNLOADING` (**Can download Data**) Role privilege allows users to dow |Role type|Privilege|Description |Data download | API: `DATADOWNLOADING` + UI: **Can download Data**| Allows users to download data from objects such as Liveboards and Answers. -|Download visuals |API: `CAN_DOWNLOAD_VISUALS` + +|Download visuals [earlyAccess eaBackground]#Early Access# |API: `CAN_DOWNLOAD_VISUALS` + UI: *Can download visuals* |Allows users to download data in the PDF or PNG file format. This is an early access feature and is not enabled by default on ThoughtSpot instances. -|Data export |API: `CAN_DOWNLOAD_DETAILED_DATA` + +|Data export [earlyAccess eaBackground]#Early Access# |API: `CAN_DOWNLOAD_DETAILED_DATA` + UI: *Can download detailed data* | Allows users to export data in XLSX/CSV format. This is an early access feature and is not enabled by default on ThoughtSpot instances. |=== +[IMPORTANT] +==== +* Contact ThoughtSpot support to enable the new `CAN_DOWNLOAD_VISUALS` and `CAN_DOWNLOAD_DETAILED_DATA` privileges. +* Once these granular privileges are enabled, the `DATADOWNLOADING` privilege will cease to exit. +* Users who previously did not have `DATADOWNLOADING` privileges will not be automatically assigned the new download privileges. Administrators can assign them manually. +* Users who previously had `DATADOWNLOADING` privileges will automatically be assigned both new privileges - `CAN_DOWNLOAD_VISUALS` and `CAN_DOWNLOAD_DETAILED_DATA`. +==== + == How to create and assign Roles You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the REST API v1 and v2 endpoints. @@ -220,7 +223,7 @@ Removes the Roles assigned to a group Edit Role associations of a group object |Object query|To get the details of Roles assigned to a group object, use the following API endpoint: * xref:group-api.adoc#get-users-group[`GET /tspublic/v1/group/`] + -Note that the API response shows the assigned Roles and privileges in the `assignedRoles` and `granularPrivilges` arrays. +Note that the API response shows the assigned Roles and privileges in the `assignedRoles` and `granularPrivileges` arrays. |=== === REST API v2 endpoints for Role administration and assignment diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 13b7fce33..338c9a5d5 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -6,7 +6,7 @@ :page-pageid: runtime-filters :page-description: Apply filters to visualizations at runtime and pass them as URL parameters -Runtime filters allow you to apply filters on a Liveboard, Answer, visualization, or conversation session with Spotter. These filters are not persistent filters saved in the object, but are applied dynamically at runtime. You can use runtime filters to pre-filter content for your application users based on context and embedding app's requirements. +Runtime filters allow you to apply filters on a Liveboard, Answer, visualization, or conversation session with Spotter. These filters are not persistent filters saved in the object, but are applied dynamically at runtime. You can use runtime filters to pre-filter content for your application users based on context and the embedding app's requirements. == Overview @@ -47,30 +47,28 @@ Some operators like `EQ` and `LE` accept a single operand, whereas `BW_INC_MAX`, === Maximum filter count -The SDK processes a maximum of *49 runtime filters* per embedded object. +The SDK processes a maximum of 49 runtime filters per embedded object. -NOTE: The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the +The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the parsing loop runs from index `1` up to (but not including) `50` (`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. This applies to both input paths: -* URL query parameters — filter values appended to the embed URL +* URL query parameters: filter values appended to the embed URL (`col1=`, `op1=`, `val1=`, `col2=`, …) -* `runtimeFilters` embed config property — filters passed as an array in the -SDK initialisation config for `LiveboardEmbed`, `AppEmbed`, and +* `runtimeFilters` embed config property: filters passed as an array in the +SDK initialization config for `LiveboardEmbed`, `AppEmbed`, and `SearchEmbed` +[IMPORTANT] +==== When the number of runtime filters exceeds 49, filters beyond that index are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the first 49 filters -without any indication that additional filters were discarded. - -IMPORTANT: This silent-drop behaviour means that, if your application passes 60 -runtime filters, the last 11 are ignored without any notification to the -developer. Always validate filter counts in your application -before passing them to the SDK. +without any indication that additional filters were discarded. This silent-drop behavior means that, if your application passes 60 runtime filters, the last 11 are ignored without any notification to the developer. Always validate filter counts in your application before passing them to the SDK. +==== === Supported data types @@ -168,7 +166,7 @@ new Date('2020-05-22').getTime() / 1000 == Runtime filters in Visual Embed SDK -If you are embedding Spotter, Liveboard, visualization or the full application using Visual Embed SDK, you can apply filters using the `runtimeFilters` property. In the full app embed mode, ThoughtSpot applies runtime filters on all Liveboard, visualization, and Answer objects in the embedded app. +If you are embedding Spotter, Liveboard, visualization, or the full application using the Visual Embed SDK, you can apply filters using the `runtimeFilters` property. In the full app embed mode, ThoughtSpot applies runtime filters on all Liveboard, visualization, and Answer objects in the embedded app. The following example shows how to apply runtime filters on an embedded visualization in the SDK. Here, the runtime filter is operating on the `Revenue` column to filter the data matching `100000`. @@ -239,7 +237,7 @@ const liveboardEmbed = new LiveboardEmbed('#tsEmbed', { If the Liveboard or Answer already has one or more filters applied, runtime filters will act as an `AND` condition. This means that all filter conditions, including those supplied in the runtime filters and Liveboard filter, must match to get the desired data. -In the following example, the OR condition is applied; That is, if at least one condition matches, the Liveboard returns data. +In the following example, the OR condition is applied; that is, if at least one condition matches, the Liveboard returns data. .Example for OR condition [source,JavaScript] @@ -292,7 +290,7 @@ a| ---- | `NE` + -Not exactly or Not equal to + +Not equal to + Number of values allowed: 1 a| [source,JavaScript] ---- @@ -368,7 +366,7 @@ a| }] ---- -See also, xref:runtime-filters.adoc#_and_and_or_conditions_in_filters[AND/OR conditions in filters], for information about the AND and OR condition for filters. +See also, xref:runtime-filters.adoc#_and_and_or_conditions_in_filters[AND/OR conditions in filters], for information about the AND and OR conditions for filters. | `BEGINS_WITH` + begins with + @@ -475,7 +473,7 @@ The following video shows how to apply multiple runtime filters on a Liveboard. -- video::./images/runtime-filters.mp4[width=100%,options="autoplay,loop"] ++++ - Copy sample code + Copy sample code Try it out in Playground ++++ @@ -532,7 +530,7 @@ https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan&col2=p ==== URL format when embedding without SDK -If embedding a ThoughtSpot Liveboard without the SDK, ensure that add the runtime filters before `#/path` in the URL as shown in the following example: +If embedding a ThoughtSpot Liveboard without the SDK, ensure that you add the runtime filters before `#/path` in the URL as shown in the following example: ---- https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan#/embed/viz/{Liveboard_id}/{visualization_id} ---- @@ -581,7 +579,6 @@ curl -X POST \ * `POST /api/rest/2.0/report/answer` + Allows downloading Answer data in PDF, XLSX, CSV, and PNG format. - + [source,cURL] ---- @@ -661,13 +658,12 @@ curl -X POST \ * `POST /api/rest/2.0/metadata/answer/data` + Gets data from a saved Answer. - + [source,cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ - -H 'Authorization: Bearer {access-token}'\\ + -H 'Authorization: Bearer {access-token}'\ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ @@ -712,7 +708,7 @@ https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id={Liveboard_id https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=543619d6-0015-4667-b257-eff547d13a12&vizid=%5B%224ff5b939-453d-40ff-8fc2-a1d972047c86%22%5D&col1=State&op1=EQ&val1=California ---- -The following is another example of a REST API request URL with a filter. Here the runtime filter is operating on the column `Category` and returning values that are equal to `mfgr%2324`. +The following is another example of a REST API request URL with a filter. Here, the runtime filter is operating on the column `Category` and returning values that are equal to `mfgr%2324`. ---- https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata? diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 4b07695db..5ea2587af 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1,4 +1,4 @@ -= Spotter Agent AIs += Spotter Agent APIs :toc: true :toclevels: 2 @@ -47,7 +47,7 @@ __Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` [.version-badge.new]#New# + xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. -__Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. +__Replaces /api/rest/2.0/ai/agent/converse/sse__. a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + @@ -86,7 +86,7 @@ The request body must include the `metadata_context`. REST API clients must have * `type` + Metadata context type. The context type is mandatory. Select one of the following values: -** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for user's queries. +** `AUTO_MODE` to allow Spotter Agent to automatically discover and select the most relevant datasets for users' queries. ** `DATA_SOURCE` to set a specific data source as the data context. You must specify `data_source_context` and data source IDs. + To set a specific data source object, use `data_source_identifier`. + To set multi-data context, use `data_source_identifiers`. @@ -452,7 +452,7 @@ data: [{"id":"hxWMDP-pgR3B","type":"answer","group_id":"m1MTvttEUa7o","metadata" data: [{"type":"notification","code":"FINAL_RESPONSE_NOTIFICATION"}] ---- -For the complete response in one payload, use `sendAgentConversationMessage` instead. +For the complete response in one payload, use the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[`/send` endpoint] instead. //// [source,] @@ -755,7 +755,7 @@ A conversation title (`title`, `conv_id`). * `notification` + Progress or status update (`group_id`, `metadata`, `code`). For example, `TOOL_CALL_NOTIFICATION`, `nls_start`, `FINAL_RESPONSE_NOTIFICATION`. * `type` + -Type can be `thinking`, `text` +Type can be `thinking`, `text`. * `text` + Complete text block in markdown format. * `text-chunk` + @@ -784,7 +784,7 @@ Events in the thinking phase carry `"metadata": { "type": "thinking" }`. All oth Every event includes a `group_id`. Events sharing the same `group_id` belong together. During the thinking phase, each tool call gets its own `group_id`. A `FINAL_RESPONSE_NOTIFICATION` notification marks the boundary between the thinking and output phases. -[mermaid] +[listing] ---- THINKING PHASE ─────────────────────────────────────────────────────────── @@ -818,7 +818,7 @@ OUTPUT PHASE [width="100%" cols="2,4"] [options='header'] -|=== +|===== |Code| When it appears |`QH`|Query handling started |`TML_GEN` / `TML_GEN_RETRY`|Generating or retrying TML @@ -829,9 +829,9 @@ OUTPUT PHASE |`SUMMARIZING_RESULTS`|Summarizing results |`TOOL_CALL_NOTIFICATION`|Tool invocation (during thinking phase) |`FINAL_RESPONSE_NOTIFICATION`|Marks the transition from thinking to output -|`search_datasets_start` / +search_datasets_end+|Data source discovery in progress or complete +|`search_datasets_start` / `search_datasets_end`|Data source discovery in progress or complete |`approval_required`|An external tool requires user permission before proceeding -|=== +|===== === SSE event payload reference @@ -1043,8 +1043,7 @@ data: { The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. -Use this endpoint when you want to cancel a long-running Spotter response before it completes. -The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. +Use this endpoint when you want to cancel a long-running Spotter response before it completes. The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. === Request parameters @@ -1070,7 +1069,7 @@ curl -X POST \ === Example response -If the API request is successful, ThoughtSpot stops the in-progress response and returns an 204 response code. +If the API request is successful, ThoughtSpot stops the in-progress response and returns a 204 response code. If the conversation session is not found or has expired, the API returns an error: diff --git a/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc new file mode 100644 index 000000000..371233233 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-conversation-mgmt-apis.adoc @@ -0,0 +1,503 @@ += APIs for managing saved conversations +:toc: true +:toclevels: 3 + +:page-title: APIs for managing saved conversations +:page-pageid: spotter-agent-conversation-mgmt-apis +:page-description: Use the Spotter 3 conversation management REST API endpoints to retrieve, update, and delete saved Spotter 3 conversations and their messages. + +ThoughtSpot's Spotter AI conversation management APIs allow you to retrieve, update, and delete saved Spotter 3 conversations and their message history. These APIs allow you to build and render custom conversation history UI, audit trails, and administrative conversation management workflows in applications using Spotter engine or embedding Spotter interface. + +== Prerequisites +To create, save, and manage conversation sessions with the Spotter 3 agent, you need `CAN_USE_SPOTTER` (**Can use Spotter**) privilege and access to the saved conversation. Only conversation owners can delete or update their saved conversations. + +== Supported API operations + +[width="100%", cols="1"] +|===== +a|`POST /api/rest/2.0/ai/agent/conversation/create` + +Allows you to save a conversation session with Spotter AI agent + +__Available on ThoughtSpot Cloud instances from 26.5.0.cl onwards.__ + +a|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` + +xref:spotter-agent-conversation-mgmt-apis.adoc#get-conversation[Retrieves the full message history of a saved Spotter 3 conversation], including ordered user prompts, agent response items, and code-execution file metadata. + +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ + +a|`GET /api/rest/2.0/ai/agent/conversations` + +xref:spotter-agent-conversation-mgmt-apis.adoc#get-conversation-list[Retrieves a paginated list of saved conversations] for the currently authenticated user. + +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ + +a|`GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` + +xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[Retrieves the full answer payload for a specific answer] within a saved conversation. + +Use this endpoint to resolve `answer_id` references returned by the get conversation messages endpoint. + +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ + +a|`POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` + +xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[Updates the metadata of a saved conversation], such as renaming its title. + +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ + +a|`DELETE /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` + +xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[Deletes a saved conversation] and all its messages. + +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ +|===== + +== Saving a conversation +To save a conversation, set the `enable_save_chat` parameter to `true` when sending a xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[conversation create `POST` request] to the `/api/rest/2.0/ai/agent/conversation/create` API endpoint. + +=== API request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "AUTO_MODE" + }, + "conversation_settings": { + "enable_save_chat": true + } +}' +---- + +If the API request is successful, ThoughtSpot returns the conversation IDs. + +[source,JSON] +---- +{ +"conversation_id":"MotUVRdguIcr", +"conversation_identifier":"MotUVRdguIcr" +} +---- + +Note these IDs. + +[#get-conversation] +== Get conversation messages +To retrieve a saved conversation, send a `GET` request to the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/messages` API endpoint with the conversation ID in the API request URL. Use this endpoint to render a persisted conversation in a UI, build an audit trail, or post-process a completed conversation. + +[NOTE] +==== +The full answer payload for each turn is not embedded in the response. To retrieve it, call the +xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer details] endpoint with +the `answer_id` returned in each `answer`-type response item. +==== + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/MotUVRdguIcr/messages' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ +---- + +=== Response body +A successful request returns an HTTP `200` response with top-level fields that include ordered conversation turns (user prompts and agent response items) and sanitized metadata for any files generated by the code-execution tool. + +When the agent conversation is initiated from a Liveboard, ThoughtSpot automatically seeds the conversation with the existing Liveboard visualization as the first response turn, without any user query. In the API response, this seeded turn appears as the first item in the `messages` array with `user_prompt` set to `null` and `message_id` set to the internal root node identifier of the conversation. All subsequent turns contain a populated `user_prompt`. When rendering conversation history, always check whether `user_prompt` is `null` before attempting to display a user query. + +=== API response +A successful request returns an HTTP `200` response with the following top-level fields. The response includes ordered conversation turns (user prompts and agent response items) and sanitized metadata for any files generated by the code-execution tool. + +When the agent conversation is initiated from a Liveboard, ThoughtSpot automatically seeds the conversation with the existing Liveboard visualization as the first response turn, without any user query. In the API response, this seeded turn appears as the first item in the `messages` array with `user_prompt` set to `null` and `message_id` set to the internal root node identifier of the conversation. All subsequent turns contain a populated `user_prompt`. When rendering conversation history, always check whether `user_prompt` is `null` before attempting to display a user query. + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`messages`|An ordered array of conversation turns, oldest to newest. +Returns an empty array when the conversation has no messages. +|`code_execution_files`|`CodeExecutionFileMetadata[]`. An array of sanitized metadata for all files generated by the code-execution tool across the entire conversation. Returns an empty array when no such files exist. +|===== + +==== ConversationMessage + +Each item in `messages` represents one conversational turn. + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`message_id`|__String__. Message ID. For Liveboard-initiated first turns, this ID is the root node identifier. +|`timestamp_in_millis`| Unix epoch timestamp for the turn, in milliseconds. +|`user_prompt`|`UserPrompt[]`. The user-authored prompt that started the turn, including the message text and any attachments. +|`response_items`|An array of agent response items produced for this turn. Returns an empty array for turns that are still in progress, which allows the UI to render the user message immediately while the agent is still processing. + +|===== + +==== UserPrompt + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`message`|`UserMessage`. The user-authored text query that started the turn. +|`attachments`|`UserAttachmentItem[]`. Files or connector resources attached to the user message. Returns an empty array when there are no attachments. + +|===== + +==== UserMessage + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`message_id`|__String__. Unique identifier of the user message. +|`content`|__String__. Text body of the user query. +|===== + +==== UserAttachmentItem + +Is distinguished by the `type` field. Valid values are `file` and `resource`. Only the fields for the indicated variant are populated. + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`type`|__String__. Attachment type. Valid values: `file`, `resource`. +|`file_id`|__String__. Unique identifier of the attached file. Matches a `file_id` in `code_execution_files`. +|`resource_identifier`|__String__. Identifier of the attached connector resource. +|===== + +==== ConversationResponseItem +Each agent response item carries a `type` distinguisher. The following types are supported. + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`type` a|__String__. Response item variant distinguisher. Supported values include: + +* `answer`: a Spotter-generated analytical answer. Carries an `answer_id` field. Pass this value as `answer_identifier` to the xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer details] endpoint to retrieve the full answer payload. +* `text`: a free-text response from the agent. +* `notification`: an agent-generated notification, such as a conversation title suggestion. +|`answer_id` a|__String__. Unique identifier of the answer. Use this to call the load answer details endpoint. +|`content`|__String__. Text content of the response. +|===== + +==== CodeExecutionFileMetadata +Sanitized metadata for a file generated by the code-execution tool. + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`file_id`|__String__. Unique identifier of the code-execution-generated file. Stable across conversation turns. Use this to match attachment references in `UserAttachmentItem`. +|`display_name`|__String__. Human-readable file name. +|`file_type`|__String__. File type hint. Either a MIME type string (for example, `text/csv`) or a file extension (for example, `csv`). +|`created_time_in_millis`|Unix epoch timestamp when the file was created, in milliseconds. +|`expired`|__Boolean__. Set to `true` when the file is no longer downloadable because its storage has expired or been evicted. +|===== + +==== Response example + +[source,JSON] +---- +{ + "messages": [ + { + "message_id": "node_u_01", + "timestamp_in_millis": 1744000000000, + "user_prompt": { + "message": { + "message_id": "msg_u_01", + "content": "Show me revenue by region as a chart." + }, + "attachments": [] + }, + "response_items": [ + { + "type": "tool_call", + "tool_call_id": "toolu_01ABC", + "tool_name": "search_datasets", + "step_title": "Searching datasets", + "arguments": { "query": "revenue" }, + "timestamp_in_millis": 1744000001000, + "is_thinking": false + }, + { + "type": "answer", + "answer_id": "ans_01XYZ", + "tool_call_id": "toolu_02DEF", + "tool_name": "fetch_and_visualize", + "step_title": "Visualising", + "timestamp_in_millis": 1744000004000, + "is_thinking": false + }, + { + "type": "text", + "content": "Revenue is highest in APAC.", + "content_type": "TEXT_MARKDOWN", + "timestamp_in_millis": 1744000005000, + "is_thinking": false, + "step_title": null, + "file_reference": { + "file_id": "revenue_by_region.csv", + "display_name": "revenue_by_region.csv", + "created_time_in_millis": 1744027200000 + } + } + ] + } + ], + "code_execution_files": [ + { + "file_id": "revenue_by_region.csv", + "display_name": "revenue_by_region.csv", + "file_type": "csv", + "created_time_in_millis": 1744027200000, + "expired": false + } + ] +} +---- + +[#get-conversation-list] +== Get conversation list + +The `GET /api/rest/2.0/ai/agent/conversations` endpoint retrieves a paginated list of saved conversations for the currently authenticated user. Only conversations created with `enable_save_chat: true` are returned in the API response. + +=== Request parameters + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Query parameter|Description +|`limit` a|__Number__. Maximum number of conversations to return per page. Use together with `offset` for pagination. +|`offset`|__Number__. Number of conversations to skip before returning results. Defaults to `0`. +|`skip_empty`|__Boolean__. When set to `true`, conversations with no messages are excluded from the results. Pass `skip_empty=false` to include empty conversations, for example, when listing conversations immediately after creation. +|===== + +=== API request + +[source,cURL] +---- +curl -X GET -G \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + -d 'limit=30' \ + -d 'offset=0' \ + -d 'skip_empty=true' +---- + +=== API response + +If the API request is successful, ThoughtSpot returns a response body. The API response does not include a `total_count` field. Use `has_more` to drive pagination controls. + +=== Response body + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`conversations`|`AgentConversationList[]`. Array of saved conversation summary objects for the current user. +|`has_more`|__Boolean__. Set to `true` when additional conversations exist beyond the current page. Set to `false` when the current page is the last. Use `offset` to fetch the next page. +|===== + +==== AgentConversationList + +Each item in `conversations` represents a saved conversation. + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`conversation_identifier`|__String__. Unique identifier of the conversation. Use this value as input in your API requests to the xref:spotter-agent-apis.adoc#_send_queries_to_a_conversation_session[send message], xref:spotter-agent-conversation-mgmt-apis.adoc#update-conversation[update conversation], xref:spotter-agent-conversation-mgmt-apis.adoc#delete-conversation[delete conversation], xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop response], and xref:spotter-agent-conversation-mgmt-apis.adoc#load-answer[load answer] endpoints. +|`conversation_title` a|__String__. Display name of the conversation. +|`created_at`|__String__. Timestamp of when the conversation was created. +|`updated_at`|__String__. Timestamp of when the conversation was last updated. +|`data_source_identifiers` a|__Array of strings__. Unique identifiers of the data sources associated with the conversation. +|`data_source_names` a|`DataSourceEntry[]`. Display names and identifiers for the data sources associated with the conversation. +|===== + +==== DataSourceEntry + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Field|Description +|`id`|__String__. Unique identifier of the data source. +|`name`|__String__. Display name of the data source. +|===== + +=== Pagination + +Use `limit` and `offset` together to page through large result sets. The response does not include a `total_count` field. Use `has_more` to determine whether additional pages exist. + +---- +GET /api/rest/2.0/ai/agent/conversations?limit=20&offset=0 (first page) +GET /api/rest/2.0/ai/agent/conversations?limit=20&offset=20 (second page) +---- + +Continue incrementing `offset` by `limit` until `has_more` returns `false`. + +==== API response example + +[source,JSON] +---- +{ + "conversations": [ + { + "conversation_identifier": "abc123", + "conversation_title": "Sales by Region Q1", + "created_at": "2026-03-01T10:00:00Z", + "updated_at": "2026-03-05T14:23:00Z", + "data_source_identifiers": ["ds-001"], + "data_source_names": [{ "id": "ds-001", "name": "Retail Sales" }] + } + ], + "has_more": false +} +---- + +[#load-answer] +== Load answer details +To retrieve the full answer payload for a specific analytical answer within a saved conversation, send a `GET` request to the `GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/answers/{answer_identifier}/details` endpoint with the conversation ID and answer ID in the request URL. + +=== Call sequence + +The following sequence is required to resolve a full answer from a saved conversation: + +. Call xref:spotter-agent-conversation-mgmt-apis.adoc#get-conversation-list[get conversation list] to retrieve saved conversations and obtain a `conversation_identifier`. +. Call xref:spotter-agent-conversation-mgmt-apis.adoc#get-conversation[get conversation messages] with the `conversation_identifier`. Locate `response_items` entries with `type: answer` and note the `answer_id` field on each. +. Call this endpoint with the `conversation_identifier` and the `answer_id` as `answer_identifier` to retrieve the full answer payload. +. Use the `tokens` array in the response to reconstruct or render the answer in your application. + +=== Request parameters +[width="100%", cols="2,4"] +[options="header"] +|===== +|Parameter|Description +|`conversation_identifier`|__String__. Path parameter. Unique identifier of the conversation. +|`answer_identifier`|__String__. Path parameter. The `answer_id` value from a `response_item` of `type: answer` in the get conversation messages response. You cannot pass arbitrary IDs to this endpoint. + +|===== + +=== API request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/0iwTDJU-tlkm/answers/5MS5xieDhefP/details' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ +---- + +=== Response body +If the API request is successful, ThoughtSpot returns a response body with the answer details. + +[width="100%", cols="2,2,4"] +[options="header"] +|===== + +|Field|Type|Description +|`answer` a|Full answer payload for the requested answer. Includes the following attributes: + +* `title`: __String__. Display title of the answer. +* `description`: __String__. Description of the answer. +* `session_identifier`: __String__. Unique identifier of the session in which the answer was generated. +* `generation_number`: __Integer__. Generation number of the answer. Incremented each time the answer is updated within the same session. +* `tokens`: __String[]__. Ordered list of TML token strings that make up the answer query. Use these to reconstruct or render the answer in the ThoughtSpot embed SDK or a custom UI. +* `visualization_type`: __String__. Visualization type selected for the answer. Valid values are: +** `Chart` / `CHART` +** `Table` / `TABLE` +** `Undefined` / `UNDEFINED`. Indicates that Spotter has not yet determined an appropriate visualization, or the answer type does not map to a chart or table. +* `formulas`: __Array of strings__. List of formula expressions used in the answer. +* `parameters`: __Array of strings__. List of parameter names applied in the answer. +* `sub_queries`: __Array of objects__. List of sub-queries used when the answer involves decomposed query processing. +* `ac_state`: Internal answer-context state used for session continuity. Includes the following attributes: +** `transaction_identifier`: __String__. Unique identifier of the answer transaction. +** `generation_number`: __Integer__. Generation number of the transaction. + +|===== + +=== Example response + +[source,JSON] +---- +{ + "answer":{ + "title":"total sales by state where item type is jackets", + "description":null, + "session_identifier":"5216568f-f808-4385-ad0a-3a40bb9b5dcb", + "generation_number":2, + "tokens":[ + "[sales] [state] [item type] = 'jackets'" + ], + "visualization_type":"UNDEFINED", + "formulas":[ + ], + "parameters":[ + ], + "sub_queries":[ + ], + "ac_state":{ + "transaction_identifier":"00ccc6e0-1117-4713-8798-d6201d3a5a40", + "generation_number":1 + } + } +} +---- + +[#update-conversation] +== Update a conversation +To update the metadata of an existing conversation, send a `POST` request to the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/update` API endpoint with the conversation ID in the request URL. Currently, the API endpoint allows you to rename the conversation title only. + +=== Request parameters + +[width="100%", cols="2,4"] +[options="header"] +|===== +|Parameter|Description +|`conversation_identifier`|__String__. Path parameter. Unique identifier of the conversation to update. +|`title`|__String__. Form parameter to include in the request body. To rename the display title of the conversation, specify the title string. +|===== + +==== API request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/0iwTDJU-tlkm/update' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "title": "Revenue Analysis — Q1 2026" +}' +---- + +=== API response +A successful request returns the 204 response. The response body contains the updated conversation object reflecting the applied changes. + +[#delete-conversation] +== Delete a conversation +To delete a saved conversation and all its associated messages, send a `DELETE` request to the `/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/delete` API endpoint with the conversation ID as a path parameter. + +[IMPORTANT] +==== +* ThoughtSpot allows only the conversation owners to delete a conversation. +* Deleted conversations and all their messages cannot be recovered. Therefore, we recommend exercising caution when deleting a saved conversation. +==== + +=== API request + +[source,cURL] +---- +curl -X DELETE \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/MotUVRdguIcr/delete' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ +---- + +=== API response +A successful request returns an HTTP `204 No Content` response with an empty body. After a successful deletion, subsequent calls to the get conversation messages or load answer endpoints for the same `conversation_identifier` result in the `404 Not Found` error. + +== Additional resources + +* See also xref:spotter-agent-apis.adoc[Spotter Agent APIs] +* To try out the request and response workflow, use the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fai%2Fget-conversation[REST API Playground] diff --git a/modules/ROOT/pages/spotter-agent-instructions.adoc b/modules/ROOT/pages/spotter-agent-instructions.adoc index 6b5deff35..4a6f9008d 100644 --- a/modules/ROOT/pages/spotter-agent-instructions.adoc +++ b/modules/ROOT/pages/spotter-agent-instructions.adoc @@ -1,39 +1,36 @@ -= Spotter AI Agent instructions API += Spotter AI agent instructions APIs :toc: true :toclevels: 2 -:page-title: Spotter Agent instructions APIs +:page-title: Spotter AI agent instructions APIs :page-pageid: spotter-agent-instructions :page-description: Use the Spotter agent instructions APIs to set and retrieve persistent behavioral guidance for the Spotter agent in a conversation session. -Administrators and developers can configure persistent behavioral instructions for the Spotter agent using the agent instructions APIs. These instructions guide how Spotter responds within a conversation context. For example, to focus on specific business domains, enforce response formats, or apply analytical constraints. +Administrators and developers can configure persistent behavioral instructions for the Spotter agent using agent instructions APIs. These instructions guide how Spotter responds within a conversation context. For example, to focus on specific business domains, enforce response formats, or apply analytical constraints. Unlike xref:spotter-nl-instructions.adoc[data model instructions], which operate at the data model level, agent instructions operate at the agent level and do not require a data source identifier. -[NOTE] -==== -To use the agent instructions APIs, you need `CAN_USE_SPOTTER` privilege and valid authentication. -==== - == Supported API endpoints [width="100%", cols="1"] |===== a|`PUT /api/rest/2.0/ai/agent/instructions/set` [.version-badge.new]#New# + xref:spotter-agent-instructions.adoc#_set_agent_instructions[Sets behavioral instructions] for the Spotter agent. + -__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ a|`GET /api/rest/2.0/ai/agent/instructions/get` [.version-badge.new]#New# + xref:spotter-agent-instructions.adoc#_get_agent_instructions[Retrieves the behavioral instructions] currently configured for the Spotter agent. + -__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ +__Available on ThoughtSpot Cloud instances from 26.7.0.cl onwards.__ |===== == Set agent instructions -The `PUT /api/rest/2.0/ai/agent/instructions/set` API endpoint sets behavioral instructions for the Spotter agent. -Use this endpoint to define persistent guidance that Spotter applies when responding to queries. +The `PUT /api/rest/2.0/ai/agent/instructions/set` API endpoint sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries. Instructions persist until you overwrite or remove them by sending a new `PUT` request. +=== Prerequisites +To configure agent instructions, you need administration or `CAN_MANAGE_SPOTTER` (**Can manage Spotter**) privilege. + === Request parameters [width="100%", cols="2,4"] @@ -90,6 +87,9 @@ If the request fails, ThoughtSpot returns an error code and message. For example The `GET /api/rest/2.0/ai/agent/instructions/get` API endpoint retrieves the behavioral instructions currently configured for the Spotter agent. +=== Prerequisites +To retrieve agent instructions via REST API, you need administration privileges. + === Request parameters This endpoint does not require a request body or query parameters. diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 88aab5c4a..a7ebfc290 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -25,6 +25,7 @@ For information about supported API operations, see the following pages: * xref:spotter-classic-apis.adoc[APIs for Spotter classic workflow] * xref:spotter-agent-apis.adoc[APIs for Spotter agent workflows] +* xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for Spotter conversation management] * xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and NL instructions] * xref:spotter-agent-instructions.adoc[APIs for Spotter agent instructions] @@ -48,10 +49,9 @@ The following rate limits apply to Spotter agent APIs per user: |API endpoint| Rate Limit (per user, per minute) |`/api/rest/2.0/ai/agent/conversation/create` | 10 |`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send`| 30 -|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` | 30 +|`/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/stream` | 30 |`/api/rest/2.0/ai/agent/{conversation_identifier}/converse` [.version-badge.deprecated]#Deprecated# | 30 |`/api/rest/2.0/ai/agent/converse/sse` [.version-badge.deprecated]#Deprecated# | 30 -|| |===== If you are integrating these APIs in your environment, consider implementing a retry logic to handle the rate limit errors. diff --git a/modules/ROOT/pages/spotter-classic-apis.adoc b/modules/ROOT/pages/spotter-classic-apis.adoc index 0b93fc5f2..2d8bb534a 100644 --- a/modules/ROOT/pages/spotter-classic-apis.adoc +++ b/modules/ROOT/pages/spotter-classic-apis.adoc @@ -6,7 +6,7 @@ :page-pageid: spotter-apis-classic :page-description: You can use Spotter REST APIs to receive Answers for your analytical queries sent through the conversational experience with ThoughtSpot. -This document describes how to use AI APIs with Spotter Classic to query and explore data through conversational interactions. +This page describes how to use AI APIs with Spotter Classic to query and explore data through conversational interactions. For information about APIs for agent interactions, see xref:spotter-agent-apis.adoc[Spotter Agent APIs]. @@ -102,7 +102,7 @@ If the API request is successful, a conversation identifier is created. Note the ---- == Send a query to a conversation session -To send a question to an ongoing conversation session or ask follow-up questions, send a `POST` request body with conversation ID and query text to the `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API endpoint. +To send a question to an ongoing conversation session or ask follow-up questions, send a `POST` request to the `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API endpoint with the conversation ID and query text in the request body. This API endpoint supports only the conversation sessions created using the `POST /api/rest/2.0/ai/conversation/create` API call. @@ -112,7 +112,7 @@ This API endpoint supports only the conversation sessions created using the `POS [options='header'] |===== |Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the GUID of the conversation received from the xref:spotter-apis.adoc#_create_a_conversation_session[create conversation API call]. +|`conversation_identifier`|Path parameter|__String__. Required. Specify the GUID of the conversation received from the xref:spotter-classic-apis.adoc#_create_a_conversation_session[create conversation API call]. |`metadata_identifier`|Form parameter|_String_. Required. Specify the GUID of the data source object, for example, Model. The metadata object specified in the API request will be used as a data source for the follow-up conversation. |`message`|Form parameter|_String_. Required. Specify a natural language query string. For example, `Sales data for Jackets`. |===== @@ -179,7 +179,7 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "message": "which city has the better sales of jackets here?" + "message": "which city has the best sales of jackets here?" }' ---- diff --git a/modules/ROOT/pages/spotter-nl-instructions.adoc b/modules/ROOT/pages/spotter-nl-instructions.adoc index 829b5b244..8062ca369 100644 --- a/modules/ROOT/pages/spotter-nl-instructions.adoc +++ b/modules/ROOT/pages/spotter-nl-instructions.adoc @@ -1,4 +1,4 @@ -= Data model instructions API += Data model instructions APIs :toc: true :toclevels: 2 @@ -15,7 +15,7 @@ To set instructions for a Model, send a `POST` request to the `/api/rest/2.0/ai/ [NOTE] ==== -To set NL instructions, you need `CAN_USE_SPOTTER` (**Can use Spotter**) privilege and either edit access or `SPOTTER_COACHING_PRIVILEGE` permission on the data model. Ensure that your bearer token is scoped to the Org where the data model resides. +To set NL instructions, you need `CAN_MANAGE_SPOTTER` (**Can manage Spotter**) privilege and either edit access or `SPOTTER_COACHING_PRIVILEGE` permission on the data model. Ensure that your bearer token is scoped to the Org where the data model resides. ==== === Request parameters diff --git a/modules/ROOT/pages/style-customization.adoc b/modules/ROOT/pages/style-customization.adoc index 0816f9ac1..6fd53a71e 100644 --- a/modules/ROOT/pages/style-customization.adoc +++ b/modules/ROOT/pages/style-customization.adoc @@ -20,12 +20,15 @@ You can customize key UI components, such as your application logo, favicon, fon Custom CSS changes take precedence and override the style customization settings applied via UI. ==== +Style customization through the REST APIs:: +You can manage style customization settings programmatically by using the ThoughtSpot REST APIs. +These endpoints expose all branding and theming controls available in the ThoughtSpot UI. For more information, see xref:xref:customize-style-api.adoc[Customize UI layout and styles through REST APIs] + Advanced style customization with custom CSS:: Custom CSS allows developers to override the default styles and UI element specifications in their deployments. Custom CSS provides granular control over the UI appearance and allows you to modify design elements such as buttons, labels, text styles, and typography. This feature is available only with the ThoughtSpot Embedded Edition license. + To customize themes and variables in the CSS file, developers must know the basics of HTML and CSS framework and how to build custom themes. For more information, see xref:css-customization.adoc[Advanced customization with custom CSS]. - A xref:style-customization_tutorial.adoc[hands-on tutorial] is also available to learn how to test style customization capabilities using Visual Embed Playground. == Scope of customization diff --git a/modules/ROOT/pages/webhooks-api.adoc b/modules/ROOT/pages/webhooks-api.adoc new file mode 100644 index 000000000..ab781b24e --- /dev/null +++ b/modules/ROOT/pages/webhooks-api.adoc @@ -0,0 +1,482 @@ += 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#_retrieving_webhook_details[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 cluster level. +==== + +=== 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 after creation, or `DISABLED` to create it in a deactivated state. +[NOTE] +==== +When the status parameter is not specified in the API request, the API response returns "status": null, indicating that the status was not explicitly set. Despite the null value, the webhook is enabled by default. To create a webhook in a disabled state, set the status parameter to `DISABLED` in the API request. +==== + +| `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 the 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" + } +] +---- +|===== + +=== 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 ThoughtSpot instances with S3 storage, the API endpoint returns a JSON array with the platform AWS account ID, IAM trust policy template, and storage setup instructions. +* For GCP-hosted ThoughtSpot instances with S3 storage, the API endpoint returns a JSON array with the GCP service account ID, OIDC provider URL, IAM trust policy template, and storage setup instructions. +* For GCP-hosted ThoughtSpot instances with GCS storage, the API endpoint returns 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 +The following response is 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", + "aws_account_id":null, + "gcp_service_account_id":null, + "oidc_provider":null, + "trust_policy_template":null, + "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" + ] + } + } +] +---- + +== Retrieving webhook details +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 a 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 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": "Primary", + "webhook_identifier": "27997a8a-cd33-485d-a039-b40b71d191a8", + "event_type": "LIVEBOARD_SCHEDULE", + "status": "ENABLED" +}' +---- + +=== API response +If the webhook ID is valid, the API returns the following response: + +[source,JSON] +---- +{ + "webhooks":[ + { + "id":"3791ad80-70e8-4222-bf11-fb8a5f1b5bf4", + "name":"webhook_s3", + "description":null, + "org":{ + "id":"2100019165", + "name":"docstest" + }, + "url":"https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", + "url_params":null, + "events":[ + "LIVEBOARD_SCHEDULE" + ], + "authentication":null, + "signature_verification":null, + "additional_headers":null, + "creation_time_in_millis":1772127694740, + "modification_time_in_millis":1772127859128, + "created_by":{ + "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name":"userA@thoughtspot.com" + }, + "last_modified_by":{ + "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name":"userA@thoughtspot.com" + }, + "storage_destination":{ + "storage_type":"AWS_S3", + "storage_config":{ + "aws_s3_config":{ + "bucket_name":"my-company-data-exports", + "region":"us-east-1", + "role_arn":"arn:aws:iam::999888777666:role/thoughtspot-s3-upload", + "external_id":"ts-webhook-x7k9m2p4q1", + "path_prefix":"thoughtspot/" + } + } + } + } + ], + "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 the webhook 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 a 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-comm-channel.adoc b/modules/ROOT/pages/webhooks-comm-channel.adoc index ad7ce839c..736c721b1 100644 --- a/modules/ROOT/pages/webhooks-comm-channel.adoc +++ b/modules/ROOT/pages/webhooks-comm-channel.adoc @@ -14,17 +14,19 @@ This document describes the steps to xref:webhooks-comm-channel.adoc#_configure_ [NOTE] ==== -* REST APIs support webhook channel configuration for `LIVEBOARD_SCHEDULE` events only. -* You can configure only one webhook per Org for the Liveboard schedule event. +REST APIs support webhook channel configuration for `LIVEBOARD_SCHEDULE` events only. ==== -== Before you begin +== Before you begin Check your application environment for the following prerequisites: -* Ensure that you have access to a ThoughtSpot instance with the required permissions to set communication channel preferences, create and manage webhooks, and schedule Liveboard jobs. +* Ensure that you have access to a ThoughtSpot instance with the required permissions to set communication channel preferences, create and manage webhooks, and schedule Liveboard jobs. + +If your instance has Role-based Access Control (RBAC) enabled, you need the following privilege: +** `APPLICATION_ADMINISTRATION` (*Can manage application settings*) to create and view communication channel preferences. * Ensure that the REST APIs for setting communication channel preferences and configuring webhooks are enabled on your instance. If the APIs are not available on your instance, contact ThoughtSpot Support. + == Configure communication channel preferences To create a webhook channel, configure channel preferences, and retrieve the channel settings, use the following REST APIs: @@ -269,7 +271,7 @@ The following example shows the preferences returned for a specific Org: ---- == Validate communication channel configuration -To ensure that a communication channel configuration is properly configured and can receive events, use the `/api/rest/2.0/system/communication-channels/validate` API endpoint and validate the communication channel configuration. +To ensure that a communication channel is properly configured and can receive events, use the `/api/rest/2.0/system/communication-channels/validate` API endpoint to validate the communication channel configuration. === Request parameters @@ -300,9 +302,6 @@ curl -X POST \ ---- === Example response - -If the validation is successful, the API returns a response indicating the webhook channel validation state. - The following response shows validation status for a webhook channel: [source,JSON] @@ -326,7 +325,7 @@ The following response shows validation status for a webhook channel: } ---- -The following response shows the validation success and failure errors for a webhook channel with AWS s3 storage configuration: +The following response shows the validation success and failure errors for a webhook channel with AWS S3 storage configuration: [source,JSON] ---- @@ -361,8 +360,7 @@ The following response shows the validation success and failure errors for a web ---- == Monitor webhook delivery and job status -To monitor job status for communication channels such as webhook, use the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. - +To monitor job status for communication channels such as webhooks, use the `/api/rest/2.0/jobs/history/communication-channels/search` API endpoint. === Request parameters In the API request, you must provide channel details such as channel type, ID, and event type, or specify the job ID. @@ -373,11 +371,11 @@ In the API request, you must provide channel details such as channel type, ID, a |===== |Parameter|Description -|`channel_type` a|__String__. Type of communication channel to validate. Specify `WEBHOOK` for webhook channels. -|`job_ids` |__Array of strings__. One or more IDs of the job. To get the ID for a given webhook channel, check the API response from the `/api/rest/2.0/system/communication-channels/validate` endpoint. +| `channel_type` a|__String__. Type of communication channel to validate. Specify `WEBHOOK` for webhook channels. +| `job_ids` |__Array of strings__. One or more IDs of the job. To get the ID for a given webhook channel, check the API response from the `/api/rest/2.0/system/communication-channels/validate` endpoint. -Required parameter if no channel identifier and event ID are specified in the API request. -|`channel_identifiers`|__String__. IDs or names of the communication channel. Required if no job ID is specified. +Required if neither a channel identifier nor an event ID is specified in the API request. +| `channel_identifiers`|__Array of strings__. IDs or names of the communication channel. Required if no job ID is specified. For webhook channels, specify the webhook ID. You can retrieve the webhook IDs from the `/api/rest/2.0/webhooks/search` API endpoint via an API request. |`channel_status` a|__String__. Status of the channel or the job. Specify one of the following values: @@ -390,8 +388,7 @@ Gets a list of jobs that were delivered successfully. * `FAILED` + Gets a list of failed job deliveries. - -|`events` + +| `events` + __Optional__ a| Allows filtering API response by event type and ID. * `type` + @@ -399,12 +396,13 @@ Event type for which the webhook delivery is triggered. Default is `LIVEBOARD_SC * `identifier` + ID of the event. -|`start_epoch_time_in_millis` |__Decimal__. Allows filtering API response by records that were created on or after the specified epoch milliseconds. +| `start_epoch_time_in_millis` |__Decimal__. Allows filtering API response by records that were created on or after the specified epoch milliseconds. +| `end_epoch_time_in_millis` |__Decimal__. Filters the API response by records created before the specified timestamp (in epoch milliseconds). |===== === Example request -The following example shows the sample request with job ID. +The following example shows a sample request with a job ID. [source,cURL] ---- @@ -501,3 +499,4 @@ If the webhook channel has the S3 storage configured, the API returns the job st * xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an external application]. * xref:webhooks-s3-storage.adoc[Deliver Liveboard reports to AWS S3 storage bucket]. +* xref:webhooks-gcs-storage.adoc[GCS storage integration for webhook delivery]. diff --git a/modules/ROOT/pages/webhooks-gcs-storage.adoc b/modules/ROOT/pages/webhooks-gcs-storage.adoc new file mode 100644 index 000000000..82482f85a --- /dev/null +++ b/modules/ROOT/pages/webhooks-gcs-storage.adoc @@ -0,0 +1,284 @@ += GCS storage configuration for webhooks +: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. + +[beta betaBackground]^Beta^ + +If your ThoughtSpot instance is hosted on Google Cloud Platform (GCP), you can configure a webhook to deliver payloads and file attachments from a scheduled Liveboard event to your Google Cloud Storage (GCS) bucket. + +[NOTE] +==== +GCS storage integration for webhooks is available for GCP-hosted ThoughtSpot instances only. This feature is in Beta. To enable this feature on your instance, contact ThoughtSpot Support. +==== + + +[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 only on ThoughtSpot Cloud instances running 26.7.0.cl and later. +* In the current version, the new experience allows creating and managing webhooks for Liveboard Schedule events only. +==== + +== Before you begin +Before configuring GCS storage for webhooks: + +* Ensure that webhook support for GCS destination is enabled on your cluster. If the feature is not available on your cluster, contact ThoughtSpot Support to enable it. +* For GCS storage destination configuration, you'll need the platform GCP service account email and the IAM role to grant for service account impersonation. To xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[retrieve these details], send a `GET` request to the `/api/rest/2.0/webhooks/storage-config` API endpoint. +* Ensure that you have a GCS bucket in the same GCP project or a project that allows cross-project IAM bindings. +* To configure a webhook in ThoughtSpot, you'll need a user account with administration privileges or the *Can Manage Webhooks* role privilege. Ensure that you have the required privileges to set up webhook connection and monitor delivery status. +* Ensure that a xref:webhooks-comm-channel.adoc[webhook communication channel] is configured in your Org or at the cluster level on your instance. + +== Grant service account impersonation permissions +In the GCP Console or using the `gcloud` CLI, grant the ThoughtSpot service account the `roles/iam.serviceAccountTokenCreator` role on your GCS-enabled service account: + +[source,bash] +---- +gcloud iam service-accounts add-iam-policy-binding \ + --member="serviceAccount:" \ + --role="roles/iam.serviceAccountTokenCreator" +---- + +[NOTE] +==== +This grants ThoughtSpot's service account the ability to create short-lived credentials for your service account, enabling it to write to your GCS bucket on your behalf without requiring long-lived credentials to be shared. +==== + +== Configuring a webhook with GCS storage +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. + +You can create a webhook with a cloud storage destination using the **Webhooks** page in the UI or through the create webhook REST API. + +=== Using REST API +To configure the GCS storage properties in ThoughtSpot, the service account email and GCS bucket name are required. + +To create a webhook, send a `POST` request to the `/api/rest/2.0/webhooks/create` API endpoint. + +[NOTE] +==== +ThoughtSpot allows only one webhook for the Liveboard Schedule event type per Org. +==== + +==== 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 listening endpoint URL where the webhook payload will be sent. The payload will include metadata and a URL referencing the file stored in GCS. +| `url_params` a|__Optional__. 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`. When this event is emitted, a webhook payload is initiated to send data to the configured GCS storage destination. +| `storage_destination` a| Configuration for storage destination. Specify the following parameters: +* `storage_type` + +__String__. Type of storage destination. Specify `GCP_GCS`. + + +* `storage_config` + +Storage configuration parameters. For `gcp_gcs_config`, specify the following parameters: + +* `bucket_name` + +__String__. Name of the GCS bucket where webhook payloads will be stored. For example, `ts-webhook-exports`. +* `service_account_email` + +__String__. Email of the GCP service account to impersonate for bucket access. For example, `my-sa@my-project.iam.gserviceaccount.com`. The platform's service account must be granted `roles/iam.serviceAccountTokenCreator`. +* `path_prefix` __Optional__ + +__String__. Path prefix for organizing objects within the bucket. For example, `thoughtspot/`. + +|`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. You can use this parameter to pass arbitrary headers with custom metadata in key-value pairs, as required by the webhook receiver endpoint. When configured, ThoughtSpot sends these headers in addition to the authentication headers and standard HTTP headers such as `Content-Type`, `User-Agent`. + +[source,JSON] +---- +"additional_headers": [ + { + "key":"X-Custom-Header", + "value":"custom_value" + } +] +---- +|==== + +==== API 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-gcs", + "url": "https://webhook-destination-site.com", + "events": [ + "LIVEBOARD_SCHEDULE" + ], + "description": "Webhook delivery to GCS bucket", + "storage_destination": { + "storage_type": "GCP_GCS", + "storage_config": { + "gcp_gcs_config": { + "bucket_name": "my-webhook-files", + "service_account_email": "my-sa@my-project.iam.gserviceaccount.com", + "path_prefix": "thoughtspot/" + } + } + }, + "status": "ENABLED" +}' +---- + +==== API response +The API response includes both `aws_s3_config` and `gcp_gcs_config` fields within `storage_config`. When GCS is configured, `aws_s3_config` appears as `null`. + +[source,JSON] +---- +{ + "id":"18835251-668b-4851-b5c7-35358549f3f4", + "name":"webhook-gcs", + "description":"Webhook for GCS delivery", + "org":{ + "id":"0", + "name":"test-org" + }, + "url":"https://webhook-destination-site.com", + "url_params":null, + "events":[ + "LIVEBOARD_SCHEDULE" + ], + "authentication":null, + "signature_verification":null, + "additional_headers":null, + "creation_time_in_millis":1782867500837, + "modification_time_in_millis":1782867500837, + "created_by":{ + "id":"59481331-ee53-42be-a548-bd87be6ddd4a", + "name":"tsadmin" + }, + "last_modified_by":null, + "storage_destination":{ + "storage_type":"GCP_GCS", + "storage_config":{ + "aws_s3_config":null, + "gcp_gcs_config":{ + "bucket_name":"my-webhook-files", + "service_account_email":"my-sa@my-project.iam.gserviceaccount.com", + "path_prefix":"thoughtspot/" + } + } + }, + "status":"ENABLED" +} +---- + +=== Using Webhooks page in UI +If the new Webhooks page is enabled on your instance, you can create a webhook via the UI. +To create a webhook with GCS 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. +. To configure storage destination, select the **File storage** checkbox and specify values for the following properties: + +* **Storage provider**: Select **Google Cloud Storage (GCS)**. +* **Bucket name**: Name of the GCS bucket. For example, `my-webhook-files`. +* **Service account email**: Email of the GCP service account to impersonate for bucket access. +* **Path prefix**: Optional. Path prefix for organizing objects within the bucket. For example, `thoughtspot/`. ++ +[.bordered] +[.widthAuto] +-- +image::./images/webhook-create-gcp.png[Webhooks for GCS storage] +-- +//. Select xref:webhooks-ux.adoc#_creating_a_webhook[the authentication method] to authorize payloads to the destination endpoint. + +. To configure xref:webhooks-ux.adoc#_creating_a_webhook_connection[advanced settings] such as signature verification, custom headers, and URL query parameters, click **Advanced settings** and configure the fields as required. +. Click *Save*. + +If the webhook is created successfully, it is added to the Webhooks list and enabled by default. + +== 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 +---- + +== Viewing webhook configuration details +To view the webhook details, use one of the following options: + +* Through the REST API: + +To retrieve webhook configuration details, use the xref:webhooks-api.adoc#_getting_a_list_of_webhooks[`/api/rest/2.0/webhooks/search` API endpoint]. +* Using the UI: + +If the **new Webhook experience** is enabled on your instance, go to the **Develop** > **Customization** > **Webhooks** page. Check the list in the xref:webhooks-ux.adoc#_webhooks_list_page[**Webhooks**] to view the details and verify if the webhook connection is activated. + +== Validating webhook channel configuration +To validate webhook configuration status, use one of the following options. + +* Using REST API: +To validate the communication channel configuration for webhook delivery, use xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[the `/api/rest/2.0/system/communication-channels/validate` API endpoint]. + +* Using the UI: + +If the new Webhook experience is enabled on your instance, go to the **Develop** > **Customization** > **Webhooks** page. The Webhooks page displays a list of webhooks configured in the current Org context. + +To validate the webhook channel configuration: +. In the **Webhooks** page, select the webhook row, and click **Send test event**. +. Verify the delivery status. + +If the validation returns errors, update the webhook configuration properties to resolve the errors. + +== Monitoring webhook delivery status +To monitor the webhook delivery and status, use one of the following options: + +* Through the REST API: + +To verify 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]. + +* Using the UI: + +If your ThoughtSpot instance has new Webhooks page enabled, use the **Webhooks** menu option on the **Develop** page to view the details of the webhook: +. Go to the **Develop** > **Customization** > **Webhooks** page. + +The **Webhooks** page displays status cards and delivery rate for the webhooks configured in the Org. +. Click the webhook from the list and verify the delivery details. For more information, see xref:webhooks-ux.adoc#_monitoring_webhook_status[Monitoring delivery status]. + +== Verifying 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. +. Verify whether the webhook payload is delivered to the correct bucket and prefix. +. Review the object content to confirm the payload matches the expected schema. +. Verify the attachments and timestamps in the logs. +. If files are not delivered to your GCS bucket, check the logs for errors. + +== Troubleshooting errors + +[cols="2,3"] +[options="header"] +|==== +| Issue | Resolution + +| Objects are not delivered to the bucket +| This error occurs in the following scenarios: + +* When service account impersonation fails +* When the GCS write operation fails due to permission errors +* Webhook connection configuration errors + +To resolve: + +* Verify that the ThoughtSpot service account is granted the `roles/iam.serviceAccountTokenCreator` role on your GCS-enabled service account. +* Verify that your service account has write access to the GCS bucket. +* Verify that the service account email in the webhook configuration matches the service account used to grant permissions. + +| `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 alert condition for the scheduled event is met. Contact ThoughtSpot Support if the issue persists. +|==== + +== Related topics +* See also: xref:webhooks.adoc[Webhooks overview], xref:webhooks-ux.adoc[Webhooks UI], and xref:webhooks-api.adoc[Webhook APIs] documentation. +* link:https://cloud.google.com/storage/docs/access-control/iam-roles[Google Cloud Storage IAM roles, window=_blank] documentation. \ No newline at end of file diff --git a/modules/ROOT/pages/webhooks-kpi-alerts.adoc b/modules/ROOT/pages/webhooks-kpi-alerts.adoc index 2df9a283b..aff4de79f 100644 --- a/modules/ROOT/pages/webhooks-kpi-alerts.adoc +++ b/modules/ROOT/pages/webhooks-kpi-alerts.adoc @@ -3,19 +3,16 @@ :page-title: Webhooks for KPI Monitor alerts :page-pageid: webhooks-kpi -:page-description: Register a Webook to send KPI monitor alerts to an external application +:page-description: Register a webhook to send KPI monitor alerts to an external application ThoughtSpot users with administrator or developer privileges can register a webhook to send Monitor alerts from a Key Performance Indicator (KPI) chart to an external application. KPI Monitor alerts notify users when a KPI metric meets a threshold condition or periodically as per the schedule configured by the user. For example, you can create an alert to be notified when a Sales KPI exceeds a threshold of 200,000, or when your weekly sales increase by 2%. By default, the email notifications are sent to the alert subscriber’s email address. With webhooks, you can trigger alerts to the REST endpoint of an external application via HTTP POST requests and customize your application workflow to present these alerts as SMS messages or Slack notifications. -//// - [NOTE] ==== -The webhooks feature is in Beta and is turned off by default. To enable this feature on your instance, contact ThoughtSpot Support. +To configure KPI alert webhooks, you need administrator or developer privileges on your ThoughtSpot instance. ==== -//// == Before you begin @@ -24,33 +21,8 @@ The webhooks feature is in Beta and is turned off by default. To enable this fea * 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. -== 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.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**. +== Configuring a webhook for KPI alerts +To configure a webhook and send KPI monitor alerts to an external application or URL, xref:webhooks-ux.adoc#webhook-configuration-and-management-legacy-experience[create a webhook in ThoughtSpot UI]. === Assign webhook to a KPI Monitor alert diff --git a/modules/ROOT/pages/webhooks-lb-schedule.adoc b/modules/ROOT/pages/webhooks-lb-schedule.adoc index 9f4a1dd44..afc39d7e2 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 += Webhook configuration for Liveboard scheduled events :toc: true :toclevels: 3 -:page-title: Webhooks for Liveboard Scheduled Jobs +:page-title: Webhook connection for Liveboard scheduled events :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,62 +17,55 @@ 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: +[#configure-webhook] +== Configuring a webhook +You can configure a webhook to deliver reports generated from Liveboard scheduled events to external applications. To create and manage webhooks, use the xref:webhooks-lb-schedule.adoc#_using_webhooks_rest_api[webhook REST API] or the xref:webhooks-lb-schedule.adoc#_through_the_webhooks_page_in_ui[**Webhooks** page (new experience) in the UI]. -* 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. - -=== Create 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. +=== Using Webhooks 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 -[width="100%" cols="1,6"] +[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 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|__Optional__. 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 header and its value. * `BASIC_AUTH` + -Authentication methods with username and password. +Username and password to authorize requests. * `BEARER_TOKEN` + -Authentication token to authenticate and authorize requests. +Authentication token to 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 +73,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 after creation, or `DISABLED` to create it in a deactivated state. |`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 +97,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] ---- @@ -129,7 +107,7 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "name": "webhook-lb-event", - "url": "https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", + "url": "https://webhook-destination-site.com", "events": [ "LIVEBOARD_SCHEDULE" ], @@ -141,243 +119,85 @@ 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"] -[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" -} ----- -|===== - -==== 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: +If webhook creation is successful, the API returns a response body with the webhook 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", + "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", + "name": "My Liveboard Webhook", + "description": "Webhook to notify external system about liveboard schedules", + "org": { + "id": "0", + "name": "Primary" + }, + "url": "https://webhook-destination-site.com", "events": [ "LIVEBOARD_SCHEDULE" - ] -}' ----- - -==== Example response - -If the API request is successful, the API returns a 204 response code indicating a successful operation. - -== 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]. - -If the connection status is successful, trigger a webhook delivery to the configured destination and xref:webhooks-payload.adoc[verify the payload]. - - -//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. - -== 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]. - -== 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": [ + ], + "authentication": { + "BEARER_TOKEN": "***" + }, + "creation_time_in_millis": 1724277430243, + "modification_time_in_millis": 1724277430243, + "additional_headers": [ + { + "key": "Custom-Header", + "value": "value1" + }, { - "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 + "key": "Custom-Header-2", + "value": "value2" } ], - "failed_webhooks": [] + "created_by": { + "id": "8e3f2a7b-9c4d-4e5f-8a1b-7c9d3e6f4a2b", + "name": "UserA" + }, + "last_modified_by": { + "id": "8e3f2a7b-9c4d-4e5f-8a1b-7c9d3e6f4a2b", + "name": "UserA" + } } ---- -== 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+++ +=== Through the Webhooks page in UI +If the new Webhooks page is enabled on your instance, you can create a webhook via the 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*: Specify the OAuth client ID, client secret, and authorization URL. +* *API Key*: Specify the header or query parameter name for the API key and its value. +* *Bearer Token*: ThoughtSpot sends a static bearer token in the `Authorization: Bearer` header. +* *Basic authentication*: Username and password to authorize delivery requests. +. 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 is created successfully, it is added to the Webhooks list and enabled by default. + +=== Test webhook connection and verify delivery +To validate the webhook channel configuration, use one of the following options: + +* Use xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[the `/api/rest/2.0/system/communication-channels/validate` API endpoint]. +* If the new Webhooks page is enabled on your instance, navigate to the **Webhooks** page, select the webhook row, and click **Send test event**. +.. Verify the delivery status. +.. If files are delivered to the configured URL endpoint, check the payload contents. For information about the webhook payload structure, see xref:webhooks-payload.adoc[Webhook payload for Liveboard events]. +.. If files are not delivered to the configured URL endpoint, check the logs for errors. \ No newline at end of file diff --git a/modules/ROOT/pages/webhooks-payload.adoc b/modules/ROOT/pages/webhooks-payload.adoc index 3aa527bec..5dbd05db6 100644 --- a/modules/ROOT/pages/webhooks-payload.adoc +++ b/modules/ROOT/pages/webhooks-payload.adoc @@ -1,15 +1,15 @@ -= Webhook payload for Liveboard events += Webhook payload for scheduled Liveboard events :toc: true :toclevels: 3 :page-title: Webhook payload for Liveboard events :page-pageid: webhooks-lb-payload -:page-description: Review the webhook payload content delivered to a target destination URL or S3 storage +:page-description: Review the webhook payload content delivered to a target destination URL, S3 storage, or GCS storage The payload contains metadata about the event, the source, the actor, the target object, and event-specific data. -== Payload example for S3 storage destination -When the schedule is configured with an S3 destination, ThoughtSpot delivers the exported file directly to S3, and the webhook payload only contains metadata JSON and the S3 object URL location. The JSON metadata includes the event type, object type, schedule name, recipients, and format. +== Payload contents for storage destinations +When the schedule is configured with a storage destination, ThoughtSpot delivers the exported file directly to the S3 or GCS bucket, and the webhook payload only contains metadata JSON and the storage object URL. The JSON metadata includes the event type, object type, schedule name, recipients, and format. The supported file formats for webhook delivery are PDF, CSV, and XLSX. @@ -71,7 +71,7 @@ The supported file formats for webhook delivery are PDF, CSV, and XLSX. } ---- -The following content in the file attachment indicates successful delivery to the S3 storage destination: +The following content in the file attachment indicates successful delivery to the storage destination: [source,JSON] ---- @@ -101,7 +101,7 @@ The following content in the file attachment indicates successful delivery to th } ---- -The following examples show a failed delivery of file attachments due to access denied errors: +The following examples show partial or complete delivery failure of file attachments due to access denied errors: [source,JSON] ---- @@ -146,6 +146,23 @@ The following examples show a failed delivery of file attachments due to access } ---- +[source,JSON] +---- +{ + "files": [ + { + "filename": "sales_report.pdf", + "contentType": "application/pdf", + "size": 1024000, + "provider": "GCP_GCS", + "bucketName": "my-webhook-files", + "objectKey": "thoughtspot/cluster-abc/user-123/org-0/liveboard/sales_report.pdf", + "uploadStatus": "SUCCESS" + } + ] +} +---- + [source,JSON] ---- { @@ -162,7 +179,7 @@ For other webhook destinations, ThoughtSpot sends a `multipart/form-data` payloa The supported attachment file formats for webhook delivery are PDF, CSV, and XLSX. -[source,JSON] +[source,http] ---- Content-Type: multipart/form-data; boundary=------------------------boundary123 @@ -330,7 +347,7 @@ The `WebhookActorInfo` schema defines the properties of the entity that initiate | `actorType` | string | Initiator of the event such as the API client or user. The default actor type is `SYSTEM`. | Yes | `id` | string a| Unique identifier, such as a GUID or object ID. For system-generated responses, the `id` is set to `null`. | No -| `name` | string a| Name of the actor that initiated the event. For system-generated responses, the `name` will be set as `null`. | No +| `name` | string a| Name of the actor that initiated the event. For system-generated responses, the `name` is set to `null`. | No | `email` | string a| Email of the actor that initiated the event. For system-generated responses, the `email` is set to `null`. | No |===== @@ -362,7 +379,7 @@ The `LiveboardScheduleData` schema defines event-specific data for Liveboard sch | `recipients` | array | Details of the ThoughtSpot users, groups, and email addresses of external users configured as subscribers to Liveboard schedule notifications and recipients of the webhook payload. For more information, see xref:webhooks-payload.adoc#_recipientinfo[RecipientInfo]. | Yes | `viewInfo` | object | Information about the Liveboard view. Applicable if the Liveboard schedule event is triggered for a personalized view of the Liveboard. For more information, see xref:webhooks-payload.adoc#_viewinfo[ViewInfo]. | No | `aiHighlights` | string | AI Highlights information. Applicable if AI highlights feature is enabled for the visualizations on the Liveboard. | No -| `msgUniqueId` | string | Unique message identifier. Unique ID of the webhook payload message. This ID can be used for traceability and deduplication on the receiving end. | No +| `msgUniqueId` | string | Unique ID of the webhook payload message. This ID can be used for traceability and deduplication on the receiving end. | No | `channelID` | string | The communication channel ID used for event dissemination. | No | `channelType` | string | Type of the communication channel. The channel type used for webhook payloads is `webhook`. | No | `communicationType` | string | Type of the messaging event. For Liveboard schedule events, the communication type will be `LiveboardSchedules`. | No @@ -374,7 +391,7 @@ The `ScheduleDetails` schema defines the properties of the schedule that trigger [width="100%" cols="1,1,3,1"] [options='header'] -|==== +|===== | Field | Type | Description | Required? | `scheduleId` | string | ID of the Liveboard schedule. | Yes | `name` | string | Name of the Liveboard schedule. | Yes @@ -385,11 +402,11 @@ The `ScheduleDetails` schema defines the properties of the schedule that trigger | `userIds` | array | IDs of the ThoughtSpot users that are subscribed to the scheduled Liveboard notifications. | No | `groupIds` | array | IDs of the ThoughtSpot groups that are subscribed to the scheduled Liveboard notifications.| No | `runId` | string | Schedule run ID of the Liveboard job. | No -| `exportRequest` | object | Details of the file export request. If the scheduled notification includes PDF attachment, the `exportRequest` includes details of the Liveboard and PDF page attributes. | No +| `exportRequest` | object | Details of the file export request. If the scheduled notification includes a PDF attachment, the `exportRequest` includes details of the Liveboard and PDF page attributes. | No | `fileFormat` | string | File format for export. Schedule notifications generally include PDF attachments. | No | `status` | string | Status of the schedule. | No -| `emailIds` | array | Email IDs of users subscribed to Liveboard job schedule. | No -|==== +| `emailIds` | array | Email addresses of users subscribed to the Liveboard job schedule. | No +|===== ==== RecipientInfo @@ -417,12 +434,12 @@ The `ViewInfo` schema defines properties of the Liveboard view for which the eve [width="100%" cols="1,1,3,1"] [options='header'] -|====== +|===== | Field | Type | Description | Required? | `viewId` | string | ID of the Liveboard personalized view. | Yes | `viewName` | string | Name of the Liveboard personalized view. | Yes -|====== +|===== == Additional resources diff --git a/modules/ROOT/pages/webhooks-s3-storage.adoc b/modules/ROOT/pages/webhooks-s3-storage.adoc index bc581e52e..05d589219 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 configuration for webhooks :toc: true :toclevels: 3 @@ -8,27 +8,20 @@ [beta betaBackground]^Beta^ -ThoughtSpot can deliver webhook payloads, such as scheduled Answer or Liveboard exports, as files written directly to your S3 storage. When integrated, ThoughtSpot supports delivering payloads of up to 25 MB directly to the storage destination configured on your instance. +ThoughtSpot can deliver webhook payloads and file attachments from a scheduled Liveboard event to your cloud storage bucket. When configured, ThoughtSpot can send payloads of up to 25 MB directly to the storage destination configured for the webhook delivery on your instance. == Before you begin - Before you begin, review the following prerequisites and ensure that you have the required setup for webhook configuration: -* Ensure that you have access to a ThoughtSpot instance with the Webhook feature enabled. -* Identify the environment in which your instance is deployed. Currently, S3 storage integration is supported in application instances hosted in one of the following environments: + -** ThoughtSpot instances hosted in Amazon Web Services (AWS) -** ThoughtSpot instances hosted in Google Cloud Platform (GCP) - -* Ensure that you have an AWS account where the target S3 bucket will be hosted. -* Ensure that you have AWS permissions to: +* Identify the environment in which your instance is deployed. For example, Amazon Web Services (AWS) and Google Cloud Platform (GCP). For S3 destination integration for webhook delivery, the platform AWS account ID and IAM trust policy template are required. To xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[retrieve these details], send a `GET` request to the `/api/rest/2.0/webhooks/storage-config` API endpoint. +* Ensure that you have an AWS account where the target S3 bucket is hosted with the following permissions: ** manage IAM identity providers and roles, including trust policies ** attach or edit IAM policies ** read and write to the target S3 bucket to test and validate integration - -* To configure a webhook in ThoughtSpot, you'll need a user account with administration privileges or the *Can Manage Webhooks* role privilege. +* To configure a webhook in ThoughtSpot, you'll need a user account with administration privileges or the *Can Manage Webhooks* role privilege. Ensure that you have the required privileges to set up webhook connection and monitor delivery status. * Ensure that a xref:webhooks-comm-channel.adoc[webhook communication channel] is configured in your Org or at the cluster level on your instance. -== AWS-based ThoughtSpot instances +== S3 storage configuration for AWS-hosted ThoughtSpot instances If your ThoughtSpot instance is running in AWS, you can configure AWS cross-account access with an IAM role that AWS STS can assume by using temporary credentials. For webhook integration, the following configuration setup is required: @@ -43,7 +36,7 @@ To obtain the account ID, contact your ThoughtSpot representative. + You must allow this ID to access your S3 resources and grant the required permissions. | AWS S3 bucket a| Create an S3 bucket or use an existing S3 bucket that you intend to use as a storage destination for ThoughtSpot exports. -You can also add a prefix for example, `thoughtspot/`, to logically separate ThoughtSpot files. This serves as the S3 prefix for webhook delivery. +You can also add a prefix, for example, `thoughtspot/`, to logically separate ThoughtSpot files. This serves as the S3 prefix for webhook delivery. | Cross-account IAM role a| The IAM role that ThoughtSpot will assume to deliver webhook content to an S3 bucket. For example, `thoughtspot-s3-upload`. The IAM role must include the following policies: @@ -99,10 +92,10 @@ In the permissions policy, specify the S3 bucket name. Optionally, to restrict a Note the IAM role ARN, bucket name, external ID, and other attributes and save the IAM policies. |==== -== GCP-based ThoughtSpot instances +== S3 storage configuration for GCP-hosted ThoughtSpot instances If your ThoughtSpot instance is hosted on a GCP cluster, you must configure OIDC and AWS STS `AssumeRoleWithWebIdentity` so that ThoughtSpot can securely obtain temporary AWS credentials to upload files to your S3 bucket, without storing long-lived AWS access keys. -For webhook integration, the following are required: +For webhook integration, the following information is required: [width="100%" cols="2,6"] [options='header'] @@ -111,11 +104,9 @@ For webhook integration, the following are required: | ThoughtSpot service account ID a| Contact ThoughtSpot Support to obtain your account ID. This account ID is required for OIDC identity creation and trust policy configuration. | AWS S3 bucket a| Create an S3 bucket or use an existing S3 bucket that you intend to use as a storage destination for ThoughtSpot exports. You can also add a prefix, for example, `thoughtspot-webhooks/`, to logically separate ThoughtSpot files. This serves as the S3 prefix for webhook delivery. | OIDC provider URL a| Add the OIDC identity provider URL in the AWS console. For example, `accounts.google.com`. - | AWS IAM role a| The IAM role that ThoughtSpot can assume via `AssumeRoleWithWebIdentity` during upload. **Web Identity trust policy** + - A trust policy that allows GCP service account via the identity provider. Ensure that the IAM role’s trust policy is restricted using `sub` (subject) and `aud` (audience) attributes: ** `sub`: ThoughtSpot GCP service account unique ID @@ -172,7 +163,7 @@ In the permissions policy, specify the role ARN and S3 bucket name. Optionally, |==== -== Provide the storage configuration details to ThoughtSpot +== Storage configuration details for ThoughtSpot Provide the following information to your ThoughtSpot administrator: * AWS Role ARN. For example, `arn:aws:iam::999888777666:role/thoughtspot-s3-upload` @@ -181,24 +172,24 @@ Provide the following information to your ThoughtSpot administrator: * S3 region. For example, `us-east-1` * S3 prefix for the folder (optional). For example, `thoughtspot/`. -== Configure a webhook for the S3 storage destination in ThoughtSpot +== Configuring 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. [NOTE] ==== -ThoughtSpot allows only one webhook per Org. +ThoughtSpot allows only one webhook for the Liveboard Schedule event type per Org. ==== ==== Request parameters -[width="100%" cols="1,6"] +[width="100%", cols="1,6"] [options='header'] |==== |Parameter|Description @@ -213,7 +204,7 @@ __Optional__ a|__String__. Description text for the webhook. __String__. Type of storage destination. Specify `AWS_S3`. + * `storage_config` + -Storage configuration parameters. Specify the storage configuration parameters from your AWS account administrator. +Storage configuration parameters. For `aws_s3_config`, specify the following parameters: * `bucket_name` + __String__. S3 bucket name. For example, `ts-data-exports` @@ -224,7 +215,7 @@ __String__. IAM role ARN. For example, `arn:aws:iam::999888777666:role/thoughtsp * `external_id` + __String__. The External ID string in IAM role trust policies that grant access to your AWS resources. For example, `ts-webhook-x7k9m2p4q1`. This parameter is required for AWS-hosted instances and is not applicable to GCP-hosted ThoughtSpot instances. * `path_prefix` __Optional__ + -__String__. S3 prefix for the folder. For example, `thoughtspot/`. +__String__. Path prefix for organizing objects within the S3 bucket. For example, `thoughtspot/`. |`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`. @@ -253,7 +244,7 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "name": "Webhook_S3", - "url": "https://api.example.com/thoughtspot/webhook", + "url": "https://webhook-destination-site.com", "events": [ "LIVEBOARD_SCHEDULE" ], @@ -279,254 +270,109 @@ If the API request is successful, ThoughtSpot returns the webhook configuration [source,JSON] ---- { - "id":"e63886a8-d468-4fc8-9c9b-a72bab6c4aee", - "name":"name6", - "description":null, + "id":"875f1497-fc98-436e-af59-28dc74dc324e", + "name":"webhook-S3", + "description":"Webhook for S3", "org":{ - "id":"0", - "name":"Primary" - }, - "url":"https://api.example.com/thoughtspot/webhook", - "url_params":{ - "key":"value" + "id":"2100019165", + "name":"test-org" }, + "url":"https://webhook-destination-site.com", + "url_params":null, "events":[ "LIVEBOARD_SCHEDULE" ], "authentication":null, "signature_verification":null, - "creation_time_in_millis":1772100928376, - "modification_time_in_millis":1772100928376, + "additional_headers":null, + "creation_time_in_millis":1782867817910, + "modification_time_in_millis":1782867817910, "created_by":{ - "id":"61b37746-a9bc-4433-b0cb-7a0e03225932", - "name":"demo_devuser" + "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "name":"user@thoughtspot.com" }, "last_modified_by":null, "storage_destination":{ "storage_type":"AWS_S3", "storage_config":{ "aws_s3_config":{ - "bucket_name":"ts-webhook-x7k9m2p4q1", + "bucket_name":"my-company-data-exports", "region":"us-east-1", "role_arn":"arn:aws:iam::999888777666:role/thoughtspot-s3-upload", "external_id":"ts-webhook-x7k9m2p4q1", "path_prefix":"thoughtspot/" - } - } - } -} ----- - -=== View webhook configuration details - -To view the webhook configuration details, send a `POST` request to the `/api/rest/2.0/webhooks/search` API endpoint. - -If the API request is sent without parameters in the request body, ThoughtSpot returns the webhooks configured for the Org context in ThoughtSpot. - -==== 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", - "webhook_identifier": "3791ad80-70e8-4222-bf11-fb8a5f1b5bf4", - "event_type": "LIVEBOARD_SCHEDULE" -}' ----- - -==== Example response -If the webhook ID is valid, the API returns the following response: - -[source,JSON] ----- -{ - "webhooks":[ - { - "id":"3791ad80-70e8-4222-bf11-fb8a5f1b5bf4", - "name":"webhook_s3", - "description":null, - "org":{ - "id":"2100019165", - "name":"docstest" - }, - "url":"https://webhook.site/6643eba5-9d3e-42a1-85e0-bb686ba1524d", - "url_params":null, - "events":[ - "LIVEBOARD_SCHEDULE" - ], - "authentication":null, - "signature_verification":null, - "additional_headers":null, - "creation_time_in_millis":1772127694740, - "modification_time_in_millis":1772127859128, - "created_by":{ - "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "name":"shashikala.subramanya@thoughtspot.com" }, - "last_modified_by":{ - "id":"08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "name":"shashikala.subramanya@thoughtspot.com" - }, - "storage_destination":{ - "storage_type":"AWS_S3", - "storage_config":{ - "aws_s3_config":{ - "bucket_name":"my-company-data-exports", - "region":"us-east-1", - "role_arn":"arn:aws:iam::999888777666:role/thoughtspot-s3-upload", - "external_id":"ts-webhook-x7k9m2p4q1", - "path_prefix":"thoughtspot/" - } - } - } + "gcp_gcs_config":null } - ], - "pagination":{ - "record_offset":0, - "record_size":50, - "total_count":1, - "has_more":false - } -} ----- - - -=== Update the webhook configuration properties - -To update the S3 storage details configured for a webhook, 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. -* `storage_destination` + -S3 storage destination. -* `storage_type` + -Type of storage destination. Currently, only the Amazon S3 bucket is supported as the storage destination. -* `storage_config` + -S3 storage configuration parameters: - -==== API 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_identifier}/update' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "name": "name6", - "url": "https://api.example.com/thoughtspot/webhook", - "events": [ - "LIVEBOARD_SCHEDULE" - ], - "url_params": { - "key": "value" - }, - "storage_destination": { - "storage_type": "AWS_S3", - "storage_config": { - "aws_s3_config": { - "bucket_name": "ts-webhook-x7k9m2p4q1", - "region": "us-east-1", - "role_arn": "arn:aws:iam::999888777666:role/thoughtspot-s3-upload", - "external_id": "ts-webhook-x7k9m2p4q1", - "path_prefix": "thoughtspot/webhook" - } - } - } -}' ----- - -==== API response - -If the API request is successful, the API returns a 204 response code indicating a successful operation. - -== Validate webhook channel configuration -To validate the communication channel configuration, use the `/api/rest/2.0/system/communication-channels/validate` API endpoint. - -For this API request, you'll need the webhook channel ID. To get the webhook ID, use the `/api/rest/2.0/webhooks/search` API endpoint. - -=== Example request -The following example sends validation request for a specific webhook channel with the S3 storage configuration. - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/system/communication-channels/validate' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "channel_type": "WEBHOOK", - "channel_identifier": "3791ad80-70e8-4222-bf11-fb8a5f1b5bf4", - "event_type": "LIVEBOARD_SCHEDULE" -}' ----- - -=== Example response - -If the webhook ID is valid, the API returns the validation status for the specified webhook channel. - -The following response shows the validation errors for a webhook channel that has the AWS S3 storage destination configured: - -[source,JSON] ----- -{ - "channel_type":"WEBHOOK", - "channel_id":"52314c1c-8d1d-40d1-8dba-3f77d219b41a", - "channel_name":"nebula-webhooks-gcp-05012026-webhook1", - "event_type":"LIVEBOARD_SCHEDULE", - "job_id":"n.validation-37688eaf-6cb1-4f7e-a6f2-0658c1d678eb", - "result_code":"PARTIAL_SUCCESS", - "details":[ - { - "validation_step":"STORAGE_FILE_UPLOAD_CHECK", - "status":"FAILED", - "http_status":null, - "error_message":"failed to assume role 'arn:aws:iam::123456789012:role/ThoughtSpotDeliveryRole': operation error STS: AssumeRole, https response error StatusCode: 403, RequestID: 8ba1a7a1-65c2-4901-8d4a-bf150687e92c, api error AccessDenied: User: arn:aws:sts::418295724037:assumed-role/cell-89b3a1c7-coms-lambda-role/cell-89b3a1c7-coms-api is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::123456789012:role/ThoughtSpotDeliveryRole. Ensure the role's trust policy allows ThoughtSpot and the External ID matches", - "aws_s3_info":{ - "bucket_name":"my-webhook-files", - "file_name":"validation_dummy_20260330_131030.pdf", - "object_key":"webhooks/cluster-abc/org-1/user-123/liveboard/report.pdf" - } - }, - { - "validation_step":"HTTP_CONNECTION_CHECK", - "status":"SUCCESS", - "http_status":200, - "error_message":null, - "aws_s3_info":null - } - ] + }, + "status":"ENABLED" } ---- -If the API returns validation errors, check your webhook configuration and update the S3 storage properties. For more information about configuration errors, see the xref:webhooks-s3-storage.adoc#_configuration_errors[troubleshooting] section. - -== Verify the integration +=== Using Webhooks page in UI +If the new Webhooks page is enabled on your instance, you can create a webhook via the UI. +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. +. To configure storage destination, select the **File storage** checkbox and specify values for the following properties: + +* **Storage provider**: For AWS S3 storage, ensure that **Amazon S3** is selected. +* **Bucket name**: Name of the S3 bucket. For example, `my-company-data-exports`. +* **Region**: S3 region. For example, `us-east-1` +* **Role ARN**: AWS Role ARN. For example, `arn:aws:iam::999888777666:role/thoughtspot-s3-upload` +* **External ID**: External ID. For example, `ts-webhook-x7k9m2p4q1`. Required for configuring a webhook on ThoughtSpot instances hosted in AWS. Not applicable to ThoughtSpot instances on GCP. +* **Path prefix**: Optional. Path prefix for organizing objects within the S3 bucket. For example, `thoughtspot/`. ++ +[.bordered] +[.widthAuto] +-- +image::./images/create-webhook-s3.png[Webhooks creation] +-- +//. Select xref:webhooks-ux.adoc#_creating_a_webhook[the authentication method] to authorize payloads to the destination endpoint. + +. To configure xref:webhooks-ux.adoc#_creating_a_webhook[advanced settings] such as signature verification, custom headers, and URL query parameters, click **Advanced settings** and configure the fields as required. +. Click *Save*. + +If the webhook is created successfully, it is added to the Webhooks list and enabled by default. + +== Viewing webhook configuration details +To view the webhook details, use one of the following options: + +* Through the REST API: + +To retrieve webhook configuration details, use the xref:webhooks-api.adoc#_getting_a_list_of_webhooks[`/api/rest/2.0/webhooks/search` API endpoint]. +* Using the UI: + +If the **new Webhook experience** is enabled on your instance, go to the **Develop** > **Customization** > **Webhooks** page. Check the list in the xref:webhooks-ux.adoc#_webhooks_list_page[**Webhooks**] to view the details and verify if the webhook connection is activated. + +== Validating webhook channel configuration +To validate webhook configuration status, use one of the following options. + +* Using REST API: +To validate the communication channel configuration for webhook delivery, use xref:webhooks-comm-channel.adoc#_validate_communication_channel_configuration[the `/api/rest/2.0/system/communication-channels/validate` API endpoint]. + +* Using the UI: + +If the new Webhook experience is enabled on your instance, go to the **Develop** > **Customization** > **Webhooks** page. The Webhooks page displays a list of webhooks configured in the current Org context. + +To validate the webhook channel configuration: +. In the **Webhooks** page, select the webhook row, and click **Send test event**. +. Verify the delivery status. + +If the validation returns errors, update the webhook configuration properties to resolve the errors. + +== Monitoring webhook delivery status +To monitor the webhook delivery and status, use one of the following options: + +* Through the REST API: + +To verify 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]. + +* Using the UI: + +If your ThoughtSpot instance has new Webhooks page enabled, use the **Webhooks** menu option in the **Develop** page to view the details of the webhook: +. Go to the **Develop** > **Customization** > **Webhooks** page. + +The **Webhooks** page displays status cards and delivery rate for the webhooks configured in the Org. +. Click the webhook from the list and verify the delivery details. For more information, see xref:webhooks-ux.adoc#_monitoring_webhook_status[Monitoring delivery status]. + +== Verifying webhook delivery Webhook delivery to an S3 storage destination includes the following sequence of events: . ThoughtSpot requests temporary AWS credentials by calling `sts:AssumeRole` (AWS setup) or `sts:AssumeRoleWithWebIdentity` (GCP) with your specified Role ARN and External ID. @@ -534,46 +380,38 @@ Webhook delivery to an S3 storage destination includes the following sequence of . If the request is valid, AWS STS issues temporary credentials, valid for approximately an hour. . ThoughtSpot uses these credentials to upload files to your designated S3 bucket. -Before testing the integration, validate the webhook connection using 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-s3-storage.adoc#_update_the_webhook_configuration_properties[update your webhook configuration]. See the xref:webhooks-s3-storage.adoc#_troubleshooting_errors[troubleshooting section] for information on resolving configuring errors. +To verify that ThoughtSpot is delivering webhooks to your S3 bucket: -If the connection status is successful: -. Trigger a Liveboard scheduled export to the configured S3 storage destination. -. In your S3 bucket: -* Confirm whether the webhook payload is delivered to the correct bucket and prefix. -* Verify the attachments and timestamps in the AWS event logs. +. Access your S3 bucket. +. Verify whether the webhook payload is delivered to the correct bucket and prefix. +. Review the object content to confirm the payload matches the expected schema. +. Verify the attachments and timestamps in the logs. . If files are not delivered to your S3 bucket, check the logs for errors. -== Monitor webhook delivery status -To monitor the webhook delivery and 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]. - -== Troubleshoot errors - +== Troubleshooting errors The common causes for webhook delivery failure are: -* Access denied errors -* Invalid external ID -* Webhook configuration errors in ThoughtSpot +[cols="2,4"] +[options="header"] +|==== +| Issue | Resolution -=== Access denied errors -The access denied error occurs in the following scenarios: +| Objects not delivered to the bucket +| This occurs in the following scenarios: * When the IAM role assumption fails * When the S3 upload fails due to permission errors +* Webhook connection configuration errors To resolve IAM role assumption issues: * Ensure that the IAM trust policy includes the correct ThoughtSpot service account ID. + -For GCP clusters, the trust policy must use a federated principal. Verify that the OIDC provider URL and identity are configured for the ThoughtSpot service account ID (`THOUGHTSPOT_SA_UNIQUE_ID`). * Ensure that ThoughtSpot is assigned AWS credentials via `sts:AssumeRole` (for AWS) or `sts:AssumeRoleWithWebIdentity` (for GCP) for the specified Role ARN and External ID. To resolve S3 upload permission errors: Ensure that the IAM permission or S3 bucket policy allows the IAM role to write objects and has the correct S3 actions configured. To write content to the S3 bucket, the `s3:PutObject` permission is required. -=== Configuration errors - S3 uploads can also fail due to errors in webhook configuration in ThoughtSpot. ThoughtSpot can control which buckets can be accessed, what actions are permitted, and when to revoke access. However, ThoughtSpot cannot read files in existing S3 storage that is not integrated with webhooks, access other prefixes, or view or modify objects in the bucket. @@ -583,17 +421,15 @@ To ensure that there is no mismatch in the configuration: * Verify the external ID used in the webhook configuration. Note that external IDs are case-sensitive. * Ensure that the S3 bucket name and Role ARN configured in ThoughtSpot match the S3 bucket name and ARN of the IAM role in your AWS account. -=== Configuration compatibility -If you are using encryption, lifecycle policies, or special access controls, ensure that they are compatible with your webhook configuration. +| Webhook is configured but not triggering +| Verify that the webhook is enabled and that the alert condition for the scheduled event is met. Contact ThoughtSpot Support if the issue persists. +| Configuration compatibility issues +|If you are using encryption, lifecycle policies, or special access controls, ensure that they are compatible with your webhook configuration. -== Webhook removal - -To delete a webhook, use the `/api/rest/2.0/webhooks/delete` REST API endpoint and specify the webhook ID in the `POST` request body. - -When you delete a webhook with S3 storage, the webhook endpoint is removed and any events or workflows configured to use that webhook can no longer deliver the payloads. Files already stored in S3 are not deleted as part of webhook deletion; only the delivery mechanism is removed. +|==== == Additional resources -* See also: xref:webhooks.adoc[Webhooks] and xref:webhooks-lb-schedule.adoc[Webhooks for Liveboard schedule events]. -* link:https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html[AWS IAM documentation] and link:https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-s3.html[IAM and Amazon S3 troubleshooting guide]. +* See also: xref:webhooks.adoc[Webhooks overview], xref:webhooks-ux.adoc[Webhooks UI], and xref:webhooks-api.adoc[Webhook APIs] documentation. +* link:https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html[AWS IAM documentation, window=_blank] and link:https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot_iam-s3.html[IAM and Amazon S3 troubleshooting guide, window=_blank]. diff --git a/modules/ROOT/pages/webhooks-ux.adoc b/modules/ROOT/pages/webhooks-ux.adoc new file mode 100644 index 000000000..a29518606 --- /dev/null +++ b/modules/ROOT/pages/webhooks-ux.adoc @@ -0,0 +1,190 @@ += Webhooks UI +:toc: true +:toclevels: 3 + +:page-title: Webhooks UI +:page-pageid: webhooks-ui +: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 on the **Develop** page allows you to access the new **Webhooks** experience. This page provides a centralized interface with menu actions to create, edit, delete, enable, or disable a webhook, send test events, view delivery status and logs. + +[IMPORTANT] +==== +* The new Webhooks UI experience is in Beta and is disabled by default. To enable this feature, contact ThoughtSpot Support. +* When the new Webhooks page is enabled, the existing Webhooks page is displayed as the **Legacy Webhooks** menu action on the **Develop** page. +* The **Webhooks** page supports webhooks for the Liveboard Schedule events only. +==== + +=== Webhooks list page +The webhooks 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. + +Note that ThoughtSpot allows only one webhook for the Liveboard Schedule event type per Org. + +The actions available for the list items include: + +* *Sort*: Click any column header to sort the webhook list by that column. +* *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 the webhook connection. + +The following figure shows the Webhooks list and dashboard cards. + +[.bordered] +[.widthAuto] +-- +image::./images/webhooks-dashboard.png[Webhooks dashboard] +-- + +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. + +To enable, disable, edit, or delete the webhook configuration, select the webhook in the list, and use the options available in the More options (`...`) menu. + +=== Creating a webhook connection +The **Create webhook** option allows you to create a webhook for the Liveboard schedule event type. Only one webhook can be created per Org. + +The webhook creation workflow allows configuring webhook properties, including authentication parameters, storage destination, signature verification, custom headers, and URL parameters. + +You can create a webhook for the Liveboard schedule event type to send 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. + +For more information, see the following documentation: + +* xref:webhooks-lb-schedule.adoc#_through_the_webhooks_page_in_ui[Webhook configuration for Liveboard scheduled events]. +* xref:webhooks-s3-storage.adoc[AWS S3 storage configuration for webhooks] +* xref:webhooks-gcs-storage.adoc[GCS storage configuration for webhooks] + +//// +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. +. To deliver webhook reports to a Cloud storage destination, select **File storage** and define storage configuration parameters. +. Specify the authentication type to authorize webhook delivery. + +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. +. Optionally, configure the advanced settings as 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**. +//// + +=== Update webhook connection status +The webhook connections are automatically enabled when they are created in the UI or via the API. To update the webhook status, use the **Disable** and **Enable** options either in More options menu (`...`) or the buttons that appear above the list when a webhook row is selected. + +=== Testing a webhook connection +To verify a webhook connection: + +. Use one of the following options to send a test event: +* Select the webhook and click *Send test event*. +* In the webhook row, from the More options menu (`...`), click **Send test event**. +. To view the delivery status, click the webhook and view the webhook event log. + +=== Editing a webhook connection +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-api.adoc#_updating_a_webhook[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. + +=== Monitoring webhook status +The **Webhooks** page provides a dashboard view with cards indicating the delivery statistics. The cards refresh when the page is reloaded. + +* *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. + +To view delivery status of a specific webhook, click the webhook to open the delivery details page. + +To filter the list, click **Add filter** and select any of the following options: + +* **Delivery status**: Filters the webhooks list by their delivery status. +* **Sent**: Allows filtering the list by webhook deliveries that were sent in the last 1, 2, 4, or 8 hours, or the last 1, 2, or 3 days. + +By default, logs are retained for 3 days. If you want to store and retrieve logs for more than 3 days, contact ThoughtSpot Support. + +[.bordered] +[.widthAuto] +-- +image::./images/webhooks-list-filter.png[Webhooks list] +-- + +To view the log details of a specific webhook delivery, click **View details**. The **Log details** modal shows details such as the event name, type, timestamp, ID, delivery status, payload properties, and retry history. + +[.bordered] +[.widthAuto] +-- +image::./images/webhook-log.png[Webhooks log] +-- + +[#webhook-configuration-and-management-legacy-experience] +== Webhook configuration and management (Legacy experience) + +The **Legacy webhooks** option in the **Develop** > **Customizations** page provides access to webhooks created for KPI monitor alerts. These webhooks are managed separately from the new Webhooks experience. + +=== Accessing legacy webhooks +To access the legacy webhook configuration: + +. Navigate to the legacy webhooks page in the **Develop** section of the ThoughtSpot UI. +. The page displays the list of webhooks registered for KPI monitor alerts. + +=== Creating a webhook for KPI alerts +To create a webhook for KPI monitor alerts: + +. On the webhooks page, click **Create webhook**. +. Enter a display name and the fully qualified URL of the webhook endpoint. +. Configure the authentication method required by your destination endpoint. +. Click **Save**. + +After saving, the webhook appears in the list and can be selected as a custom notification channel when creating or editing a KPI monitor alert. For more information, see xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. + +=== Actions available for legacy webhooks +For each webhook in the list, the following actions are available: + +* *Edit*: Update the webhook name, URL, or authentication settings. +* *Delete*: Permanently remove the webhook from ThoughtSpot. + +[NOTE] +==== +Legacy webhooks for KPI alerts are separate from the Liveboard schedule webhooks managed through the xref:webhooks-ux.adoc#_webhook_configuration_and_management_new_experience[new Webhooks page]. KPI alert webhooks are not subject to the one-per-Org limit that applies to Liveboard schedule webhooks. +==== + +== 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-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..566f76f13 100644 --- a/modules/ROOT/pages/webhooks.adoc +++ b/modules/ROOT/pages/webhooks.adoc @@ -1,48 +1,78 @@ = 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-pageid: webhooks-overview +: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: +ThoughtSpot webhooks provide a way to deliver data and reports to a target application, URL endpoint, or storage destination, 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 +ThoughtSpot allows using webhooks for the following purposes: -* 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]. +Liveboard schedule notifications:: +ThoughtSpot supports using webhooks to deliver scheduled Liveboard notifications to external applications and communication channels. For more information, see +xref:webhooks-lb-schedule.adoc[Webhook configuration for Liveboard scheduled events]. +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[AWS S3 storage configuration for webhooks]. +* *Google Cloud Storage (GCS)*: Available on GCP-hosted ThoughtSpot Cloud instances. For more information, see xref:webhooks-gcs-storage.adoc[GCS storage configuration for webhooks]. -== Webhook configuration +KPI monitor alerts:: +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]. -ThoughtSpot users with developer or administrator privileges can create webhooks via REST APIs or from the *Develop* page in the UI. - -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. - -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 per Org is allowed for the Liveboard Schedule event type. +* To configure and manage webhooks, `ADMINISTRATION` (**Can administer ThoughtSpot**) or *Can manage webhooks* (`CAN_MANAGE_WEBHOOKS`) privilege is required. ==== -== 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: + +* **Webhooks** : + +The new *Webhooks* option in the *Develop* page provides a centralized view of webhooks configured in ThoughtSpot, including the options to create, monitor, and manage webhooks, and view delivery statistics and logs in your ThoughtSpot Org. -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. ++ +[IMPORTANT] +==== +* The new Webhooks UI experience is in Beta and is disabled by default. To enable this feature, contact ThoughtSpot Support. +* In the current version, the new experience allows creating and managing webhooks for Liveboard Schedule events only. +==== -For more information, see xref:webhooks-s3-storage.adoc[S3 storage integration for Webhook delivery]. ++ +For more information, see xref:webhooks-ux.adoc[Webhook configuration and management through the UI]. -== Response after webhook delivery +* **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-ux.adoc#webhook-configuration-and-management-legacy-experience[Webhook configuration and management through the UI] and xref:webhooks-kpi-alerts.adoc[Webhooks for KPI monitor alerts]. -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 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. For REST API reference and examples, see xref:webhooks-lb-schedule.adoc[Deliver Liveboard reports to an external application] and xref:webhooks-api.adoc[Webhook REST APIs]. -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. +== 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. -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. +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, 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-ux.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-lb-schedule.adoc[Configure a webhook for Liveboard scheduled events] +* xref:webhooks-s3-storage.adoc[Configure AWS S3 storage destination for webhook delivery] +* xref:webhooks-gcs-storage.adoc[Configure a GCS destination for webhook delivery] diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 9ecd6537a..6d9f374ea 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,6 +23,95 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ +== July 2026 + +**Release version**: ThoughtSpot Cloud 26.7.0.cl + +*Upgrade notes*: No breaking changes + +*Recommended SDK versions*: Visual Embed SDK v1.50.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|===== +a| +[.cl-label] +*Version 26.7.0.cl* + +a| +[discrete] +==== SpotterViz for Liveboards [earlyAccess eaBackground]#Early Access# +You can now use SpotterViz in your embedding application to help your users build and edit Liveboards through a conversational interface. Instead of manually configuring charts and layouts, your users can describe what they want and SpotterViz generates the Liveboard for them, including the new tabs, chart types, data filters, and scheduled deliveries. + +For SpotterViz customization in embedded view, the Visual Embed SDK also provides several options to customize the SpotterViz panel experience. For more information, see xref:embed-spotterViz.adoc[SpotterViz in embedded Liveboards]. + +--- + +[discrete] +==== Spotter embedding + +Spotter file upload in embedded apps:: +Applications embedding the Spotter interface can now allow their users to xref:embed-spotter.adoc#_enable_file_upload_in_spotter_chat[upload files directly in the Spotter chat panel]. + +Spotter conversation history:: +You can now save your Spotter conversation and manage chat history using Spotter AI REST APIs. For more information, see xref:spotter-agent-conversation-mgmt-apis.adoc[APIs for managing saved conversations]. + +Spotter Agent instructions:: +You can configure and retrieve behavioral instructions for the Spotter agent using REST APIs. For more information, see xref:spotter-agent-instructions.adoc[Spotter AI agent instructions APIs]. + +--- + +[discrete] +==== Focused home page experience [earlyAccess eaBackground]#Early Access# + +In full application embedding with the V3 navigation and home page experience, ThoughtSpot provides an additional option to switch to the V4 focused home page experience. The focused home page experience provides a streamlined, contemporary experience along with the Spotter panel. For more information, see xref:full-app-customize.adoc[Customize full application embedding]. + +--- + +[discrete] +==== Webhooks enhancements + +ThoughtSpot introduces the following features and enhancements for webhook configuration and management: + +* New Webhooks page in the UI [earlyAccess eaBackground]#Early Access# + +The *Develop* page now includes a xref:webhooks-ux.adoc[dedicated *Webhooks* page] for creating, managing, and monitoring webhooks within the Org context. +* Storage configuration retrieval + +The `GET /api/rest/2.0/webhooks/storage-config` REST API endpoint to xref:webhooks-api.adoc#_retrieving_storage_information_for_webhook_configuration[get storage configuration details]. +* GCS storage configuration for webhook delivery + +Administrators can now xref:webhooks-gcs-storage.adoc[configure Google Cloud Storage (GCS) buckets as a storage destination] for webhook payload delivery on GCP-hosted ThoughtSpot clusters. +* Webhook activation and deactivation + +You can enable or disable a webhook connection in the UI or through REST API. +* Selective configuration reset + +The xref:webhooks-api.adoc#_updating_a_webhook[webhook update API endpoint] supports the `reset_options` parameter to remove specific optional configuration sections without replacing the full webhook configuration. + +--- + +[discrete] +==== SpotterCode Agent in Visual Embed Playground [earlyAccess eaBackground]#Early Access# + +The Visual Embed SDK Playground now includes SpotterCode Agent, an AI-powered coding assistant. The SpotterCode panel displays pre-built prompts relevant to the component you are embedding, a prompt interface for user queries, and generates embed code. It generates boilerplate code automatically, accelerates building code and iterating embed configurations. + +For more information, see xref:developer-playground.adoc#spottercode-panel[Using SpotterCode in the Playground]. + +--- + +[discrete] +==== Org isolation for per-org SAML and OIDC authentication +ThoughtSpot now enforces strict org isolation when users authenticate through a per-org identity provider (IdP). When a per-org IdP sends SAML or OIDC group claims that reference Orgs outside its authorized scope, ThoughtSpot silently drops those claims and records them as security audit events. This prevents a rogue IdP administrator in one Org from using group assertions to gain unauthorized access to another Org. Manually-assigned existing Org memberships are unaffected. For more information, see xref:orgs.adoc#per-org-sso-isolation[SSO and Org isolation]. + +--- + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.50.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +For information about REST API v2 enhancements in this release, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +--- + +|===== + == June 2026 **Release version**: ThoughtSpot Cloud 26.6.0.cl + @@ -37,7 +126,7 @@ a| a| [discrete] -==== Chart and table overrides [.version-badge.new]#New# +==== 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 + @@ -59,9 +148,9 @@ This release introduces the following enhancements for Spotter AI workflows and * Spotter embedding: + Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. -* Spotter AI APIs: + +* 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]. + New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. --- @@ -75,6 +164,12 @@ The legacy REST Playground v1 has been removed from the left navigation. This ch * Removal of GraphQL playgrounds + The menu link to the GraphQL playground has been removed from the UI. +[discrete] +==== Liveboard browser cache refresh +To improve load performance and reduce, you can now enable the Liveboard cache option with a **Refresh** button to allow your users to clear cache and refresh visualization data when required. For more information, see xref:api-changelog.adoc#_liveboard_browser_cache_refresh[Liveboard browser cache refresh]. + +--- + [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]. @@ -91,7 +186,7 @@ This release introduces new API endpoints for Spotter, connections and trusted a == May 2026 **Release version**: ThoughtSpot Cloud 26.5.0.cl + -*Upgrade notes*: ⚠️Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + +*Upgrade notes*: ⚠️ Includes breaking changes to Spotter APIs. Refer to the xref:rest-apiv2-changelog.adoc[REST API changelog] for more information. + *Recommended SDK versions*: Visual Embed SDK v1.48.0 and later @@ -108,7 +203,7 @@ a| ==== Liveboard downloads Continuous Liveboard PDF export [beta betaBackground]^Beta^:: -In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. +In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. Liveboard download in XLSX and CSV formats:: Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. @@ -173,7 +268,7 @@ This release introduces new Spotter API endpoints and modifications to the agent == April 2026 **Release version**: ThoughtSpot Cloud 26.4.0.cl + -*Upgrade notes*: ⚠️Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: ⚠️ Variable update and delete API and metadata parameterization endpoints are deprecated and replaced with new API endpoints. Refer to xref:rest-apiv2-changelog.adoc#version_26_4_0_cl_april_2026[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.47.0 and later [.cl-table, cols="2,4", frame=none, grid=none] @@ -248,7 +343,7 @@ The ListPage V3 experience provides a refreshed list layout and styling, includi * The **Views** column to show the number of views for each object. * Sorting options for **Name**, **Author**, and **Views** columns. -* Filter addition by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. +* Filters can be added by clicking the column header without opening the filter modal. This option is available for **Favorites**, **Views** columns, and **Verified** columns. For more information, see xref:full-app-customize.adoc#_customize_list_page_experience[List page customization]. @@ -310,7 +405,7 @@ For information about REST API v2 enhancements, see the xref:rest-apiv2-changelo == March 2026 **Release version**: ThoughtSpot Cloud 26.3.0.cl + -*Upgrade notes*: ⚠️Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: ⚠️ Includes feature deprecations. Refer to xref:rest-apiv2-changelog.adoc#_custom_access_token_api[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.46.0 and later [.cl-table, cols="2,4", frame=none, grid=none] @@ -394,7 +489,7 @@ For information about REST API v2 enhancements, see the xref:rest-apiv2-changelo == February 2026 **Release version**: ThoughtSpot Cloud 26.2.0.cl + -*Upgrade notes*: ⚠️Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + +*Upgrade notes*: ⚠️ Includes API parameter deprecations. Refer to xref:rest-apiv2-changelog.adoc[REST API changelog] and xref:deprecated-features.adoc[Deprecation announcements]. + *Recommended SDK versions*: Visual Embed SDK v1.45.0 and later @@ -416,7 +511,7 @@ SpotterCode is available as an Early Access feature and can be integrated with d [discrete] ==== Spotter 3 experience [earlyAccess eaBackground]#Early Access# -You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. +You can now embed the Spotter 3 experience, which introduces several new capabilities, agentic analytics, and an enhanced user experience. Spotter 3 is an Early Access feature and is disabled by default on ThoughtSpot embedded instances. For more information, see xref:embed-ai-analytics.adoc[Embed AI Search and Analytics] and xref:embed-spotter.adoc[Spotter embedding documentation]. @@ -551,13 +646,8 @@ For information about the new features and enhancements introduced in Visual Emb --- -[discrete] -==== Custom calendar APIs - ---- - [discrete] ==== REST API For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -|=== +|=== \ No newline at end of file diff --git a/src/components/DevDocTemplate/index.tsx b/src/components/DevDocTemplate/index.tsx index bb83b7d80..4b0ac293c 100644 --- a/src/components/DevDocTemplate/index.tsx +++ b/src/components/DevDocTemplate/index.tsx @@ -53,6 +53,10 @@ import t from '../../utils/lang-utils'; import { getHTMLFromComponent } from '../../utils/react-utils'; import VersionIframe from '../VersionIframe'; +// Key of the merged nav-in-product-help.adoc entry in processedNavMap (pageid minus 'nav-' prefix). +// Not a real DocCategory/tab — used only to pick the left sidebar content when embedded in-product. +const IN_PRODUCT_NAV_KEY = 'in-product-help'; + const DevDocTemplate: FC = (props) => { const { data, @@ -127,21 +131,28 @@ const DevDocTemplate: FC = (props) => { []); // Breadcrumb data built from master nav + all category navs for full coverage + // (excludes the merged in-product nav, which duplicates the category navs) const breadcrumsData = React.useMemo(() => { if (typeof window === 'undefined') return []; const allHtmls = [ initialNavContentData, - ...Object.values(processedNavMap as Record), + ...Object.entries(processedNavMap as Record) + .filter(([cat]) => cat !== IN_PRODUCT_NAV_KEY) + .map(([, html]) => html), ]; return allHtmls.flatMap((html) => fetchChild(html)); }, [processedNavMap]); - // Pick the right sidebar content for the active category + // Pick the right sidebar content for the active category. + // In-product (embedded) presentation has no category tabs — always show the merged nav. const activeNavContent = React.useMemo(() => { + if (!isPublicSiteOpen) { + return processedNavMap[IN_PRODUCT_NAV_KEY] || navContent; + } const navId = CATEGORY_NAV_ID[activeCategory]; const mapKey = navId.startsWith('nav-') ? navId.slice(4) : null; return (mapKey && processedNavMap[mapKey]) || navContent; - }, [activeCategory, processedNavMap, navContent]); + }, [activeCategory, processedNavMap, navContent, isPublicSiteOpen]); const isCustomPage = _.values(CUSTOM_PAGE_ID).some( (pageId: string) => pageId === params[TS_PAGE_ID_PARAM], @@ -171,11 +182,13 @@ const isVersionedIframe = VERSION_DROPDOWN.some( const isAskDocsPage = params[TS_PAGE_ID_PARAM] === CUSTOM_PAGE_ID.ASK_DOCS; /* Build pageId → category map by parsing hrefs from each category's nav HTML. - * This means writers only need to update nav-*.adoc — no TypeScript changes needed. */ + * This means writers only need to update nav-*.adoc — no TypeScript changes needed. + * Excludes the merged in-product nav, which isn't a real tab/category. */ const pageIdToCategoryMap = React.useMemo(() => { if (typeof window === 'undefined') return {}; const map: Record = {}; Object.entries(processedNavMap).forEach(([cat, html]) => { + if (cat === IN_PRODUCT_NAV_KEY) return; const doc = new DOMParser().parseFromString(html as string, 'text/html'); doc.querySelectorAll('a[href]').forEach((a) => { const href = a.getAttribute('href') || ''; @@ -723,13 +736,28 @@ if (isVersionedIframe) { } > {!isIframeMode && !isVersionedIframe && ( - + isPublicSiteOpen ? ( + + ) : !isMaxMobileResolution && ( + // In-product presentation has no tabs — show just the nav + // toggle so the sidebar stays reachable on narrow viewports. + // Desktop-width embeds skip this entirely; the sidebar is + // always visible there. + + ) )}
diff --git a/src/components/LeftSidebar/NavContent.tsx b/src/components/LeftSidebar/NavContent.tsx index 7629d9022..f4fa1ea97 100644 --- a/src/components/LeftSidebar/NavContent.tsx +++ b/src/components/LeftSidebar/NavContent.tsx @@ -1,4 +1,5 @@ import React from 'react'; +import { navigate } from 'gatsby'; import { IconContext } from '@react-icons/all-files'; import { BiSearch } from '@react-icons/all-files/bi/BiSearch'; import BackButton from '../BackButton'; @@ -50,6 +51,19 @@ const NavContent = (props: { + {/* AskDocs lives in the top SecondaryHeader on the standalone site; + that bar is hidden in-product, so surface it here instead. */} + {!props.isPublicSiteOpen && ( +
+ +
+ )}