diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 1f4823429..627387ddc 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,69 @@ 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.41.0, September 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*React component for Spotter Agent embed* + +The Visual Embed SDK now supports embedding Spotter Agent feature without a body or Spotter interface in a React app. For ease of implementation, the SDK also provides a custom React hook, `useSpotterAgent`. + +For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Spotter Agent embedding in a React app]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter embed* + +The following event handlers are now available for Spotter embed: + +* `EmbedEvent.SpotterInit` + +Fires when Spotter embed component rendering is initialized. +* `EmbedEvent.QueryChanged` + +Fires when the Spotter query is updated by the user. +* `HostEvent.AskSpotter` + +Triggers *Ask Spotter* action for visualizations. +* `HostEvent.GetParameters` + +Triggers the action to fetch runtime Parameters applied on a visualization. +* `HostEvent.UpdateParameters` + +Triggers the action to update runtime Parameters for a Spotter-generated Answer. +* `HostEvent.GetTML` + +Triggers the action to get TML representation of a Spotter-generated Answer. + +For more information, see xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a|*Event handlers for Spotter Agent embed* + +You can now use the following host events in Spotter Agent embedding: + +- `HostEvent.DownloadAsCsv` + +Triggers the action to download a Spotter-generated Answer in CSV format. +- `HostEvent.DownloadAsPng` + +Triggers the action to download a Spotter-generated Answer in PNG format. +- `HostEvent.DownloadAsXlsx` + +Triggers the action to download a Spotter-generated Answer in XLSX format. +- `HostEvent.DownloadAsPdf` + +Triggers the action to download the PDF version of a Spotter-generated Answer. +- `HostEvent.Pin` + +Triggers the action to add a Spotter-generated Answer to a Liveboard. +- `HostEvent.Save` + +Triggers the *Save* action for a Spotter-generated Answer. + +For more information, see xref:HostEvent.adoc[HostEvent]. + +|[tag greenBackground]#NEW FEATURE# a| *Lazy loading of visualizations on an embedded Liveboard* + +You can now use the `lazyLoadingForFullHeight` parameter with the `fullHeight` to progressively load visualizations on an embedded Liveboard. When both these attributes are enabled, only the visualizations in the current viewport are loaded initially, while the other visualizations load as the user scrolls the Liveboard page. + +You can also set the margin property for lazy loading to define when the visualization should load. + +For more information, see xref:lazy-loading-fullheight.adoc[Lazy loading of visualizations in an embedded Liveboard]. + +|[tag greenBackground]#NEW FEATURE# a| *Full application embed* + + +You can now enable the persona-based left navigation panel and home page experience on your ThoughtSpot instance. This feature disabled by default on ThoughtSpot instances and is available for Early Access. when it's enabled on your ThoughtSpot instance, you can roll out the new experience on embedding applications by configuring the xref:AppViewConfig.adoc#_discoveryexperience[`discoveryExperience`] attribute. + +When enabled, the left navigation panel organizes the application menu into persona-based contextual sections. For example, the *Insights* icon for business users, the *Data Workspace* icon for Analysts and Data engineers, and the *Develop* icon for developers. Your application users can navigate to each option using the tabs in the left navigation panel. The new interface also provides a slider to allow users to view or hide the left navigation panel. +|==== + == Version 1.40.0, July 2025 [width="100%" cols="1,4"] @@ -73,19 +136,7 @@ To use these attributes effectively in embedded applications, your ThoughtSpot i ==== |==== -//// -TBD 10.12 events - -- `HostEvent.AnswerChartSwitcher` -- `HostEvent.AskSpotter` -- `HostEvent.DeleteLastPrompt` -- `HostEvent.EditLastPrompt` -- `HostEvent.PreviewSpotterData` -- `HostEvent.ResetSpotterConversation` -- `HostEvent.SpotterSearch` - -//// == Version 1.39.0, July 2025 diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 39575944d..31be01c9c 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -62,9 +62,9 @@ *** Embed analytics **** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] **** link:{{navprefix}}/embed-a-viz[Embed a visualization] -*** Embed AI Search and Analytics +*** link:{{navprefix}}/embed-ai-search-analytics[Embed AI Search and Analytics] **** link:{{navprefix}}/embed-spotter[Embed Spotter] -**** link:{{navprefix}}/tutorials/spotter/integrate-into-chatbot[Integrate Spotter interface into a Chatbot] +**** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] **** link:{{navprefix}}/embed-nls[Embed Natural Language Search (legacy interface)] *** Embed full app experience **** link:{{navprefix}}/full-embed[Embed full app] @@ -110,25 +110,7 @@ *** 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}}/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]# - +** link:{{navprefix}}/security-settings[Security settings] ** link:{{navprefix}}/embed-auth[Authentication] *** link:{{navprefix}}/trusted-auth[Trusted authentication] **** link:{{navprefix}}/trusted-auth-secret-key[Secret key management] @@ -147,13 +129,31 @@ include::generated/typedoc/CustomSideNav.adoc[] **** link:{{navprefix}}/abac-user-parameters-beta[ABAC via tokens (pre-10.4.0.cl)] **** link:{{navprefix}}/rls-rules[RLS Rules] *** link:{{navprefix}}/selective-user-access[User access] -** link:{{navprefix}}/best-practices[Optimize app performance] +** link:{{navprefix}}/best-practices[Performance optimization] *** link:{{navprefix}}/best-practices[Best practices] -*** 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] +*** link:{{navprefix}}/lazy-load-fullHeight[Full height and lazy loading options] +*** link:{{navprefix}}/prefetch[Prefetch static resources] +** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] *** link:{{navprefix}}/pendo-integration[Pendo integration with embed] +** 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]# ** Other embedding methods *** link:{{navprefix}}/embed-without-sdk[Embed without SDK] *** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] @@ -166,6 +166,7 @@ include::generated/typedoc/CustomSideNav.adoc[] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] ** link:{{navprefix}}/connections[Connections] +*** link:{{navprefix}}/connection-config[Connection configuration] ** link:{{navprefix}}/rest-apiv2-getstarted[REST API v2.0] *** link:{{navprefix}}/rest-apiv2-getstarted[Get started] *** link:{{navprefix}}/api-authv2[REST API v2.0 authentication] diff --git a/modules/ROOT/pages/connection-config.adoc b/modules/ROOT/pages/connection-config.adoc new file mode 100644 index 000000000..8ace0f9ae --- /dev/null +++ b/modules/ROOT/pages/connection-config.adoc @@ -0,0 +1,109 @@ += Connection configuration +:toc: true +:toclevels: 2 + +:page-title: Data connection configuration APIs +:page-pageid: connection-config +:page-description: The connection API endpoints allow you to query multiple data configurations per connection used for live query services on a ThoughtSpot instance + +ThoughtSpot supports multiple configurations per connection feature allowing developers to define and manage several distinct connection configurations under a single data connection object in ThoughtSpot. This is currently supported for Snowflake, Databricks, and BigQuery. + + +== Connection Configuration APIs +The connection configuration API endpoints allow you to create, edit, delete, and search connection configuration for an existing data connection on a ThoughtSpot instance. + +=== Required permissions + +You must have data management permissions to create, search, update, and delete connection configuration objects. Make sure your user account has the `DATAMANAGEMENT` privilege. + +If xref:roles.adoc[Role-Based Access Control (RBAC)] is enabled on your ThoughtSpot cluster, the `CAN_CREATE_OR_EDIT_CONNECTIONS` *(Can create/edit Connections)* privilege is required. + +=== Create connection configuration + +To create a connection configuration to an existing data connection object in ThoughtSpot, send a `POST` request to the +`POST /api/rest/2.0/connection-configurations/create` API endpoint. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description + +|`name` a|__String__. Required. Name of the connection configuration. +|`description` a|__String__. Optional. Description of the connection configuration. +|`connection_identifier` a|__String__. Required. Unique ID of the connection for which the configuration will be created. +|`authentication_type` a|__String__. Optional. Type of authentication used for the connection. Default value is `SERVICE_ACCOUNT`. +|`configuration` a|__String__. Required. A JSON map of the connection configuration attributes. For example, + +"configuration": {"accountName":"DEMO_SNOWFLAKE","user":"DEMO_USER","password":"Password@1234","role":"DEMO_ROLE","warehouse":"DEV_WH"}, +|`policy_type` a|__String__. Optional. Policy type in connection configuration APIs determines how a specific configuration is assigned and used. Default value is `NO_POLICY`. The main policy types are: + +* *NO_POLICY:* The configuration is saved but not assigned to any users, groups, or processes. + +* *PRINCIPALS:* The configuration is assigned to specific users and groups, allowing only them to use this configuration. + +* *PROCESSES:* The configuration is assigned for use by specific processes, such as search indexing or row count statistics jobs. +|`policy_principals` a|__String__. Required when the `policy_type` is `PRINCIPALS`. The users or groups which can access and use the connection for querying data. A sample value for this could be, + +"policy_principals": [ +"testuser", +"98617aac-9643-4e94-a2d7-8e4b2c8e8175" +] +|`policy_processes` a|__String__. Required when the `policy_type` is `PROCESSES`. Processes which can use the connection. Valid values include: + + +* `SAGE_INDEXING` +* `ROW_COUNT_STATS` + +|===== + +=== Search a connection configuration +To create a connection configuration to an existing data connection object in ThoughtSpot, send a `POST` request to the `POST /api/rest/2.0/connection-configurations/search` API endpoint. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`connection_identifier` a|__String__. Required. Unique ID of the connection. To get a list of all configurations available in the ThoughtSpot system, send the API request with only the connection name or GUID in the request body. +|`configuration_identifier` a|__String__. Optional. Unique ID of the configuration. Specify the configuration object name or GUID to fetch the details for it. +|`policy_type` a|__String__. Optional. The type of policy associated with the configuration object. +|===== + +=== Update a connection configuration +To update an existing connection configuration in ThoughtSpot, send a `POST` request to the `POST /api/rest/2.0/connection-configurations/{configuration_identifier}/update` API endpoint. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`configuration_identifier` a|__String__. Required. Unique ID of the configuration to be updated. +|`connection_identifier` a|__String__. Required. Unique ID of the connection object. +|`name` a|__String__. Optional. The name of the configuration. +|`description` a|__String__. Optional. The description for the configuration. +|`authentication_type` a|__String__. Optional. Type of authentication used for the connection. +|`policy_type` a|__String__. Optional. The type of policy associated with the configuration object. +|`disable` a|__Boolean__. Optional. Indicates whether a configuration is enabled or disabled. +|`policy_principals` a|__String__. Required when the `policy_type` is `PRINCIPALS`. +|`policy_processes` a|__String__. Required when the `policy_type` is `PROCESSES`. +|===== + +=== Delete connection configuration +To delete an existing connection configuration from ThoughtSpot, send a `POST` request to the `POST /api/rest/2.0/connection-configurations/delete` API endpoint. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`configuration_identifier` a|__String__. Required. Unique ID of the configuration to be deleted. +|`connection_identifier` a|__String__. Required. Unique ID of the connection object for the configuration to be deleted. +|===== + +== Additional Resources +* xref:connections.adoc[Connections] +* xref:rest-api-v2-reference.adoc[REST APIs v2] \ No newline at end of file diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index 3772d309b..ad7efa1b3 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -613,6 +613,27 @@ To understand the metadata API endpoints, see the following pages: * https://developers.thoughtspot.com/docs/catalog-and-audit[REST APIs v1, window=_blank] * https://developers.thoughtspot.com/docs/rest-apiv2-reference#_metadata[REST APIs v2, window=_blank] +== Connection Configuration +ThoughtSpot supports multiple configurations per data Connection. This feature allows data engineers to define and manage several distinct Connection configurations under a single data Connection object in ThoughtSpot. + +For more information about this feature and its APIs, see xref:connection-config.adoc[Connection Configuration]. + +== Custom Calendar + +ThoughtSpot supports creation and management of custom calendars for a given Connection object. For more information, see the following APIs and related documentation in the REST API v2 Playground: + +* `POST /api/rest/2.0/calendars/create` + +Creates a custom calendar. +* `POST /api/rest/2.0/calendars/generate-csv` + +Exports a custom calendar in the CSV format. +* `POST /api/rest/2.0/calendars/search` + +Gets custom calendars for the connection ID specified in the API request. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/delete` + +Deletes a custom calendar. +* `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + +Updates a custom calendar. + + //// [#cre-connection] diff --git a/modules/ROOT/pages/customize-css-styles.adoc b/modules/ROOT/pages/customize-css-styles.adoc index 47de73e86..12bfe2a78 100644 --- a/modules/ROOT/pages/customize-css-styles.adoc +++ b/modules/ROOT/pages/customize-css-styles.adoc @@ -174,6 +174,7 @@ Use the following variables to customize the Liveboard page elements. |Variable|Description |`--ts-var-liveboard-edit-bar-background`| Background color of the edit panel on the Liveboard. The edit panel is displayed when the Liveboard is in edit mode. |`--ts-var-liveboard-cross-filter-layout-background`| Background color of the cross-filter layout. +|`--ts-var-liveboard-layout-background`| Background color of the Liveboard. |====== [.bordered] @@ -181,6 +182,33 @@ Use the following variables to customize the Liveboard page elements. -- image::./images/custom-css-viz.png[CSS customization Liveboard page] -- +[#grp-style] +=== Liveboard grouping and styling +Use the following variables to customize the Liveboard visualization groups and style elements. + +[NOTE] +==== +To enable this feature, set `isLiveboardStylingAndGroupingEnabled` to `true`. +==== + +[width="100%" cols="7,7"] +[options='header'] +|====== +|Variable|Description +|`--ts-var-liveboard-group-background`| Background color of the group. +|`--ts-var-liveboard-group-title-font-color`| Color of the group title. +|`--ts-var-liveboard-group-border-color`| Color of the border for the group. +|`--ts-var-liveboard-group-description-font-color`| Color of the group description text. +|`--ts-var-liveboard-group-tile-title-font-color`| Color of the title of the vizualizations in the group. +|`--ts-var-liveboard-group-tile-description-font-color`| Color of the description of the vizualizations in the group. +|====== + +[.bordered] +[.widthAuto] +-- +image::./images/lb-grp-styling.png[CSS customization for Liveboard groups] +-- + [#vizStyle] == Visualization and Answer diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index 378915b25..2a758389f 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -79,8 +79,7 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic |September 2022| January 2023 |||| |===== - - + == Worksheet deprecation and removal Starting with 10.4.0.cl, Worksheets are deprecated and disabled by default in ThoughtSpot. In ThoughtSpot Cloud 10.12.0.cl and later versions, the ability to create new Worksheets will be removed, and all existing Worksheets will be automatically migrated to Models. @@ -112,7 +111,7 @@ When the REST API v1 Playground is no longer available in the ThoughtSpot UI, us [#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. +The Sage Search (the legacy Natural Language Search interface) and *Ask Sage* features are deprecated from 10.11.0.cl and will be removed from the product in December 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. diff --git a/modules/ROOT/pages/embed-ai-analytics.adoc b/modules/ROOT/pages/embed-ai-analytics.adoc new file mode 100644 index 000000000..6765aeae0 --- /dev/null +++ b/modules/ROOT/pages/embed-ai-analytics.adoc @@ -0,0 +1,75 @@ += Embed AI Search and Analytics +:toc: true +:toclevels: 3 + +:page-title: Embed AI Search and Analytics +:page-pageid: embed-ai-search-analytics +:page-description: To embed ThoughtSpot Spotter and conversational analytics experience in your app, you can use the `SpotterEmbed` or `SpotterAgentEmbed` SDK library. + +ThoughtSpot Spotter provides an interactive AI-powered Search and conversation analytics experience for its application users. With ThoughtSpot Spotter, users can query data in plain language, ask follow-up questions, and get insights directly from their data. ThoughtSpot also provides an agentic version of Spotter for a more advanced experience with context-based conversations and responses for deeper analysis. + +== Embed components +For embedding applications, ThoughtSpot provides two distinct SDK libraries to embed Spotter capabilities in their app: + +* xref:embed-spotter.adoc[`SpotterEmbed`] + +To embed the full Spotter interface with a conversation panel that allows natural language text strings, data source selection, and interactions with AI-generated Answers, use the `SpotterEmbed` component. +For more information, see xref:embed-spotter.adoc[Embed Spotter]. +* xref:embed-spotter-agent.adoc[`SpotterAgentEmbed`] + +The Spotter Agent embedding, also known as `bodyless` embed, allows you to integrate natural language data search and analysis into your own applications or chatbot. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, the `SpotterAgentEmbed` component is designed for deeper customization, allowing full control over the look and feel and workflow of the embedded analytics experience. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations. + +[NOTE] +==== +* The `ConversationEmbed` and `BodylessConversation` components are deprecated and replaced with `SpotterEmbed` and `SpotterAgentEmbed` respectively in Visual Embed SDK v1.38.0 and later. +* If you are embedding full ThoughtSpot experience in your app via `AppEmbed`, you must enable new home page experience and set the home page search bar mode to `aiAnswer` to view Spotter components. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding]. +==== + +== Spotter embed and Spotted Agent embed comparison + +[width="100%" cols="7,5,5"] +[options='header'] + +|===== +| +| Spotter embed +| Spotter Agent embed (Bodyless/Agent) + +|Use case +|Use this method to integrate the built-in AI search and conversation analytics interface in your app. +|Use this method to embed Spotter Search capabilities in your chatbot, virtual agent or an app with your own interface elements and user-experience. + +| Embedding component +| Use `SpotterEmbed` component in the Visual Embed SDK library +| Use `SpotterAgentEmbed` component in the Visual Embed SDK library + +| Data context +a| * Supported data object is Model + + * Allows data source selection +a| * Supported data object is Model + * Data source is passed in the code. No explicit selection is allowed unless the embedding application UI allows it. + +| Customization +| The SDK provides several props, object properties, CSS and text customization options for branding and styling, event handlers for host and embed app interaction, and menu action configuration +| The SDK provides limited customization options as the UI/UX controlled by host application. + +| Sample Questions +| The SDK provides the ability to show or hide sample questions via `hideSampleQuestions`. +| Not applicable +|===== + +== Customization options in the SDK + +Visual Embed SDK provides several view configuration settings and customization options for customizing Spotter embeds: + +* Configuration properties to enable or disable features. +For more information, see xref:_spotterembedviewconfig.adoc[SpotterEmbedViewConfig] and xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig] +* Action customization framework to show or hide actions in the embedded view + +For more information, see xref:Action.adoc[Action] and xref:embed-action-ref.adoc[Action IDs in the SDK] +* Event handlers for host and embed app interaction + +For more information, see xref:EmbedEvent.adoc[Embed events], xref:HostEvent.adoc[Host events], and xref:embed-events.adoc[Events and app interactions] +* Style customization framework for customizing styles, text strings, and icons + +See xref:css-customization.adoc[style customization framework] + + +== Additional resources +* link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] +* link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 19d1ee39a..610e448b2 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -500,6 +500,12 @@ liveboardEmbed.trigger(HostEvent.UpdateFilters, { //// +=== Liveboard grouping and styling +You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. +To enable this feature, set `isLiveboardStylingAndGroupingEnabled` to `true`. 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 diff --git a/modules/ROOT/pages/embed-spotter-agent.adoc b/modules/ROOT/pages/embed-spotter-agent.adoc index 170684b48..d8d53c6eb 100644 --- a/modules/ROOT/pages/embed-spotter-agent.adoc +++ b/modules/ROOT/pages/embed-spotter-agent.adoc @@ -6,192 +6,15 @@ :page-pageid: embed-spotter-agent :page-description: You can use the SpotterAgentEmbed SDK library to embed Spotter experience in your application. -Spotter Agent is an embeddable AI analyst component from ThoughtSpot that enables you to integrate natural language data search and analysis into your own applications. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, Spotter Agent is designed for deeper integration and customization. It allows you to build your own UI or agent experience, broker user questions to ThoughtSpot, and receive structured answers and visualizations, giving you full control over the look, feel, and workflow of the embedded analytics experience. - -== How is Spotter Agent Embedding Different from Spotter Embed? - -* Spotter embed provides a pre-built search bar and interface for quick embedding. -* Spotter Agent embedding is intended for custom agent or chatbot experiences, letting you control the UI and workflow while leveraging ThoughtSpot’s AI-powered analytics engine. - -== Prerequisites - -* Access to a ThoughtSpot instance. -* Your application domain must be allowlisted in ThoughtSpot CSP and CORS settings. -* Admin or developer privileges in ThoughtSpot. -* A worksheet or table to use as the data source. - -== Install the Visual Embed SDK - -[source,bash] ----- -npm install @thoughtspot/visual-embed-sdk ----- - -== Import the SDK and Components - -[source,js] ----- -import { AuthType, init } from '@thoughtspot/visual-embed-sdk'; -import { SpotterAgentEmbed, SpotterAgentViewConfig } from '@thoughtspot/visual-embed-sdk/react'; ----- - -== Initialize the SDK - -[source,js] ----- -init({ - thoughtSpotHost: 'https://', - authType: AuthType.None // Or AuthType.TrustedAuthToken, etc. -}); ----- - -== Configure SpotterAgentViewConfig - -[source,js] ----- -const viewConfig = { - worksheetId: '', // Required: Data source object ID - searchQuery: 'sales by region', // Optional: Initial query - runtimeFilters: [ - { - columnName: 'region', - operator: 'EQ', - values: ['West'] - } - ], // Optional: Pre-filtered context - visibleActions: [ - 'Action.Save', - 'Action.Download', - 'Action.DownloadAsPDF' - ], // Optional: Show only these actions - disabledActions: [ - 'Action.Download' - ], // Optional: Disable specific actions - disabledActionReason: { - 'Action.Download': 'Download is not allowed for this user' - }, // Optional: Tooltip for disabled actions - hideSourceSelection: true, // Optional: Hide data source selector - disableSourceSelection: false, // Optional: Disable data source selection - locale: 'en-US', // Optional: Set locale - showSpotterLimitations: false, // Optional: Show Spotter limitations - hideSampleQuestions: true // Optional: Hide sample questions -}; ----- - -== Embed the Spotter Agent - -[source,jsx] ----- - console.log('Spotter Agent loaded')} - onInit={() => console.log('Spotter Agent initialized')} -/> ----- - -== Register and Handle Events - -You can handle Spotter Agent events for analytics and integration. - -[source,jsx] ----- - ----- - -*Common events include:* -- `onLoad`: Fires when Spotter Agent is loaded. -- `onInit`: Fires when Spotter Agent is initialized. -- `onData`: Fires when data is returned from a query. -- `onError`: Fires on error. - -== Customizing the UI - -* Use `visibleActions`, `hiddenActions`, and `disabledActions` in the config to control menu actions. Do not use both `visibleActions` and `hiddenActions` at the same time [1], [2], [3]. -* To apply custom styles, use CSS variables such as: -+ -[source,css] ----- -:root { - --ts-var-spotter-input-background: #f5f5f5; - --ts-var-spotter-prompt-background: #e0e0e0; -} ----- - - -== Test the Embedded Spotter Agent - -* Start your app. -* Verify Spotter Agent loads and is interactive. -* Confirm initial query and runtime filters are applied. -* Test event handlers and UI customizations. - -== Additional Notes - -* Use only `answerId` for event tracking in SpotterAgentEmbed. -* SpotterAgentEmbed supports both host and embed events for two-way communication. -* For advanced use, refer to the official SDK and API documentation. - - - - - - - - - - - - - - - - - - - - - - - -//// - -== Runtime Filters - -* Pass runtime filters in the `runtimeFilters` array in the config. -* Filters are applied to the initial query and search suggestions. -* Invalid filters are handled gracefully (error message or ignored). - - -ThoughtSpot supports Natural Language Search queries and AI-generated Answers. With ThoughtSpot Spotter, this experience is further enhanced to provide a conversational interface for users to query data, ask follow-up questions, and get insights. - -Visual Embed SDK offers several options to seamlessly embed conversational analytics within your applications and customize the interface and experience as per your organization's branding guidelines. - -To integrate Spotter capabilities into other apps, ThoughtSpot provides the following components: - -* To embed the full Spotter interface with a conversation panel that allows natural language text strings, data source selection, and interactions with AI generated Answers, use the `SpotterEmbed` component. + - -* To integrate Spotter Agent capabilities in a chatbot, use the `SpotterAgentEmbed` component. + - -[NOTE] -==== -The `ConversationEmbed` and `BodylessConversation` components are deprecated and replaced with `SpotterEmbed` and `SpotterAgentEmbed` respectively in Visual Embed SDK v1.38.0 and later. -==== - -This article describes how to embed the Spotter interface using the `SpotterEmbed` component. For information about how to integrate Spotter Agent capabilities without body in a chatbot, see xref:spotter-in-custom-chatbot.adoc[Integrate Spotter into your chatbot]. +Spotter Agent is an embeddable AI analyst component from ThoughtSpot that enables you to integrate natural language data search and conversation analytics into your own application. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, Spotter Agent is designed for deeper integration and customization. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations, allowing full control over the look, feel, and workflow of the embedded analytics experience. == Before you begin Before you begin, check the following: -* Spotter is enabled on your ThoughtSpot instance. +* You have a ThoughtSpot instance with Spotter Agent enabled. * You have access to the latest version of the Visual Embed SDK or at least v1.33.1. +* Your host application domain is added to ThoughtSpot CSP and CORS allowlists. == Import the SDK package @@ -201,7 +24,7 @@ Import the `SpotterEmbed` SDK library to your application environment: [source,JavaScript] ---- import { - SpotterEmbed, + SpotterAgentEmbed, AuthType, init, prefetch, @@ -214,7 +37,7 @@ from '@thoughtspot/visual-embed-sdk'; ----