From 6cd1523e59d161e6ec286a23a37192ad5bfc163f Mon Sep 17 00:00:00 2001 From: ShashiSubramnya Date: Fri, 24 Nov 2023 13:09:57 +0530 Subject: [PATCH 01/32] transfer ownership api update --- modules/ROOT/pages/user-api.adoc | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/user-api.adoc b/modules/ROOT/pages/user-api.adoc index b50d80a2c..0a6dd50ea 100644 --- a/modules/ROOT/pages/user-api.adoc +++ b/modules/ROOT/pages/user-api.adoc @@ -1248,6 +1248,7 @@ curl -X POST \ 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/updatepreference' ---- + .**Request URL** ---- https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/updatepreference @@ -1336,7 +1337,15 @@ POST /tspublic/v1/user/transfer/ownership |Query parameter|Description |`fromUserName`|__String__. Username to transfer from. |`toUserName`|__String__. Username to transfer to. -|`objectid`|__String__. A JSON array of ThoughtSpot object IDs. +|`objectsID` + +__Optional__ a|__Array of strings__. A JSON array of ThoughtSpot object IDs. + + +* Example with multiple object IDs: + +`[7589cbdb-eb50-4d8c-89e7-08e8f4573a5d,84481cda-f92e-4ba5-a1ef-366eb61017f5,5f9bc462-eca8-4b12-b8da-36474664eada]` +* Example with a single object ID: + +`[7589cbdb-eb50-4d8c-89e7-08e8f4573a5d]` + +If you do not specify the object IDs, all the objects owned by the user specified in `fromUserName` will be transferred to the user specified in `toUserName`. |==== === Example request @@ -1344,16 +1353,15 @@ POST /tspublic/v1/user/transfer/ownership .**cURL** [source,cURL] ---- -curl -X POST \ ---header 'Content-Type: application/json' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1' +curl -X POST +--header 'Content-Type: application/json' / +--header 'Accept: application/json' / +'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=User3&toUserName=tsadmin&objectsID=%5B%228e7d27c5-d4e8-494e-8c13-196a9961ffa1%22%2C%220c68a0a1-930b-4ba0-b7a0-59ea49b09848%22%5D' ---- .**Request URL** ---- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=guest&toUserName=guest1 +https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/transfer/ownership?fromUserName=testUser3&toUserName=tsadmin&objectsID=%5B%228e7d27c5-d4e8-494e-8c13-196a9961ffa1%22%2C%220c68a0a1-930b-4ba0-b7a0-59ea49b09848%22%5D ---- === Example response From 81ee5dccb9740a851227063cab03ce213dcf6020 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <76986173+ShashiSubramanya@users.noreply.github.com> Date: Tue, 21 Nov 2023 22:55:18 +0530 Subject: [PATCH 02/32] broken link fix --- modules/ROOT/pages/trusted-authentication.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/trusted-authentication.adoc b/modules/ROOT/pages/trusted-authentication.adoc index b0f1c1b1d..56c5c96af 100644 --- a/modules/ROOT/pages/trusted-authentication.adoc +++ b/modules/ROOT/pages/trusted-authentication.adoc @@ -18,7 +18,7 @@ image::./images/trusted-auth-workflow.png[Trusted Authentication Workflow] The trusted authentication implementation method includes the following steps: . xref:trusted-auth-secret-key.adoc[Enable Trusted authentication on ThoughtSpot] in the **Develop** > **Customizations** > **Security Settings** page. Copy the `secret_key` and place where the *token request service* can xref:trusted-auth-secret-key.adoc[securely access it]. -. Create the *xref:rusted-auth-token-request-service.adoc[token request service]*, typically a REST API endpoint in the embedding application. This service returns a login token for the user signed in by the web application. +. Create the *xref:trusted-auth-token-request-service.adoc[token request service]*, typically a REST API endpoint in the embedding application. This service returns a login token for the user signed in by the web application. . Include the xref:trusted-auth-sdk.adoc[Visual Embed SDK] into the embedding web application. The authentication type is defined in the `init` function. You can configure cookie-based (`AuthType.TrustedAuthToken`) or cookieless authentication (`AuthType.TrustedAuthTokenCookieless`) as per your deployment needs. + . When `init()` is called, the SDK checks if there is an existing ThoughtSpot session for the instance in the browser. If not, it will request a *login token* from either the `authEndpoint` URL specified in the SDK or the `getAuthToken` callback function. For `authEndPoint`, specify the authentication endpoint URL from which you want to obtain the authentication token. If using `getAuthToken`, call the `getAuthToken` function to invoke your login endpoint. The login endpoint then returns a `Promise` string that resolves to an authentication token. From a62d502016eebf0cbb310d5d2823543af66d3cd7 Mon Sep 17 00:00:00 2001 From: ShashiSubramnya Date: Mon, 27 Nov 2023 13:14:37 +0530 Subject: [PATCH 03/32] api doc fixes --- modules/ROOT/pages/admin-api.adoc | 13 ------------- modules/ROOT/pages/connections-api.adoc | 4 ++-- modules/ROOT/pages/group-api.adoc | 4 ++++ modules/ROOT/pages/partials/group-api-list.adoc | 8 ++++---- modules/ROOT/pages/partials/login-token-api.adoc | 2 +- modules/ROOT/pages/rest-api-reference.adoc | 1 + modules/ROOT/pages/user-api.adoc | 2 ++ 7 files changed, 14 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/admin-api.adoc b/modules/ROOT/pages/admin-api.adoc index 5ec5ab618..841545999 100644 --- a/modules/ROOT/pages/admin-api.adoc +++ b/modules/ROOT/pages/admin-api.adoc @@ -852,13 +852,6 @@ POST /tspublic/v1/admin/embed/actions |==== === Example request - -Make sure the API request has the following headers: - -* the `Accept` header is set as `Accept: application/json` -* the `X-requested-by` header is set as `X-Requested-By: ThoughtSpot` -* the `Content-Type` is set as `application/x-www-form-urlencoded` - .cURL [source,curl] @@ -994,12 +987,6 @@ PUT /tspublic/v1/admin/embed/actions/{actionid} === Example request -Make sure the API request has the following headers: - -* the `Accept` header is set as `Accept: application/json` -* The `X-requested-by` header as `X-Requested-By: ThoughtSpot` -* The `Content-Type' as `application/x-www-form-urlencoded` - .cURL [source,curl] diff --git a/modules/ROOT/pages/connections-api.adoc b/modules/ROOT/pages/connections-api.adoc index 0399b7de1..99eb905e5 100644 --- a/modules/ROOT/pages/connections-api.adoc +++ b/modules/ROOT/pages/connections-api.adoc @@ -1382,7 +1382,7 @@ __Optional__ a|__String__. Configuration attributes to override the connection ==== Note that the `config` attribute does not update the connection metadata in the ThoughtSpot system. It only allows you to modify the metadata in the API response. To update a connection, you must use the `/tspublic/v1/connection/update` endpoint. ==== -|`authentication_type` [tag greenBackground]#NEW in 8.8.0.cl# a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + +|`authentication_type` a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + * `SERVICE_ACCOUNT` + For data connections that require service account credentials to authenticate to the Cloud Data Warehouse and fetch data. @@ -1907,7 +1907,7 @@ __Optional__ a|__String__. Configuration attributes to override the metadata det ==== Note that the `config` attribute does not update the connection metadata in the ThoughtSpot system. It only allows you to modify the metadata in the API response. To update the connection metadata, you must use the `/tspublic/v1/connection/update` endpoint. ==== -|`authentication_type` [tag greenBackground]#NEW in 8.8.0.cl# a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + +|`authentication_type` a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + * `SERVICE_ACCOUNT` __Default__ + For data connections that require service account credentials to authenticate to the Cloud Data Warehouse and fetch data. diff --git a/modules/ROOT/pages/group-api.adoc b/modules/ROOT/pages/group-api.adoc index 452449e19..b2ef2770c 100644 --- a/modules/ROOT/pages/group-api.adoc +++ b/modules/ROOT/pages/group-api.adoc @@ -63,6 +63,8 @@ POST /tspublic/v1/group/ |`grouptype` __Optional__ a|__String__. Type of user group. Default value is `LOCAL_GROUP`, which indicates that the user group is created locally in the ThoughtSpot system. |`tenantid` __Optional__|__String__. GUID of the tenant for which the user group is being created. |`visibility` __Optional__|__String__. Visibility of the user group. The `visibility` attribute is set to `DEFAULT`. The `DEFAULT` attribute makes the user group visible for other user groups and allows them to share objects. +|`roleIds` +__Optional__|__Array of Strings__. Array of Role GUIDs. If RBAC is enabled and Roles are created on your instance, specify the GUIDs of the Role objects. |=== === Example request @@ -152,6 +154,8 @@ PUT /tspublic/v1/group/{groupid} |Form parameter|Description |`groupid`|__String__. The GUID of the user group. |`content`|__String__. A JSON map of group properties. +|`roleIds` +__Optional__|__Array of Strings__. Array of Role GUIDs. If RBAC is enabled and Roles are created on your instance, specify the GUIDs of the Role objects. |=== === Example request diff --git a/modules/ROOT/pages/partials/group-api-list.adoc b/modules/ROOT/pages/partials/group-api-list.adoc index 0dc996f07..fdd1c61df 100644 --- a/modules/ROOT/pages/partials/group-api-list.adoc +++ b/modules/ROOT/pages/partials/group-api-list.adoc @@ -33,13 +33,13 @@ ThoughtSpot Software [version noBackground]#7.2.1# |`xref:group-api.adoc#deleteUsersInGroup[*DELETE* /tspublic/v1/group/{groupid}/users]` + Removes users from a group. |ThoughtSpot Cloud [version noBackground]#ts7.oct.cl# + ThoughtSpot Software [version noBackground]#7.2.1# -|`xref:group-api.adoc#addRole[**POST** /tspublic/v1/group/addrole]` [beta betaBackground]^Beta^, + -Assigns a Role to a user group.|ThoughtSpot Cloud [version noBackground]#ts7.may.cl# + -ThoughtSpot Software [version noBackground]#6.0.x# +|`xref:group-api.adoc#addRole[**POST** /tspublic/v1/group/addrole]` [beta betaBackground]^Beta^ + +Assigns a Role to a user group.|ThoughtSpot Cloud [version noBackground]#9.7.0.cl# + +ThoughtSpot Software [version noBackground]#Not available# |`xref:group-api.adoc#add-privilege[**POST** /tspublic/v1/group/addprivilege]` + Assigns a privilege to a user group.|ThoughtSpot Cloud [version noBackground]#ts7.may.cl# + ThoughtSpot Software [version noBackground]#6.0.x# -|`xref:group-api.adoc##removeRole[**POST** /tspublic/v1/group/removerole] [beta betaBackground]^Beta^,` + +|`xref:group-api.adoc##removeRole[**POST** /tspublic/v1/group/removerole] [beta betaBackground]^Beta^` + Removes the Role assigned to a group.|ThoughtSpot Cloud [version noBackground]#9.7.0.cl# + ThoughtSpot Software [version noBackground]#Not available# |`xref:group-api.adoc#add-privilege[**POST** /tspublic/v1/group/addprivilege]` + diff --git a/modules/ROOT/pages/partials/login-token-api.adoc b/modules/ROOT/pages/partials/login-token-api.adoc index 937d05926..922e2c45d 100644 --- a/modules/ROOT/pages/partials/login-token-api.adoc +++ b/modules/ROOT/pages/partials/login-token-api.adoc @@ -8,7 +8,7 @@ This request method sends the user authentication attributes as query string par * `POST /tspublic/v1/session/login/token` (Recommended) + -This request method sends the user authentication attributes as `formData` parameters in the request body of the API call. For secure exchange of authentication information, we recommend using the `POST`request method. +This request method sends the user authentication attributes as `formData` parameters in the request body of the API call. For secure exchange of authentication information, we recommend using the `POST` request method. ==== Resource URLs diff --git a/modules/ROOT/pages/rest-api-reference.adoc b/modules/ROOT/pages/rest-api-reference.adoc index dd5d0d7b9..92ea95acd 100644 --- a/modules/ROOT/pages/rest-api-reference.adoc +++ b/modules/ROOT/pages/rest-api-reference.adoc @@ -13,6 +13,7 @@ Note that the `pinboard` and `PINBOARD_ANSWER_BOOK` terminology in REST API v1 e -- + == Orgs management include::{path}/org-api-list.adoc[] diff --git a/modules/ROOT/pages/user-api.adoc b/modules/ROOT/pages/user-api.adoc index 0a6dd50ea..722d8d7ee 100644 --- a/modules/ROOT/pages/user-api.adoc +++ b/modules/ROOT/pages/user-api.adoc @@ -1427,6 +1427,8 @@ Specify whether to remove the deleted users and user groups. By default, this at |`password` |__String__. Assign a password for new users added during the sync operation. By default, all new users will have the same password. +|`orgScope` + +__Optional__|Query parameter|__String__. The Org scope. Applicable to ThoughtSpot instances with Orgs feature enabled. When set to `ALL`, the API allows a cross-Org user sync operation. |=== === Example request From b39dd11d558c147751c2337b74e870047a245221 Mon Sep 17 00:00:00 2001 From: ShashiSubramnya Date: Mon, 11 Dec 2023 10:53:40 +0530 Subject: [PATCH 04/32] 9-8-0-updates --- modules/ROOT/pages/api-changelog.adoc | 40 +++++++++++++++++-- .../pages/rest-api-v2-metadata-search.adoc | 7 +++- modules/ROOT/pages/rest-apiv2-changelog.adoc | 4 ++ modules/ROOT/pages/runtime-filters.adoc | 4 +- modules/ROOT/pages/whats-new.adoc | 21 ++++++++++ 5 files changed, 70 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index d980f1323..7a7535106 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,31 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For a complete list of ThoughtSpot Everywhere features and enhancements, see xref:whats-new.adoc[What's New]. +== Version 1.27.0, Coming soon + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You cna use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize Natural Language Search experience. + +For a complete list of methods, functions, interface objects and properties, see the following pages: + + +* xref:SageEmbed.adoc[SageEmbed] +* xref:SageViewConfig[SageViewConfig]. + +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger drill down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent#_drilldown[DrillDown]. +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: + +* Host Events +** HostEvent.UpdateSageQuery + +Updates the search query string for Natural Language Search operations. +* Embed Events +** EmbedEvent.CreateConnection + +Emitted when a user creates a new data connection on the **Data** page. +** EmbedEvent.CreateWorksheet + +Emitted when a user creates a new Worksheet. +|==== + == Version 1.26.0, November 2023 [width="100%" cols="1,4"] @@ -38,24 +63,33 @@ Embed events:: * `EmbedEvent.SavePersonalisedView` * `EmbedEvent.ResetLiveboard` * `EmbedEvent.DeletePersonalisedView` +* `EmbedEvent.SageWorksheetUpdated +* `EmbedEvent.SageEmbedQuery` + For more information, see xref:EmbedEvent.adoc[EmbedEvent]. Host events:: -* `HostEvent.DeletePersonalisedView` * `HostEvent.GetTabs` * `HostEvent.SetVisibleTabs` * `HostEvent.SetHiddenTabs` +* `HostEvent.GetAnswerSession` +* `HostEvent.UpdateSageQuery` + For more information, see xref:HostEvent.adoc[HostEvent]. |[tag greenBackground]#NEW FEATURE# a| The SDK introduces the following action enumeration members: +* `Action.AddTab` + +Show, disable, or hide the **Add Tab** action on a Liveboard. * `Action.PersonalisedViewsDropdown` + -Show or hide the Liveboard views saved by a user. +Show, disable, or hide the Liveboard views saved by a user. * `Action.LiveboardUsers` + -Show or hide Liveboard users. +Show, disable, or hide Liveboard users. +* `Action.SageAnswerFeedback` +Show, disable, or hide the feedback widget on AI-generated Answer page. +* `Action.EditSageAnswer` +Show, disable, or hide the **Edit** action on the AI-generated Answer page. For more information, see xref:Action.adoc[Actions]. |==== diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index d4d788609..2a93e4492 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -87,7 +87,7 @@ The `/metadata/search` API performs listing functions when you do not send speci The basic metadata selectors are placed in the `metadata` parameter as an array of link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fstructures%2Fmetadata-list-item-input[Metadata List objects, target=_blank]. -For example, to get all Liveboards, you need to send only a single metadata object with `type` parameter set to `LIVEBOARD`: +For example, to get all Liveboards, you need to send only a single metadata object with `type` parameter set to `LIVEBOARD`. [source,JSON] ---- @@ -100,6 +100,11 @@ For example, to get all Liveboards, you need to send only a single metadata obje { ---- +[NOTE] +==== +The `type` attribute is set to `LIVEBOARD` by default. In other words, even if the `type` attribute is not defined and the API request is sent with an empty body, ThoughtSpot returns only Liveboard objects. +==== + To match names against a pattern, you can use the `name_pattern` parameter, including `%` for wildcard purposes: diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 77f5182cc..d5b653b01 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,10 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For a complete list of ThoughtSpot Everywhere features and enhancements, see xref:whats-new.adoc[What's New]. +== Version, 9.8.0.cl, Coming soon + +The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports `VALIDATE_ONLY` option to compare and validate TML content on the destination environment against the content in the main branch before deploying commits and publishing changes. + == Version 9.7.0, November 2023 === Version Control APIs diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 48f968008..36d2058fd 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -40,7 +40,7 @@ __String__. The xref:runtime-filters.adoc#rtOperator[runtime filter operator]. F | 1 | `NE` -| does not equal +| not equal to | 1 | `LT` @@ -212,7 +212,7 @@ liveboardEmbed.render({ ---- | `NE` + -does not equal + +Not exactly or Not equal to + Number of values allowed: 1 a| [source,JavaScript] ---- diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 20441388f..a32537abb 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,27 @@ This page provides information about new features, enhancements, and deprecated functionality in ThoughtSpot Everywhere. +== Version 9.8.0.cl, Coming soon + +=== Support for Natural Language Search embedding +You can now embed ThoughtSpot Search page with Natural Language Search capability using the `SageEmbed` SDK package. Natural Language Search allows your application users to search for data using natural language query strings. This feature also provides AI-suggested sample questions and popular queries to assist users in their data search operations. + +Using `SageEmbed`, you can integrate ThoughtSpot Search data interface with Natural Language Search in your app and also customize the Search options as per your requirements. + +=== Embed Playground enhancements +The Visual Embed playground now allows you to explore Natural Language Search embedding options and Search page customization capabilities. + +=== Git integration enhancements + +The **Deploy Commit** Version Control API now provides the `VALIDATE_ONLY` option to validate TML imports to the destination environment. If your destination environment has TML content that has been modified or is different from the content on the main branch, you can run the validation before deploying changes to the destination environment. + +=== Visual Embed SDK + +For information about the new features and enhancements introduced in Visual Embed SDK version 1.26.0, see xref:api-changelog.adoc[Visual Embed changelog]. + +=== REST API + +For information about REST API enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. == Version 9.7.0.cl From 5fee78b92502469a6058989ae699d987a77cb1f8 Mon Sep 17 00:00:00 2001 From: ShashiSubramnya Date: Tue, 12 Dec 2023 22:33:02 +0530 Subject: [PATCH 05/32] 9-8-0-updates --- modules/ROOT/pages/api-changelog.adoc | 15 +- modules/ROOT/pages/code-samples.adoc | 115 +++++--- modules/ROOT/pages/common/nav.adoc | 1 + modules/ROOT/pages/developer-playground.adoc | 147 ++++++++++- modules/ROOT/pages/embed-nls.adoc | 264 +++++++++++++++++++ modules/ROOT/pages/rest-apiv2-changelog.adoc | 2 +- modules/ROOT/pages/version_control.adoc | 17 +- modules/ROOT/pages/whats-new.adoc | 8 +- static/doc-images/images/sageEmbed.png | Bin 0 -> 127843 bytes 9 files changed, 517 insertions(+), 52 deletions(-) create mode 100644 modules/ROOT/pages/embed-nls.adoc create mode 100644 static/doc-images/images/sageEmbed.png diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 7a7535106..8265e7cd4 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -12,27 +12,28 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For a [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You cna use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize Natural Language Search experience. +|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. For a complete list of methods, functions, interface objects and properties, see the following pages: + * xref:SageEmbed.adoc[SageEmbed] -* xref:SageViewConfig[SageViewConfig]. +* xref:SageViewConfig.adoc[SageViewConfig] -|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger drill down action on a specific visualization of a Liveboard. -For more information, see xref:HostEvent#_drilldown[DrillDown]. +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. |[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: * Host Events -** HostEvent.UpdateSageQuery + +** `HostEvent.UpdateSageQuery` + Updates the search query string for Natural Language Search operations. * Embed Events -** EmbedEvent.CreateConnection + +** `EmbedEvent.CreateConnection` + Emitted when a user creates a new data connection on the **Data** page. -** EmbedEvent.CreateWorksheet + +** `EmbedEvent.CreateWorksheet` + Emitted when a user creates a new Worksheet. |==== + == Version 1.26.0, November 2023 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/code-samples.adoc b/modules/ROOT/pages/code-samples.adoc index 7130fbd2c..a0d957f3a 100644 --- a/modules/ROOT/pages/code-samples.adoc +++ b/modules/ROOT/pages/code-samples.adoc @@ -11,14 +11,12 @@ This page contains code samples to help you embed ThoughtSpot features and data You can use the following code snippets to build your code and embed ThoughtSpot content in your host application. -=== Embed ThoughtSpot Search - -The following example shows how to embed the ThoughtSpot Search page: +=== Embed a Liveboard [source,JavaScript] ---- import { - SearchEmbed, + LiveboardEmbed, AuthType, init, prefetch, @@ -29,27 +27,25 @@ from '@thoughtspot/visual-embed-sdk'; // If not using npm, use the following for an ES6 standard import: // from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; init({ - thoughtSpotHost: "<%=tshost%>", + thoughtSpotHost: '<%=tshost%>', authType: AuthType.EmbeddedSSO, }); -const searchEmbed = new SearchEmbed(document.getElementById('ts-embed'), { +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%', }, - dataSources: ['4f289824-e301-4001-ad06-8888f69c4748'], - collapseDataSources: true, + liveboardId: 'f4a4e205-3b43-4b77-8ec0-8723da49ce1d', }); -searchEmbed.render(); +liveboardEmbed.render(); ---- -[#searchBarEmbedCode] -The following example shows how to embed ThoughtSpot search bar: +=== Embed charts and tables [source,JavaScript] ---- import { - SearchBarEmbed, + LiveboardEmbed, AuthType, init, prefetch, @@ -60,25 +56,27 @@ from '@thoughtspot/visual-embed-sdk'; // If not using npm, use the following for an ES6 standard import: // from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; init({ - thoughtSpotHost: "<%=tshost%>", + thoughtSpotHost: '<%=tshost%>', authType: AuthType.EmbeddedSSO, }); -const searchBarEmbed = new SearchBarEmbed(document.getElementById('ts-embed'), { +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%', }, - dataSources: ['4f289824-e301-4001-ad06-8888f69c4748'], + liveboardId: '6294b4fc-c289-412a-b458-073fcf6e4516', + vizId: '28b73b4a-1341-4535-ab71-f76b6fe7bf92', }); -searchBarEmbed.render(); +liveboardEmbed.render(); ---- -=== Embed charts and tables +=== Embed full application [source,JavaScript] ---- import { - LiveboardEmbed, + AppEmbed, + Page, AuthType, init, prefetch, @@ -92,23 +90,24 @@ init({ thoughtSpotHost: '<%=tshost%>', authType: AuthType.EmbeddedSSO, }); -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { +const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%', }, - liveboardId: '6294b4fc-c289-412a-b458-073fcf6e4516', - vizId: '28b73b4a-1341-4535-ab71-f76b6fe7bf92', + pageId: Page.Data, }); -liveboardEmbed.render(); +appEmbed.render(); ---- -=== Embed a Liveboard +=== Embed ThoughtSpot Search + +The following example shows how to embed the ThoughtSpot Search page: [source,JavaScript] ---- import { - LiveboardEmbed, + SearchEmbed, AuthType, init, prefetch, @@ -119,26 +118,32 @@ from '@thoughtspot/visual-embed-sdk'; // If not using npm, use the following for an ES6 standard import: // from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; init({ - thoughtSpotHost: '<%=tshost%>', + thoughtSpotHost: "<%=tshost%>", authType: AuthType.EmbeddedSSO, }); -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { +const searchEmbed = new SearchEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%', }, - liveboardId: 'f4a4e205-3b43-4b77-8ec0-8723da49ce1d', + dataSources: ['4f289824-e301-4001-ad06-8888f69c4748'], + searchOptions: { + searchTokenString: '[quantity purchased] [region]', + executeSearch: true, + }, }); -liveboardEmbed.render(); +searchEmbed.render(); ---- -=== Embed full application +== Embed Natural Language Search + +[#nlsEmbedCode] +The following example shows how to embed ThoughtSpot search bar: [source,JavaScript] ---- import { - AppEmbed, - Page, + SageEmbed, AuthType, init, prefetch, @@ -149,17 +154,57 @@ from '@thoughtspot/visual-embed-sdk'; // If not using npm, use the following for an ES6 standard import: // from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; init({ - thoughtSpotHost: '<%=tshost%>', + thoughtSpotHost: "<%=tshost%>", authType: AuthType.EmbeddedSSO, }); -const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { +const sageEmbed = new SageEmbed(document.getElementById('ts-embed'), { frameParams: { width: '100%', height: '100%', }, - pageId: Page.Data, + dataSources: ['4f289824-e301-4001-ad06-8888f69c4748'], + searchOptions: { + searchQuery: 'average sales by country and product type', + executeSearch: true, + }, }); -appEmbed.render(); +sageEmbed.render(); +---- + +== Embed ThoughtSpot Search bar + +[#searchBarEmbedCode] +The following example shows how to embed ThoughtSpot search bar: + +[source,JavaScript] +---- +import { + SearchBarEmbed, + AuthType, + init, + prefetch, + EmbedEvent, + HostEvent +} +from '@thoughtspot/visual-embed-sdk'; +// If not using npm, use the following for an ES6 standard import: +// from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; +init({ + thoughtSpotHost: "<%=tshost%>", + authType: AuthType.EmbeddedSSO, +}); +const searchBarEmbed = new SearchBarEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + dataSources: ['4f289824-e301-4001-ad06-8888f69c4748'], + searchOptions: { + searchTokenString: '[quantity purchased] [region]', + executeSearch: true, + }, +}); +searchBarEmbed.render(); ---- == Event trigger diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 46b437a85..1968c15d1 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -34,6 +34,7 @@ *** 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-searchbar[Embed search bar] ** link:{{navprefix}}/react-app-embed[Embed with React components] ** link:{{navprefix}}/VisualEmbedSdk[Visual Embed SDK Reference] diff --git a/modules/ROOT/pages/developer-playground.adoc b/modules/ROOT/pages/developer-playground.adoc index 31237b404..5fabefc8f 100644 --- a/modules/ROOT/pages/developer-playground.adoc +++ b/modules/ROOT/pages/developer-playground.adoc @@ -14,6 +14,151 @@ You can explore the following SDK components in the Playground. * xref:developer-playground.adoc#playground-visualization[Visualizations] * xref:developer-playground.adoc#playground-fullapp[Full application] +[#playground-search] +== Search +To explore the Search embed function: + +. Go to *Playground* > *Search*. +. Select a data source or a saved Answer. +. Try using any of the following customization settings and click *Run* to preview the result. + ++ +[width="100%"] +|==== +a|**Collapse data panel** + +Minimizes the data panel on the left navigation bar. +++++ +Try it out +++++ + +a|**Hide data panel** + + +Hides the default data panel. You can use this function to create a custom data panel when embedding the search module in your application. + +++++ +Try it out +++++ + +a|**Hide chart or table** + +Hides the charts and tables that appear beneath the search bar by default. For example, if you want to create a custom visualization using raw data from an existing Answer, you can enable this checkbox. + +++++ +Try it out +++++ + +a|**Modify available actions** + + +include::{path}/modify-available-actions.adoc[] + +++++ +Try it out +++++ + +a|**Enable Search Assist** + +Enables the Search Assist feature that provides a custom onboarding experience for users searching data on an embedded instance. With Search Assist, data engineers and Worksheet owners can create a set of questions to assist users with the search. + +++++ +Try it out +++++ + +a|**Set runtime filters** + +Enables Runtime Filters. + +Runtime filters provide the ability to filter data at the time of retrieval. +To apply Runtime Filters, pass the `columnName`, `operator`, and `value` parameters in the `runtimeFilters` attribute. + +[source,JavaScript] +---- +runtimeFilters: [{ + columnName: 'color', + operator: RuntimeFilterOp.EQ, + values: ['red'] +}] +---- + +++++ +Try it out +++++ + +a|**Add search tokens** + + +Allows you to pass search tokens as query string and execute search. + +The following example shows how to create a search a `searchTokenString` and execute search: + + +[source, Javascript] +---- +searchOptions: { + searchTokenString: '[product][sales][date].daily', + executeSearch: true, +} +---- + +++++ +Try it out +++++ + +|*Handle custom actions* + +Allows you to view the code for a custom action event. If the embedded instance has a custom action, use this checkbox to view the event generated by the custom action and send ThoughtSpot data as a payload. +|==== + +[#playground-visualization] +== Visualization +To explore the visualization embedding function: + +. Go to *Playground* > *Visualization*. +. Select a Liveboard or visualization. +. Try using any of the following customization settings and click *Run* to preview the result. + + +[width="100%"] +|==== + +a|*Modify available actions* + +include::{path}/modify-available-actions.adoc[] + +a|**Set runtime filters** + +Enables Runtime Filters. + +Runtime filters provide the ability to filter data at the time of retrieval. +To apply Runtime Filters, pass the `columnName`, `operator`, and `value` parameters in the `runtimeFilters` attribute. + +[source,JavaScript] +---- +runtimeFilters: [{ + columnName: 'color', + operator: RuntimeFilterOp.EQ, + values: ['red'] +}] +---- + +++++ +Try it out +++++ + +For more information, see xref:runtime-filters.adoc[Runtime filters]. + +|**Handle custom actions** + +Allows you to view the code for a custom action event. If the embedded instance has a custom action, use this checkbox to view the event generated by the custom action and send ThoughtSpot data as a payload. + + + +++++ +Try it out +++++ + +|==== + + + [#playground-search] == Search To explore the Search embed function: @@ -66,7 +211,7 @@ searchOptions: { executeSearch: true, } ---- - + ++++ Try it out ++++ diff --git a/modules/ROOT/pages/embed-nls.adoc b/modules/ROOT/pages/embed-nls.adoc new file mode 100644 index 000000000..93c676233 --- /dev/null +++ b/modules/ROOT/pages/embed-nls.adoc @@ -0,0 +1,264 @@ += Embed Natural Language Search +:toc: true +:toclevels: 2 + +:page-title: Embed Natural Language Search +: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 +* AI-generated sample Answers +* AI-suggested popular queries + +== Natural Language Search components + +The `SageEmbed` package allows you embed the following Search components in your application: + +* Search bar that supports natural language queries + ++ +Unlike the token-based Search, the Search bar in the Natural Language Search interface allows you to type questions in the natural language format. Users can also select popular queries suggested by ThoughtSpot. + +* Worksheet selector + +Allows selecting a Worksheet as data source for search queries. The AI Answer Search must be enabled on the Worksheet for search queries to return AI-generated Answers. +* Sample questions + +The sample questions panel shows the AI-suggested search queries and Answers. To see AI generated answers, select an AI-enabled worksheet. +* Answer page + +The API generated Answer page shows chart or table and an **Edit** button to modify the search query. The Answer page also includes a feedback widget for users to send feedback. + +== Get started +Get started with embedding Natural Language Search and complete the steps described in the following sections + +=== Import the SageEmbed package + +Import the `SageEmbed` SDK library to your application environment: + +**npm** +[source,JavaScript] +---- +import { + SageEmbed, + AuthType, + init, + prefetch, + EmbedEvent, + HostEvent +} +from '@thoughtspot/visual-embed-sdk'; +---- + +**ES6** +[source,JavaScript] +---- +