diff --git a/modules/ROOT/pages/3rd-party-script.adoc b/modules/ROOT/pages/3rd-party-script.adoc new file mode 100644 index 000000000..02b8c3b2e --- /dev/null +++ b/modules/ROOT/pages/3rd-party-script.adoc @@ -0,0 +1,67 @@ += Integrate external tools and allow custom scripts +:toc: true +:toclevels: 2 + +:page-title: Integrate external tools and allow scripts +:page-pageid: external-tool-script-integration +:page-description: Security settings for embedding + +ThoughtSpot supports integrating third-party apps such as Mixpanel, Pendo, LogRocket, and more in your embed. If you are using third-party tools to track usage, trace, log, or onboard your application users, you can seamlessly integrate these tools with ThoughtSpot embed and add custom JavaScripts. This feature is disabled by default on ThoughtSpot instances. To enable this feature, contact ThoughtSpot Support. + +[IMPORTANT] +==== +While ThoughtSpot allows the injection of custom JavaScripts, it is important to be aware of the associated security risks, particularly Cross-Site Scripting (XSS). XSS is a vulnerability that can enable malicious actors to inject and execute unauthorized scripts within a trusted environment. This can lead to data breaches, unauthorized access to user sessions, and compromised system integrity. ThoughtSpot strongly recommends reviewing security guidelines before activating this feature in your instances and exercising caution when integrating third-party tools into your embedded application. +==== + +== Security considerations + +Before requesting ThoughtSpot Support to enable this feature on your instance, do the following: + +* Review the security risks associated with custom-hosted scripts and understand the potential consequences of XSS attacks. +* Implement security controls and measures to validate hosted scripts and mitigate potential vulnerabilities. + +== Feature enablement + +Enabling third-party tools on embed involves two steps: + +. Request for feature activation and provide the script details to ThoughtSpot Support +. Adding the script sources to the CSP allowlist + +=== Request for feature enablement + +Create a ThoughtSpot Support ticket to enable the feature on your instance. In your request, specify the domain URLs that will host the scripts in your embedding environment. + +Wait for ThoughtSpot Support to validate, approve, and configure the URL for your instance. This step will ensure that only the trusted and vetted domains are allowed to run scripts in your application environment. + +=== Add script source to CSP allowlist +After the script hosting URL is approved and configured by ThoughtSpot Support, you must add the JavaScript hosting domain to the CSP allowlist. This step requires administration privileges, so make sure you log in to ThoughtSpot with your administrator credentials. + +. In your ThoughtSpot application, navigate to *Develop* > *Customizations* > *Security Settings*. +. If your instance has the Orgs feature enabled, ensure that you are in the *All Orgs* context. +. On the *Security Settings* page, click *Edit* and turn on the *CSP script-src domains* toggle switch. ++ +[.widthAuto] +[.bordered] +image::./images/csp-script-domain.png[CSS script-src domain] +. Add the script hosting domain. +. Click *Save changes*. + +[NOTE] +==== +* The *CSP script-src domains* section is visible to users with administrative privileges only if the third-party integration feature is enabled on your instance. +* The *CSP script-src domains* cannot be enabled and configured at the Org level. When configured, this setting will apply to all the Orgs configured on your instance. +==== + +== Passing variables to the hosted script + +To pass variables to the customer's hosted script, Visual Embed SDK provides the `customVariablesForThirdPartyTools` parameter. The `customVariablesForThirdPartyTools` is an object containing the variables that you wish to pass to the customer’s hosted JavaScript. These may include private information such as credentials or keys. The hosted JavaScript will access these variables via the `window.tsEmbed` object. + +Developers can define this parameter in the **init()** function as shown in the following example. Once initialized, the JavaScript will run after the authentication is successfully completed in the ThoughtSpot Embed App. + +[source,JavaScript] +---- +init({ + //... + customVariablesForThirdPartyTools: { cloud: "123Basic" } +}); +---- diff --git a/modules/ROOT/pages/api-auth-session.adoc b/modules/ROOT/pages/api-auth-session.adoc index a84a470d9..33ddd2ce8 100644 --- a/modules/ROOT/pages/api-auth-session.adoc +++ b/modules/ROOT/pages/api-auth-session.adoc @@ -17,7 +17,7 @@ include::{path}/log-in-api.adoc[] A successful login returns a session cookie that can be used in your subsequent API calls. For more information, see xref:api-auth-session.adoc#sessionCookies[Session cookies for subsequent API calls]. [NOTE] ==== -* If MFA [beta betaBackground]^Beta^ is enabled on your ThoughtSpot instance then basic authentication with only `username` and `password` will return an error. +* If MFA is enabled on your ThoughtSpot instance then basic authentication with only `username` and `password` will return an error. Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance. * Embedded users authenticating to ThoughtSpot with basic authentication are recommended to switch to `AuthType.TrustedAuthTokenCookieless`. * MFA can be enabled on your instance only if Identity and Access Management (IAMv2) is already enabled. diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index d01dc1e0f..34cb245bd 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,39 @@ 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]. + +== Version 1.37.0, April 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +The SDK now provides the `customVariablesForThirdPartyTools` setting to pass custom variables when integrating third-party tools and running custom scripts in your embed. Developers can define this object in the **init()** function and add variables as key-value pair. +This feature is available only if third-party integration is enabled on your instance and script hosting domain URL is added to the CSP allowlist. + +For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. + +|[tag greenBackground]#NEW FEATURE# a| +You can now exclude search token string from the application URL by setting `excludeSearchTokenStringFromURL` to `true` in your embed with ThoughtSpot token-based Search or Search bar. + +|[tag greenBackground]#NEW FEATURE# a| This version of the SDK supports the following embed and host events: + +Embed Events:: + +* `EmbedEvent.TableVizRendered` + +Emits when a table visualization is rendered in the ThoughtSpot embedded app. You can also use this event as a hook to trigger host events such as `HostEvent.TransformTableVizData` on the table visualization. For more information, see the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_tablevizrendered[SDK reference documentation]. + +* `EmbedEvent.CreateLiveboard` + +Emits when a Liveboard is created. + +Host Events:: + +* `HostEvent.TransformTableVizData` + +Triggers the table visualization re-render with the updated data. You can use this event in conjunction with `EmbedEvent.TableVizRendered` to apply the modifications to table visualization payload. + +* `HostEvent.Remove` + +Triggers the *Delete* action on a Liveboard. +|==== + == Version 1.36.0, February 2025 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index e1404579e..c9ac295b2 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -20,7 +20,7 @@ In this method, a REST client sends the `username` and `password` to authenticat xref:authentication.adoc#trusted-auth-v2[Trusted authentication];; In this method, the REST client must send the `username` and `secret_key` in the API request to obtain an authentication token. The `secret_key` is generated if **Trusted authentication** is enabled on your ThoughtSpot instance. -Multifactor authentication (MFA):: [beta betaBackground]^Beta^ +Multifactor authentication (MFA):: + ThoughtSpot now supports multifactor authentication (MFA) for environments using local authentication with Identity and Access Management (IAMv2). If MFA is enabled on your ThoughtSpot instance, diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index a9c445bcd..0b055f6ad 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -13,6 +13,7 @@ ** link:{{navprefix}}/embed-sdk-changelog[SDK and API changelog] *** link:{{navprefix}}/embed-sdk-changelog[Visual Embed changelog] +*** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog] *** link:{{navprefix}}/rest-v1-changelog[REST API v1 changelog] *** link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] ** link:{{navprefix}}/deprecated-features[Deprecation announcements] @@ -57,16 +58,23 @@ * link:{{navprefix}}/getting-started[Embed ThoughtSpot] ** link:{{navprefix}}/getting-started[Quickstart Guide] -** link:{{navprefix}}/tsembed[Embed a ThoughtSpot component] -*** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] -*** link:{{navprefix}}/embed-a-viz[Embed a visualization] -*** link:{{navprefix}}/full-embed[Embed full application] -*** link:{{navprefix}}/search-embed[Embed search page] -*** link:{{navprefix}}/embed-nls[Embed Natural Language Search] -*** link:{{navprefix}}/embed-spotter[Embed Spotter] -*** link:{{navprefix}}/embed-searchbar[Embed search bar] +** link:{{navprefix}}/tsembed[Embed ThoughtSpot in Web app] +*** Embed analytics +**** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +**** link:{{navprefix}}/embed-a-viz[Embed a visualization] +*** Embed natural language search +**** link:{{navprefix}}/embed-spotter[Embed Spotter] +**** link:{{navprefix}}/tutorials/spotter/integrate-into-chatbot[Integrate Spotter interface into a Chatbot] +**** link:{{navprefix}}/embed-nls[Embed Natural Language Search (legacy interface)] +*** Embed full app experience +**** link:{{navprefix}}/full-embed[Embed full app] +**** link:{{navprefix}}/full-app-customize[Customize full application embedding] +*** Embed token-based Search +**** link:{{navprefix}}/search-embed[Embed Search] +**** link:{{navprefix}}/embed-searchbar[Embed search bar] *** link:{{navprefix}}/react-app-embed[Embed with React components] - +** Embed ThoughtSpot in a mobile app +*** link:{{navprefix}}/embed-ts-mobile-react-native[Embed using React Native SDK ^Beta^] ** Customize and integrate *** link:{{navprefix}}/style-customization[Customize UX and styles] **** link:{{navprefix}}/customize-style[Customize basic styles] @@ -96,7 +104,6 @@ ***** link:{{navprefix}}/custom-action-payload[Callback response payload] *** link:{{navprefix}}/in-app-navigation[Create dynamic menus and navigation] -*** link:{{navprefix}}/full-app-customize[Customize full application embedding] *** link:{{navprefix}}/customize-links[Customize links] *** link:{{navprefix}}/set-locale[Customize locale] *** link:{{navprefix}}/custom-domain-config[Custom domain configuration] @@ -143,6 +150,7 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/prefetch[Prefetch static resources] *** link:{{navprefix}}/prerender[Prerender components] ** link:{{navprefix}}/security-settings[Security settings] +*** link:{{navprefix}}/external-tool-script-integration[Integrate external tools and scripts] ** Other embedding methods *** link:{{navprefix}}/embed-without-sdk[Embed without SDK] *** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 3b5a379c1..88fa664fa 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -81,7 +81,7 @@ curl -X POST \ ---- === Fetch Liveboard Data API -To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have the `DATADOWNLOADING` (*Can download Data*) privilege and at least view access to the Liveboard specified in the API request. +To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. @@ -191,7 +191,7 @@ Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. === Liveboard Report API -To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need `DATADOWNLOADING` (*Can download Data*) privilege and at least view access to the Liveboard specified in the API request. +To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. In the `POST` request body, specify the GUID or name of the Liveboard as `metadata_identifier`. To download reports with specific visualizations, add GUIDs or names of the visualizations in the `visualization_identifiers`. @@ -227,6 +227,59 @@ curl -X POST \ }' ---- +==== Override filters + +If the Liveboard has filters applied and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. + +[source,JSON] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {access-token}' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG", + "override_filters": [ + { + "column_name": "Color", + "generic_filter": { + "op": "IN", + "values": [ + "almond", + "turquoise" + ] + }, + "negate": false + }, + { + "column_name": "Commit Date", + "date_filter": { + "datePeriod": "HOUR", + "number": 3, + "type": "LAST_N_PERIOD", + "op": "EQ" + } + }, + { + "column_name": "Sales", + "generic_filter": { + "op": "BW_INC", + "values": [ + "100000", + "70000" + ] + }, + "negate": true + } + ], + "png_options": { + "include_cover_page": true, + "include_filter_page": true + } +}' +---- + [#transient-lb-content] ==== Liveboard data with unsaved changes @@ -258,7 +311,7 @@ See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_ge === Answer Report API -To download Answer data via `/api/rest/2.0/report/answer` API, you need `DATADOWNLOADING` privilege and at least view access to the saved Answer. +To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index b0de38bca..6af1317a0 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -10,16 +10,19 @@ As ThoughtSpot applications evolve, some existing features will be deprecated an == Deprecated features -[width="100%" cols="4,5,2,4"] +[width="100%" cols="4,5,4,4"] [options='header'] |===== -|Feature|Impacted interface and release versions|Deprecation announcement date|Deprecation date +|Feature|Impacted interface and release versions|Deprecation date |End of Support / removal from the product +a|xref:deprecated-features.adoc#SageDeprecationNotice[Sage Search and Ask Sage] a| +* ThoughtSpot Cloud 10.13.0.cl and later +* Visual Embed SDK version 1.40.0 and later +| September 2025 | September 2025 a|xref:deprecated-features.adoc#connectionAPIs[Delete and update connection API v2 endpoints] a|REST API v2 + -* ThoughtSpot Cloud 10.4.0.cl and later|November 2024 a| *Deprecated in*: November 2024 + -*End of support*: September 2025 +* ThoughtSpot Cloud 10.4.0.cl and later|November 2024 a| September 2025 |xref:deprecated-features.adoc#IAMv1[IAMv1] a| @@ -41,7 +44,6 @@ a|REST API v2 + * ThoughtSpot Software 10.1.0.sw and later|February 2024| August 2024 |xref:deprecated-features.adoc#_page_title_customization[Page title customization] a|Application UI + - * ThoughtSpot Cloud 10.1.0.cl and later * ThoughtSpot Software 10.1.0.sw and later|February 2024| August 2024 |xref:deprecated-features.adoc#_application_background_customization_via_ui[Application Background style customization] a|Application UI + @@ -71,6 +73,27 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic |||| |===== +[#SageDeprecationNotice] +== Sage and Ask Sage deprecation + +The Sage Search (the legacy Natural Language Search interface) and *Ask Sage* features will be deprecated in version 10.13.0.cl, which is scheduled for release in September 2025. +Along with this, the xref:SageEmbed.adoc[SageEmbed] library in the Visual Embed SDK will also be deprecated. + +//with no new enhancements or bug fixes supported after July 2025. + +Impact on your instance:: +This change will impact all ThoughtSpot instances and applications that use the xref:embed-nls.adoc[Natural Language Search (legacy) interface embedded using the SageEmbed] library in Visual Embed SDK. + +Recommended action:: +Customers using the legacy Natural Language Search interface and *Ask Sage* in their embedding applications are advised to upgrade to Spotter. We recommend that you start using Spotter by the 10.11.0.cl release (July 2025), so that you have sufficient time to test your rollout. + +Spotter provides advanced natural language search capabilities and a conversational interface to allow users to interact with the AI analyst and ask follow-up questions. To know more about Spotter and learn how to embed Spotter in your embedding application, refer to the following documentation: + +* link:https://www.thoughtspot.com/product/ai-analyst[About Spotter, window=_blank] +* xref:embed-spotter.adoc[How to embed Spotter] +* link:https://docs.thoughtspot.com/cloud/latest/spotter[How to use Spotter, window=_blank] ++ +For additional queries and assistance, contact ThoughtSpot Support. + [#connectionAPIs] == Delete and update connection API v2 endpoints The following Connection API v2 endpoints are deprecated and will be removed from the product in September 2025: + @@ -225,7 +248,7 @@ Effective from:: * ThoughtSpot Cloud 8.8.0.cl * ThoughtSpot Software 9.0.1.sw -=== Recommended action:: +=== Recommended action Use the new version of REST API v2.0 endpoints and SDK versions available for these endpoints. For more information, see xref:rest-api-sdk-libraries.adoc[REST API v2.0 SDKs]. ==== Documentation diff --git a/modules/ROOT/pages/embed-authentication.adoc b/modules/ROOT/pages/embed-authentication.adoc index 445780e27..ec2fdd8dc 100644 --- a/modules/ROOT/pages/embed-authentication.adoc +++ b/modules/ROOT/pages/embed-authentication.adoc @@ -68,7 +68,7 @@ a| Do not use this method if you don’t want the SDK to redirect your entire ap * If you want to use local authentication with ThoughtSpot `username` and `password`. * If you are developing or testing code for embedding ThoughtSpot in your host app. a| * Do not use this authentication method in production environments. + -* This authentication will fail if multifactor authentication (MFA) [beta betaBackground]^Beta^ is enabled on your ThoughtSpot instance. Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance. +* This authentication will fail if multifactor authentication (MFA) is enabled on your ThoughtSpot instance. Contact https://community.thoughtspot.com/customers/s/login/?ec=302&startURL=%2Fcustomers%2Fs%2Fcontactsupport[ThoughtSpot Support] for assistance. |===== == User accounts diff --git a/modules/ROOT/pages/embed-nls.adoc b/modules/ROOT/pages/embed-nls.adoc index 9a9d4d4a3..15513f5c8 100644 --- a/modules/ROOT/pages/embed-nls.adoc +++ b/modules/ROOT/pages/embed-nls.adoc @@ -1,4 +1,4 @@ -= Embed Natural Language Search += Embed Natural Language Search (legacy interface) :toc: true :toclevels: 2 @@ -6,13 +6,19 @@ :page-pageid: embed-nls :page-description: You can use the SageEmbed SDK library to embed ThoughtSpot Natural Language Search experience in your application. -ThoughtSpot provides the `SageEmbed` SDK package to embed Natural Language Search experience in your embedding application. ThoughtSpot Natural Language Search supports the following features: -* Ability to pass search text in natural language format as query string +[IMPORTANT] +==== +The legacy Natural Language Search interface, also referred to as `Sage`, will be deprecated in July 2025. Customers who want to embed ThoughtSpot's natural language search interface are advised to upgrade to xref:embed-spotter.adoc[Spotter]. For more information, see the xref:deprecated-features.adoc#SageDeprecationNotice[deprecation notice]. +==== + +ThoughtSpot provides the `SageEmbed` SDK package to help developers embed Natural Language Search (legacy) experience, which supports the following features: + +* Ability to pass natural language queries as search text * AI-generated sample Answers * AI-suggested popular queries -== Natural Language Search components +== Search components The `SageEmbed` package allows you embed the following Search components in your application: diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index bb23ba347..a1e701d43 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -111,7 +111,7 @@ Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderStic Along with xref:Action.adoc[Actions] there is very fine-grained control of the display of the `LiveboardEmbed` component, which can be varied for each user or content object displayed depending on the desires of the app development team. -[widthAuto] +[.widthAuto] image::./images/liveboard_view_config_callouts_2.png[LiveboardViewConfig parameters] The `hideLiveboardHeader` property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only' use cases or rebuilding your own menus and buttons using xref:embed-events.adoc[HostEvents]. diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index b51f8ae85..f37bac490 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -22,8 +22,11 @@ In the new navigation and Home page experience, the app selector image:./images/ [.widthAuto] image::./images/homepage.png[New home page] -The new navigation and Home page experience introduces the following changes: +The new navigation and Home page experience introduces several UI changes. +.View UI changes +[%collapsible] +==== [width="100%", cols="3,7,7"] [options='header'] |===== @@ -99,6 +102,8 @@ a| `\https://{ThoughtSpot-Host}/#/home/monitor-alerts` |Liveboards and Answers| In the classic experience mode, users can use All, Yours, and Favorites tabs to filter the Liveboards and Answers list| In new experience, the Liveboard and Answers list page provides filters for each column. For example, to view their favorite Liveboards, users can click the star icon in the column head and apply a filter to show only their starred (favorite) Liveboards. Similarly, users can filter the list by author to view only their Liveboards or Answers. |===== +[%collapsible] +==== === Enable new experience mode for ThoughtSpot embedding By default, the new navigation and home page experience is turned off on ThoughtSpot embedding applications. To enable the new experience mode for embedding application users, set `modularHomeExperience` to `true` in the `AppEmbed` component. @@ -213,12 +218,12 @@ The following table lists the search components supported in full application em The Object Search bar also appears on the top navigation bar if the top navigation bar visibility is enabled ( `showPrimaryNavbar: true`) in the SDK. -|Natural Language Search a| Allows searching a data source using a natural language query string and get AI-generated Answers. -On instances running 10.3.0.cl or earlier, with split search experience disabled, Natural Language Search will be available along with Object Search on the Home page. However, on instances running 10.3.0.cl or later, split search is enabled by default, and due to this, the Home page will not show Natural Language Search as the default search experience. To enable Natural Language Search for embed users, set `homePageSearchBarMode` to `aiAnswer` in the SDK. +|Natural Language Search (legacy interface) a| Allows searching a data source using a natural language query string and get AI-generated Answers. +On instances running 10.3.0.cl or earlier, with split search experience disabled, the Natural Language Search (legacy interface) will be available along with Object Search on the Home page. However, on instances running 10.3.0.cl or later, split search is enabled by default, and due to this, the Home page will not show Natural Language Search as the default search experience. To enable Natural Language Search for embed users, set `homePageSearchBarMode` to `aiAnswer` in the SDK. For more information, see xref:full-app-customize.adoc#_enable_ai_search_without_spotter[Enable AI Search]. -|Spotter[beta betaBackground]^Beta^ | In addition to AI Search capabilities, Spotter provides a conversation interface for queries and follow-up questions. + +|Spotter | In addition to AI Search capabilities, Spotter provides a conversation interface for queries and follow-up questions. + If Spotter is enabled on your instance, and `homePageSearchBarMode: "aiAnswer"` property is set in the SDK along with split search enabled (`isUnifiedSearchExperienceEnabled: false`), the search experience on the Home page switches to Spotter in full application embed. For more information, see xref:full-app-customize.adoc#_enable_ai_search_with_spotter[Enable AI Search with Spotter]. @@ -355,6 +360,23 @@ Hides the app selector image:./images/app_switcher.png[the app switcher menu]. T ** To hide help and profile icons (Classic experience) + ** To hide help and profile icons, Help and Chat with Support menu options on the Home page (New Experience). +=== Help menu customization +On ThoughtSpot instances running 10.8.0.cl and later, a unified help and support experience is available. The new information center experience provides access to ThoughtSpot documentation and support and allows administrators to link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links]. + +If you have embedded the full ThoughtSpot application with the top navigation bar and Help (?) icon with the `showPrimaryNavbar: true` and `disableProfileAndHelp: false` settings in the Visual Embed SDK and if you want to try the new information center experience, use the xref:AppViewConfig.adoc#_enablependohelp[enablePendoHelp] attribute in the SDK. + +By default, the `enablePendoHelp` attribute is set to `true` for customer environments using the legacy information center generated by Pendo. To enable the new experience, you need to set `enablePendoHelp` to `false`. + +[source,JavaScript] +---- +const embed = new AppEmbed("#embed", { + ... // other options + showPrimaryNavbar: true, + disableProfileAndHelp: false, + enablePendoHelp: false, +}); +---- + === Customize the left navigation panel on Home page (New experience) If the new navigation and Home page experience is enabled and `showPrimaryNavbar` to `true`, the home page displays a navigation panel on the left side of the Insights page. The panel consists of menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and so on. @@ -363,6 +385,7 @@ To hide the left navigation panel in the embedded view, set `hideHomepageLeftNav [source,javascript] ---- const embed = new AppEmbed("#embed", { + ... // other attributes modularHomeExperience: true, showPrimaryNavbar: true, hideApplicationSwitcher: true, diff --git a/modules/ROOT/pages/locale-setting.adoc b/modules/ROOT/pages/locale-setting.adoc index aa6cc2f07..00e49b0b0 100644 --- a/modules/ROOT/pages/locale-setting.adoc +++ b/modules/ROOT/pages/locale-setting.adoc @@ -26,14 +26,17 @@ If you want to set your embedded app view to a specific locale for your applicat | `ar-EG` | Egyptian Arabic | `da-DK` | Dansk | `de-DE` | Deutsch +| `de-CH` | German (Switzerland) | `en-AU` | English (Australia) | `en-CA` | English (Canada) | `en-DE` | English (Germany) | `en-IN` | English (India) | `en-GB` | English (United Kingdom) | `en-US` | English (United States) +| `en-NZ` | English (New Zealand) | `es-US` | Español (Latinoamérica) | `es-ES` | Español (España) +| `es-MX` | Spanish (Mexico) | `fi-FI` | Suomi | `fr-CA` | Français (Canada) | `fr-FR` | Français (France) @@ -106,7 +109,8 @@ The following REST API v1 and v2 endpoints allow updating locale preference for == Limitations -* 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**. + +* 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. + +* ThoughtSpot translates keywords, operators, and error messages. See link:https://docs.thoughtspot.com/cloud/latest/keywords[Keyword reference] for all supported languages. diff --git a/modules/ROOT/pages/mobile-sdk-changelog.adoc b/modules/ROOT/pages/mobile-sdk-changelog.adoc new file mode 100644 index 000000000..fb9978b4b --- /dev/null +++ b/modules/ROOT/pages/mobile-sdk-changelog.adoc @@ -0,0 +1,23 @@ += Mobile Embed SDK Changelog +:toc: true +:toclevels: 2 + +:page-title: Changelog +:page-pageid: mobile-sdk-changelog +:page-description: Changes to the Mobile SDK and APIs + +This changelog lists only the changes introduced in the Mobile Embed SDK. For information about the new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. + +== React Native SDK + +=== Version 0.0.1, April 2025 + +The version 0.0.1 of the React Native Embed SDK [beta betaBackground]^Beta^ provides client libraries to embed a ThoughtSpot Liveboard in native mobile apps for both Android and iOS, using JavaScript and React. + +Along with the Liveboard component, the SDK provides the following features and configuration settings to customize the embedded view: + +* Liveboard and visualization xref:mobilesdk-quick-start.adoc#_customize_menu_actions[menu customization]. +* Style, text string, and icon customization with xref:css-customization.adoc[CSS customization framework]. +* App interactions and custom workflows with xref:EmbedEvent.adoc[Embed events] and xref:HostEvent.adoc[Host events]. + +For more information, see xref:mobilesdk-quick-start.adoc[Embed ThoughtSpot using React Native mobile SDK]. diff --git a/modules/ROOT/pages/mobilesdk-quick-start.adoc b/modules/ROOT/pages/mobilesdk-quick-start.adoc new file mode 100644 index 000000000..c01787fbd --- /dev/null +++ b/modules/ROOT/pages/mobilesdk-quick-start.adoc @@ -0,0 +1,446 @@ += Embed using React Native mobile SDK +:toc: true +:toclevels: 2 + +:page-title: Embed ThoughtSpot using React Native Embed SDK +:page-pageid: embed-ts-mobile-react-native +:page-description: Using React Native embed SDK, you can now embed ThoughtSpot in your mobile apps built for iOS and Andrioid platforms + +ThoughtSpot's React Native Mobile Embed SDK [beta betaBackground]^Beta^ enables developers to embed ThoughtSpot Analytics in their mobile apps. This SDK is designed for the React Native framework to allow developers to build their mobile apps that operate on *iOS* and *Android* platforms, using native resources and a single codebase. + +In its initial release, the React Native Embed SDK supports embedding a Liveboard component and customizing the embed view within the mobile app. + +== Before you begin + +Before you get started, check the following: + +* You have access to a ThoughtSpot instance with the necessary credentials. +* link:https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[NPM and Node.js are installed, window=_blank] on your system. +* Your link:https://reactnative.dev/docs/environment-setup[React Native environment, window=_blank] is set up. +* If you are using Expo to build your application: +** Ensure that the link:https://docs.expo.dev/tutorial/create-your-first-app/[Expo project is created, window=_blank] and imported into your development environment. +** Install the link:https://expo.dev/go[Expo Go, window=_blank] app on your mobile device (iOS or Android) to preview the app. + +== Get started with embedding +This section provides a set of steps to quickly embed a ThoughtSpot xref:faqs.adoc#lbDef[Liveboard] in a mobile app. + +=== Install the SDK + +The latest version of the Mobile Embed SDK for React Native is available at link:https://www.npmjs.com/package/@thoughtspot/react-native-embed-sdk[https://www.npmjs.com/package/@thoughtspot/react-native-embed-sdk, window=_blank]. + +[source,console] +---- +npm install @thoughtspot/react-native-embed-sdk +---- + +=== Import the SDK into your project + +[source,JavaScript] +---- + // NPM + import { LiveboardEmbed, AuthType, init } from '@thoughtspot/react-native-embed-sdk'; +---- + +After you import, you can define the ThoughtSpot host URL from which you want to embed a Liveboard, authentication type and attributes, and Liveboard ID. + +==== File structure in the Expo go sandbox + +In the link:https://snack.expo.dev/@git/github.com/thoughtspot/developer-examples:mobile/react-native-embed-sdk[Expo code sandbox, window=_blank], you'll notice that your mobile embed project has the following files: + +* `Auth.ts` - Includes the code required to get authentication token from ThoughtSpot via REST API SDK. +* `App.tsx` - Includes the code for expo app setup. +* `Home.tsx` - Includes the code for the main screen and the form to populate embed view configuration, the `init` function with the `tsHost` and `username`, Liveboard ID, and custom style specification. +* `LiveboardView.tsx` - Defines the interface configuration properties and event interaction settings for the Liveboard embed view. + +You can use similar files in your project setup or an index file for the ThoughtSpot mobile embed code. + +=== Initialize the SDK and set up authentication + +To initialize the SDK, the following information is required: + +* `thoughtSpotHost` + +The hostname of your ThoughtSpot application instance. For example, `team2.thoughtspot.cloud`. See xref:faqs.adoc#tsHostName[FAQs] to know how to find the hostname of your application instance. +* `authType` + +Authentication type. In the current version, mobile embedding supports only the Cookieless Trusted authentication method (`AuthType.TrustedAuthTokenCookieless`). + +[source,TypeScript] +---- +init({ + thoughtSpotHost: 'ts-host-url', // Replace with your ThoughtSpot host URL + authType: AuthType.TrustedAuthTokenCookieless, + getAuthToken: async () => "full-auth-token" +}); +---- + +=== Add the Liveboard component + +[source,TypeScript] +---- +const TsApp = () => { + return ( + + + + ); +}; +---- + +=== Build your app and preview the embedded content + +* Build your app: ++ +[,bash] +---- +$ npm run build +---- + +* If you are using an Expo project: ++ +. Build your project locally ++ +[,bash] +---- +expo start +---- +. Scan the QR code with the *Expo Go* app to see the app with the embedded content. + +== Customize your embed +Just like the Visual Embed SDK for web application embed, the Mobile Embed SDK provides the following customization options: + +* Control the xref:mobilesdk-quick-start.adoc#_customize_menu_actions[visibility of menu actions in the embedded view] +* xref:mobilesdk-quick-start.adoc#_customize_app_interactions[Customize app interactions and workflows] using events. +* xref:mobilesdk-quick-start.adoc#_customize_styles[Customize the styles and UI layout] of the embedded view + +=== Customize menu actions +By default, the SDK includes a set of menu actions in the embedded view. + +.Default menu actions +[%collapsible] +==== +* **Add filter** (xref:Action.adoc#_addfilter[`Action.AddFilter`]) + +Allows adding filters to the embedded Liveboard +* **Filter** (xref:Action.adoc#_crossfilter[`Action.CrossFilter`]) + +Allows applying filters across all visualizations in a Liveboard. +* **Drill down** (xref:Action.adoc#_drilldown[`Action.DrillDown`]) + +Allows drilling down on a data point in the visualization to get granular details. +* **Personalized view** (xref:Action.adoc#_personalisedviewsdropdown[`Action.PersonalisedViewsDropdown`]) + +The Liveboard personalized views drop-down. +* **Filter** action (xref:Action.adoc#_axismenufilter[`Action.AxisMenuFilter`]) in the chart axis or table column customization menu + +Allows adding, editing, or removing filters on a visualization. +* **Edit** action (xref:Action.adoc#_axismenuedit[`Action.AxisMenuEdit`]) in the axis customization menu. + +Allows editing the axis name, position, minimum and maximum values of a column. +* **Position** action (xref:Action.adoc#_axismenuposition[`Action.AxisMenuPosition`]) in the axis customization menu. + +Allows changing the position of the axis to the left or right side of the chart. +* **Sort** action (xref:Action.adoc#_axismenusort[`Action.AxisMenuSort`]) - Sorts the data in ascending or descending order on a chart or table. +* **Aggregate** (xref:Action.adoc#_axismenuaggregate[`Action.AxisMenuAggregate`]) option in the chart axis or the table column customization menu. + +Provides aggregation options to analyze the data on a chart or table. +* **Conditional formatting** menu option (xref:Action.adoc#_axismenuconditionalformat[`Action.AxisMenuConditionalFormat`]) + +Allows adding rules for conditional formatting of data points on a chart or table. +* The **Group** option (xref:Action.adoc#_axismenugroup[`Action.AxisMenuGroup`]) in the chart axis or table column customization menu. + +Allows grouping data points if the axes use the same unit of measurement and a similar scale. +* The **Remove** option (xref:Action.adoc#_axismenuremove[`Action.AxisMenuRemove`]) in the chart axis or table column customization menu. + +Removes the data labels from a chart or the column of a table visualization. +* The **Rename** option (xref:Action.adoc#_axismenurename[`Action.AxisMenuRename`]) in the chart axis or table column customization menu. + +Renames the axis label on a chart or the column header on a table +* **Time bucket** option (xref:Action.adoc#_axismenutimebucket[`Action.AxisMenuTimeBucket`]) in the chart axis or table column customization menu. + +Allows defining time metric for date comparison. +==== + +To disable or hide a menu action, you must specify the action ID in the `disabledActions`, `visibleActions`, or `hiddenActions` array. To show or hide menu actions, use either `visibleActions` or `hiddenActions`. + +[source,Javascript] +---- +//Add the menu actions to show in the embed view. Removes all actions if the array is empty +visibleActions: [Action.AddFilter,Action.Share,Action.DrillDown,Action.AxisMenuFilter,Action.AxisMenuTimeBucket], +//disable actions +disabledActions: [Action.DrillDown, Action.Edit], +//specify the reason for disabling menu actions +disabledActionReason: "Contact your administrator to enable this feature", +//hiddenActions: [], /* Do not use if `visibleActions` is enabled */ +---- + +[source,Javascript] +---- +//hide specific actions +hiddenActions: [Action.AddFilters], +//disable actions +disabledActions: [Action.DrillDown], +//specify the reason for disabling menu action +disabledActionReason: "Contact your administrator to enable this feature", +//visibleActions: [], /* Do not use if `hiddenActions` is enabled */ +---- + +=== Customize app interactions +To customize app interactions and enable custom workflows with xref:embed-events.adoc[Embed and Host events]. + +The following code adds an event listener for the `authInit` embed event and specifies how to handle the default load when it emits. + +[source,TypeScript] +---- +// Define a component that embeds a Liveboard and handles initial authentication state +const LiveboardEmbedView = () => { + // Declare a loading state to control the loading UI + const [loading, setLoading] = useState(true); + + // Create a ref to interact with the LiveboardEmbed component programmatically + const webViewRef = useRef(null); + + // Function to handle the AuthInit event from the LiveboardEmbed + const handleAuthInit = () => { + alert("Auth Init EmbedEvent"); // Show a simple alert when auth is initialized + setLoading(false); // Set loading to false once authentication is complete + } + + return ( + <> + {loading && Loading...} + {handleAuthInit()}} // Callback when the AuthInit event is fired by the embed + /> + + ); +}; +---- + +Similarly, you can also add a host event to trigger an action or add custom workflow. The following example shows the host events registered to trigger reload and Liveboard Share actions. + +[source,TypeScript] +---- +// Define a component for embedding and interacting with a Liveboard +const LiveboardEmbedView = () => { + // Create a reference to the LiveboardEmbed instance + const webViewRef = useRef(null); + + // Function to reload the embedded Liveboard + const reloadView = () => { + Alert.alert("Reloading") // Show an alert to inform the user + if(webViewRef?.current) { + // Trigger the Reload event on the Liveboard + webViewRef?.current?.trigger(HostEvent.Reload) + } + } + + // Function to open the Share dialog for the Liveboard + const shareView = () => { + if(webViewRef?.current) { + // Trigger the Share event on the Liveboard + webViewRef.current.trigger(HostEvent.Share) + } + } + + // Render buttons for "Reload" and "Share", and the LiveboardEmbed component + return ( + <> + + + Reload + + + Share + + + + + ); +}; +---- + +=== Customize styles +You can use ThoughtSpot's xref:css-customization.adoc[CSS customization framework] to customize the text strings, icons, styles and the UI layout of the embedded view. + +[source,TypeScript] +---- +init({ + // Other attributes such as the host URL, authentication type and so on. + customizations: { + content: { + strings: { + // Custom label for the Filter menu action + "Filter": "Select column", + } + }, + style: { + customCSS: { + variables: { + // Background color of the application + "--ts-var-root-background": "#fef4dd", + // Text color + "--ts-var-root-color": "#4a4a4a", + // Visualization title color + "--ts-var-viz-title-color": "#8e6b23", + // Font family for visualization title + "--ts-var-viz-title-font-family": "'Roboto', 'Helvetica', sans-serif", + // Title text capitalization + "--ts-var-viz-title-text-transform": "capitalize", + // Visualization description text color + "--ts-var-viz-description-color": "#6b705c", + // Font family for description text + "--ts-var-viz-description-font-family": "'Roboto', 'Helvetica', sans-serif", + } + } + } + } +}); +---- + +== Code samples + +The following example shows the minimum code required to embed a Liveboard successfully in a mobile app: + +[source,TypeScript] +---- +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +// Import necessary ThoughtSpot SDK modules +import { AuthType, init, LiveboardEmbed } from '@thoughtspot/react-native-embed-sdk'; + +// Initialize the ThoughtSpot SDK +init({ + thoughtSpotHost: 'ts-host-url', // Replace with your ThoughtSpot host URL + authType: AuthType.TrustedAuthTokenCookieless, //Using cookieless trusted token authentication + getAuthToken: async () => "full-auth-token", //fetch a valid authentication token +}); + +// Add Liveboard component +const TsApp = () => { + return ( + + console.error('Embed error:', error)} // Log any embed errors + /> + + ); +}; + +// Define layout styles +const styles = StyleSheet.create({ + container: { + flex: 1, // Takes up full screen height + marginTop: 50, // Add some space from the top + marginBottom: 30, // Add some space at the bottom + }, +}); + +export default TsApp; // Export the Liveboard component +---- + +In the following code sample, the embedded view is customized to show only *Drill down* (`Action.DrillDown`), *Add filter* (`Action.AddFilter`), and *Share* actions. This code also includes embed events that register event listeners or host events to trigger a response from the app. + +[source,typescript] +---- +import React, { useRef, useState } from 'react'; +import { StyleSheet, View, Text, Alert, TouchableOpacity } from 'react-native'; +// Import ThoughtSpot SDK components and helpers +import { Action, HostEvent, LiveboardEmbed, init, AuthType } from '@thoughtspot/react-native-embed-sdk'; + +// Initialize the ThoughtSpot SDK +init({ + thoughtSpotHost: 'ts-host-url', // Replace with your ThoughtSpot host URL + authType: AuthType.TrustedAuthTokenCookieless, // Using cookieless trusted token authentication + getAuthToken: async () => "full-auth-token", // Fetch authentication token +}); + +// Custom components to display and interact with the ThoughtSpot Liveboard +const LiveboardView = ({ liveboardId }) => { + const [loading, setLoading] = useState(true); // State to track loading (optional) + const webViewRef = useRef(null); // Ref to access the LiveboardEmbed instance + + // Reloads the liveboard when called + const reloadView = () => { + Alert.alert("Reloading") + if (webViewRef?.current) { + webViewRef.current.trigger(HostEvent.Reload); + } + }; + // Triggers the Liveboard sharing action + const shareView = () => { + if(webViewRef?.current) { + webViewRef.current.trigger(HostEvent.Share) + } + }; + + return ( + + {/* The embedded ThoughtSpot Liveboard view */} + setLoading(false)} // If authentication is successful + onError={(error) => Alert.alert("Error", `Error: ${JSON.stringify(error)}`)} // Handle embed errors + onLiveboardRendered={() => Alert.alert("Success", "Liveboard Rendered")} // Notify when Liveboard is rendered + visibleActions={[Action.DrillDown, Action.AddFilter, Action.Share]} // Showm menu actions + fullHeight={true} + /> + {/* Optional control buttons */} + + Reload View + + + Share + + + ); +}; + +// Component that renders the LiveboardView +const TsApp = () => { + return ( + + // Pass the Liveboard ID + + ); +}; + +// Define layout styles +const styles = StyleSheet.create({ + container: { + flex: 1, // Takes up full screen height + marginTop: 50, + marginBottom: 30, + }, +}); + +// Export the component +export default TsApp; +---- + +== Test your app + +. Connect your device to the app, authenticate, and load the Liveboard in your mobile app. ++ +[width="100%", cols="5,5,5"] +|=== +a|[.widthAuto] +[.bordered] +image::./images/mobile-embed.png[Mobile embed view] a|[.widthAuto] +[.bordered] +image::./images/mobile-embed3.png[Mobile embed view] +a|[.widthAuto] +[.bordered] +image::./images/mobile-embed2.png[Mobile embed view] +|=== + +. Select a data point to drill down on a visualization or apply filters. +. Verify the event interactions and workflows. + +== Known limitations + +The following Liveboard view configuration parameters are not supported in mobile embeds: + +* xref:LiveboardViewConfig.adoc#_insertassibling[insertAsSibling] +* xref:LiveboardViewConfig.adoc#_prerenderid[preRenderId] +* xref:LiveboardViewConfig.adoc#_fullheight[fullHeight] +* xref:LiveboardViewConfig.adoc#_donottrackprerendersize[doNotTrackPreRenderSize] + +== Additional resources + +* link:https://github.com/thoughtspot/react-native-mobile-sdk[React Native Mobile Embed SDK GitHub Repository, window=_blank] +* link:https://snack.expo.dev/@git/github.com/thoughtspot/developer-examples:mobile/react-native-embed-sdk[Expo code sandbox, window=_blank] diff --git a/modules/ROOT/pages/onboarding-guide.adoc b/modules/ROOT/pages/onboarding-guide.adoc index 985aa9c42..e350fab3a 100644 --- a/modules/ROOT/pages/onboarding-guide.adoc +++ b/modules/ROOT/pages/onboarding-guide.adoc @@ -20,7 +20,6 @@ Check if you have access to a ThoughtSpot instance. If you don't have a ThoughtS You must add your embedding application domain(s) to the xref:security-settings.adoc[CSP and CORS allowlist] on the **Develop** > **Customizations** > **Security Settings** page in ThoughtSpot. To configure CORS and CSP settings, you need admin or developer privilege (*Has Developer privilege*). ==== - == Create content in ThoughtSpot Building content in ThoughtSpot for embedding is done through ThoughtSpot’s UI, following the same process for an internal business use case. diff --git a/modules/ROOT/pages/orgs.adoc b/modules/ROOT/pages/orgs.adoc index a6acca397..cb08f7658 100644 --- a/modules/ROOT/pages/orgs.adoc +++ b/modules/ROOT/pages/orgs.adoc @@ -149,7 +149,6 @@ The Org ID will be passed in the URL depending on the placement of `{ts-query-pa [NOTE] ==== - * The developers are advised to update their implementation to accommodate the Org ID in the `{ts-query-params}` while setting up the link:https://developers.thoughtspot.com/docs/customize-links[custom links] for their application users. This will enable the users to seamlessly access ThoughtSpot objects across Orgs in a multi-Org setup, without causing any disruption to the current workflow. * The `overrideOrgId` parameter in the SDK can accept the Org ID from the resulting URL as its input value. * The `overrideOrgId` parameter may not work properly with trusted authentication (`AuthType.TrustedAuthToken`) or cookieless authentication (`AuthType.TrustedAuthTokenCookieless`), if `tokenAuthPerOrg` is already enabled on your ThoughtSpot instance. diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 7ba47b993..90662752b 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -221,6 +221,7 @@ a|* ThoughtSpot Cloud release versions: + * ThoughtSpot Software: 10.1.0.sw | v2.11.1 or later a|ThoughtSpot Cloud: 10.6.0.cl | v2.12.1 or later +a|ThoughtSpot Cloud: 10.8.0.cl | v2.13.1 or later |==== For information about new features, breaking changes, and deprecated parameters, see xref:rest-apiv2-changelog.adoc[API changelog]. @@ -300,6 +301,7 @@ For a complete list of methods to use for API requests, see the following resour |`importMetadataTMLAsync`|`POST /api/rest/2.0/metadata/tml/async/import` | `searchMetadata` | `POST /api/rest/2.0/metadata/search` |`updateMetadataHeader`| `POST /api/rest/2.0/metadata/headers/update` +|`updateMetadataObjId`| `POST /api/rest/2.0/metadata/update-obj-id`| .4+| link:https://github.com/thoughtspot/rest-api-sdk/blob/release/sdks/typescript/OrgsApi.md[Orgs, window=_blank] | `createOrg` | `POST /api/rest/2.0/orgs/create` diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index 76662027b..10c7318d0 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -445,6 +445,13 @@ Updates the header attributes of a metadata object. ThoughtSpot Software: __10.7.0.sw or later__ a| +++Try it out+++ + +a| `POST /api/rest/2.0/metadata/update-obj-id` + +Update object IDs for given metadata objects. +|ThoughtSpot Cloud: __10.8.0.cl or later__ + +ThoughtSpot Software: __10.10.0.sw or later__ +a| ++++Try it out+++ |===== -- diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 8a95ee27c..17313ba32 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,45 @@ 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 10.8.0.cl, April 2025 + +=== New API endpoints + +This version introduces the following endpoints: +//// +* `POST /api/rest/2.0/ai/analytical-questions` + +Allows using an existing ThoughtSpot Answer or Liveboard, and include content to improve query response. +//// + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Update object IDs for given metadata objects. + + +[NOTE] +==== +An object ID is a user-defined ID assigned to a ThoughtSpot object in addition to the system-generated GUID. +Note that the object ID generation for metadata objects is disabled by default. If this feature is enabled on your instance, you can use the `POST /api/rest/2.0/metadata/update-obj-id` to assign or update the object ID. +==== + +=== Metadata API + +* The `POST /api/rest/2.0/metadata/search` endpoint now supports the following parameters: + +** `include_discoverable_objects` + +Allows including Answers and Liveboards that are marked as discoverable by the object owner. +** `metadata_obj_id` + +Filters metadata objects by the user-defined object ID. This parameter returns data only if the user-defined object ID feature is enabled on your instance. + +=== TML APIs + +* The `all_orgs_context` parameter in TML import APIs (` /api/rest/2.0/metadata/tml/import` and `/api/rest/2.0/metadata/tml/async/import`) is deprecated and removed from the Playground. Use `all_orgs_override` to define the Org context in your API requests. + +* The TML export API now allows exporting TML content with user feedback received for objects such as AI-generated Answers. The `export_with_associated_feedbacks` attribute is set to `false` by default. + +=== Report APIs +The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. + +For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. + == Version 10.6.0.cl, March 2025 === New metadata API endpoints diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index bec783cb3..24017a229 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -1,5 +1,6 @@ = Security settings :toc: true +:toclevels: 2 :page-title: Security settings :page-pageid: security-settings @@ -79,6 +80,8 @@ Add the domains from which you want to load fonts. Add the domains from which you want to load stylesheets. * *CSP frame-src domains* + Add the iframe source URL domains. +* *CSP script-src domains* +Add the domains from which you want host scripts. For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and allow custom scripts]. [NOTE] ==== diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 6220168d1..bbd82bdcc 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -61,6 +61,8 @@ There are multiple kinds of imports possible: * `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. * `ALL_OR_NONE` imports the objects that validate successfully. * `VALIDATE_ONLY` validates the objects but does not import them. +* `PARTIAL_OBJECT` (only applicable to REST API v2) +imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. @@ -355,6 +357,19 @@ The `export_fqn` attribute is useful when ThoughtSpot has multiple objects with Specifies the schema version to use during TML export. By default, the API request uses v1 schema for Worksheets. If you are using Models, set `export_schema_version` to v2. link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank] are supported as new datasets from 9.10.0.cl onwards. + +=== Additional export options for REST API v2 +Following are some additional attributes which can be set for exporting objects: + +* `include_obj_id_ref` + +When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. + +* `include_guid` + +When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. + +* `include_obj_id` + +When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. + === Export in a batch This API operation supports exporting User, User Group, and Role objects only. To export objects in a batch, set the following additional attributes: @@ -367,6 +382,7 @@ Offsets the API response by the specified number. Batch offset value defines the For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. + == TML modification ThoughtSpot offers a lot of flexibility within its set of xref:intro-thoughtspot-objects.adoc[data objects], and there is no particular hierarchy to TML files, but rather just some rules. Visit this page for detailed information on xref:modify-tml.adoc[TML modification]. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index d9d636e8e..c27c3ce2e 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,34 @@ This page lists new features, enhancements, and deprecated functionality in ThoughtSpot Embedded instances. +== Version 10.8.0.cl + +=== React Native SDK to embed ThoughtSpot in a mobile app [beta betaBackground]^Beta^ +Developers can now embed ThoughtSpot Analytics in their mobile apps using the React Native Embed SDK [beta betaBackground]^Beta^. With the React Native Embed SDK, developers can use native resources and a single codebase to build their mobile app with embedded ThoughtSpot content for both *iOS* and *Android* platforms. + +In the initial release, the SDK supports embedding a Liveboard component and customizing the embedded view. For more information, see xref:mobilesdk-quick-start.adoc[React Native SDK quick start guide]. + +=== External tools and custom script integration + +You can now integrate third-party tools and execute custom scripts within your embed. This feature is disabled by default on ThoughtSpot instances. When enabled, you can use this feature to integrate your preferred analytics and product-guide tools such as Pendo, LogRocket, and Mixpanel into your ThoughtSpot embed. + +While you can inject custom Javascript into your embeds, it is essential to consider the associated security risks and vulnerabilities, such as Cross-site scripting (XSS). Before contacting Support to enable this feature on your instance, assess the potential security risks to your application environment and review your organization's security guidelines. We recommend that you sanitize user data before rendering and ensure that your environment runs scripts from trusted domains only. For more information, see xref:3rd-party-script.adoc[Integrate third-party tools and scripts]. + +==== Recommended action for deployments that use pendoTrackingKey +If you are using the xref:EmbedConfig.adoc#_pendotrackingkey[pendoTrackingKey] setting in the Visual Embed SDK, note that ThoughtSpot will deprecate this attribute six months after the 10.8.0.cl release. While you can continue using `pendoTrackingKey` until its deprecation, we recommend using the xref:3rd-party-script.adoc[external tools integration] feature to integrate your preferred tool for analytics and product guides. For additional information or migration assistance, contact ThoughtSpot Support. + +=== Help menu and information center changes +In the 10.8.0.cl release, ThoughtSpot introduces a unified help and support experience that will eventually replace the information center panel generated by Pendo. +The new information panel provides access to ThoughtSpot documentation and support and also allows you to add custom links. This feature will be enabled gradually on ThoughtSpot instances. + +This change will affect your instance if you have embedded the full ThoughtSpot experience with the top navigation bar and Help (?) icon, using `showPrimaryNavbar: true` and `disableProfileAndHelp: false` settings in the Visual Embed SDK. + +Customer environments currently using the legacy information center during embedded sessions will continue to do so for the next few months to minimize disruption. Your ThoughtSpot Customer Success team will contact you and assist you in migrating to the new experience. + +To facilitate testing and the rollout of the new information center, ThoughtSpot provides the xref:AppViewConfig.adoc#_enablependohelp[enablePendoHelp] SDK flag. By default, the `enablePendoHelp` is set to `true` to ensure that your embedded sessions use the legacy information center generated by Pendo. To enable the new experience, you need to set `enablePendoHelp` to `false`. + +=== Column name localization [beta betaBackground]^Beta^ +ThoughtSpot now supports column name and description aliases in a Worksheet or Model, which can be used for localizing the Search and Answer interfaces. This feature is disabled by default on ThoughtSpot instances. To enable this feature, contact ThoughtSpot support. == Version 10.6.0.cl @@ -140,8 +168,9 @@ For information about REST API enhancements, see xref:rest-apiv2-changelog.adoc[ == Version 10.4.0.cl -=== Spotter AI for conversational analytics - +.Spotter AI for conversational analytics +[%collapsible] +==== ThoughtSpot Spotter [beta betaBackground]^Beta^ enables users to find insights from their data through a conversational interface powered by Generative AI. Spotter functions as your AI Analyst and allows your application users to start a conversation, ask follow-up questions on the results generated by ThoughtSpot, and get the data they need. For more information, see the following pages: @@ -151,43 +180,57 @@ For more information, see the following pages: * xref:spotter-in-custom-chatbot.adoc[Spotter tutorials] [NOTE] -==== The Spotter feature is in beta and disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support. ==== -=== ABAC token generation enhancements +.ABAC token generation enhancements +[%collapsible] +==== To generate a token with custom rules, attributes, and filter conditions for Attribute-Based Access Control (ABAC) [beta betaBackground]^Beta^, you can use the `/api/rest/2.0/auth/token/custom` API endpoint instead of the `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs. For more information, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[Get tokens with custom rules and filter conditions]. +==== -=== Visual Embed Playground enhancements +.Visual Embed Playground enhancements +[%collapsible] +==== The Visual Embed Playground provides several checkboxes and customization settings for ThoughtSpot embed components. You can use these checkboxes to customize your embedded view, view results instantly, and copy code. For more information, see xref:developer-playground.adoc[Visual Embed Playground]. - -=== Models - +==== +.Models +[%collapsible] +==== Models are now available on ThoughtSpot embedded instances. ThoughtSpot recommends using Models as data source objects for Answers and Liveboards instead of Worksheets from 10.4.0.cl release onwards. Worksheets are deprecated in 10.4.0.cl and will be removed from ThoughtSpot in an upcoming release. If you are embedding full ThoughtSpot application or the Data Workspace page in your app, you will notice that the Worksheet creation option is disabled by default. However, existing Worksheets continue to be available and editable. To enable Worksheet creation on your instance, contact ThoughtSpot Support. - -=== Orgs enablement +==== +.Orgs enablement +[%collapsible] +==== Starting with ThoughtSpot Cloud 10.4.0.cl release, Orgs will be enabled by default on all new ThoughtSpot instances. Your environment remains a single-tenant instance until you create Orgs. If the Orgs feature is enabled on your instance, you can switch to a single-tenant mode anytime by deleting the Orgs and using just the Primary Org. For more information, see xref:orgs.adoc[Multi-tenancy with Orgs]. - -=== Visual Embed SDK - +==== +.Visual Embed SDK +[%collapsible] +==== For information about the new features and enhancements introduced in Visual Embed SDK version 1.34.x, see xref:api-changelog.adoc[Visual Embed changelog]. - -=== REST API +==== +.REST API +[%collapsible] +==== For information about REST API enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +==== -=== Feature deprecations +.Feature deprecations +[%collapsible] +==== The Search Assist feature for Worksheets and the **Enable Search Assist** checkbox in Search Embed Playground are removed from ThoughtSpot in 10.4.0.cl. If your embedding application uses the `enableSearchAssist` property, you may want to update your deployment. For more information, see xref:deprecated-features.adoc#_search_assist[Deprecated features]. +==== == Version 10.3.0.cl diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 10e431193..05a60fc48 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -35,10 +35,16 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.6.0.cl', + label: '10.8.0.cl', link: ' ', subLabel: 'Cloud (Latest)', }, + { + label: '10.6.0.cl', + link: ' ', + subLabel: 'Cloud', + iframeUrl: 'https://developer-docs-10-6-0-cl.vercel.app/docs', + }, { label: '10.1.0.sw', link: '10-1-0-sw', diff --git a/static/doc-images/images/csp-script-domain.png b/static/doc-images/images/csp-script-domain.png new file mode 100644 index 000000000..2795015a8 Binary files /dev/null and b/static/doc-images/images/csp-script-domain.png differ diff --git a/static/doc-images/images/mobile-embed.png b/static/doc-images/images/mobile-embed.png new file mode 100644 index 000000000..173341c90 Binary files /dev/null and b/static/doc-images/images/mobile-embed.png differ diff --git a/static/doc-images/images/mobile-embed2.png b/static/doc-images/images/mobile-embed2.png new file mode 100644 index 000000000..5b668a152 Binary files /dev/null and b/static/doc-images/images/mobile-embed2.png differ diff --git a/static/doc-images/images/mobile-embed3.png b/static/doc-images/images/mobile-embed3.png new file mode 100644 index 000000000..8c3d798eb Binary files /dev/null and b/static/doc-images/images/mobile-embed3.png differ diff --git a/static/doc-images/images/mobile-emed.png b/static/doc-images/images/mobile-emed.png new file mode 100644 index 000000000..ae6e5fa67 Binary files /dev/null and b/static/doc-images/images/mobile-emed.png differ