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/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index d980f1323..fc77ce64b 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,32 @@ 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, January 2024 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|The `SageEmbed` package is now available on all clusters. You can use this SDK package to embed Natural Language Search capabilities and assist users with AI-suggested queries and AI-generated answers. This SDK package also allows you to customize the Natural Language Search experience in the embedded view. + +For a complete list of methods, functions, interface objects and properties, see the following pages: + + +* xref:SageEmbed.adoc[SageEmbed] +* xref:SageViewConfig.adoc[SageViewConfig] + +|[tag orangeBackground]#MODIFIED# a| The `HostEvent.DrillDown` now supports the `vizId` parameter to trigger a drill-down action on a specific visualization of a Liveboard. +For more information, see xref:HostEvent.adoc#_drilldown[DrillDown]. +|[tag greenBackground]#NEW FEATURE# a| The new version of the SDK introduces the following new enumeration members: + +* Host Events +** `HostEvent.UpdateSageQuery` + +Updates the search query string for Natural Language Search operations. +* Embed Events +** `EmbedEvent.CreateConnection` + +Emitted when a user creates a new data connection on the **Data** page. +** `EmbedEvent.CreateWorksheet` + +Emitted when a user creates a new Worksheet. +|==== + + == Version 1.26.0, November 2023 [width="100%" cols="1,4"] @@ -38,24 +64,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]. |==== @@ -168,16 +203,25 @@ The following events are deprecated from version 1.21.0 onwards. You can use the `DownloadAsPng`, `DownloadAsXlsx`, `DownloadAsCsv` and `DownloadAsPdf` events for download actions. For more information, see xref:embed-events.adoc[Events reference]. -|[tag orangeBackground]#MODIFIED# a|The SDK supports omitting or executing a search query in xref:xref:HostEvent.adoc#_search[`HostEvent.Search`]. - -Starting from 9.2.0.cl release, use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: +|[tag orangeBackground]#MODIFIED# a| +Events:: +The SDK supports omitting or executing a search query in xref:xref:HostEvent.adoc#_search[`HostEvent.Search`]. +Actions:: +Use the following action enumeration members instead of `Action.Download` to show, hide, or disable the *Download* menu action on an embedded Liveboard, visualization, or Answer: ++ * `Action.DownloadAsCsv` * `Action.DownloadAsPdf` * `Action.DownloadAsXlsx` * `Action.DownloadAsPng` -For more information, see xref:embed-action-ref.adoc[Action reference]. ++ +To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` |[tag greenBackground]#NEW FEATURE# a| The SDK includes new attributes to customize the experience for embedded app users: diff --git a/modules/ROOT/pages/app-actions.adoc b/modules/ROOT/pages/app-actions.adoc deleted file mode 100644 index b46c5e815..000000000 --- a/modules/ROOT/pages/app-actions.adoc +++ /dev/null @@ -1,30 +0,0 @@ -= App actions [beta betaBackground]^Beta^ -:toc: true - -:page-title: App actions for business application integration -:page-pageid: app-actions -:page-description: You can add an app action to send data to a third-party business application workspace such as Slack channels. - -ThoughtSpot supports integrating your application instance with business apps such as Slack. With this integration capability, business users and analysts can now push insights to their application workspace, notify their teams, and view data in context. - -ThoughtSpot automates and simplifies the integration workflow with app actions and secures data transactions between the source and destination apps with OAuth authentication and authorization. App actions allow ThoughtSpot to automatically establish a pipeline with the destination app and thus eliminate the need for building connectors or programs for application integration. Your application users can quickly get started and push data to their workspace in a few simple steps. - - -[div boxDiv boxFullWidth] --- -+++
Feature highlights
+++ - -* App actions are available on both embedded and standalone ThoughtSpot instances and do not require a ThoughtSpot Everywhere Edition license. -* In the 8.1.0.cl release, app actions are available for Slack integration only. -* Any ThoughtSpot user with developer or admin privileges can create an app action in the Developer portal. -* ThoughtSpot allows only one action per app. -* Developers can set an app action as a global or local action. -* By default, a global app action is added as a menu action in **More** image:./images/icon-more-10px.png[the more options menu]. -* An app action cannot be set as a context menu action. -* Developers can control user access to app actions and limit its availability to specific user groups. --- - -== App actions for Slack integration - -For information about how to create an app action and push data to a Slack workspace, see xref:push-data-to-slack.adoc[Integrate ThoughtSpot with Slack workspace]. - diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index b5105a8e6..d8e3ad23c 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -1,6 +1,6 @@ = REST API v2.0 authentication :toc: true -:toclevels: 1 +:toclevels: 2 :page-title: User authentication and session management :page-pageid: api-authv2 @@ -8,25 +8,25 @@ The REST API v2.0 framework supports the following types of authentication: -Basic authentication:: -In this method, REST clients can access ThoughtSpot objects using `username` and `password` parameters. +xref:authentication.adoc#loginTS[Cookie-based authentication]:: +In this method, the REST client sends an API request to the `api/rest/2.0/auth/session/login` endpoint with the `username` and `password`. The client session is assigned a cookie upon successful login. This session cookie is used to authenticate the client in subsequent API calls. -Bearer token authentication:: -In this method, the REST clients obtain a bearer access token to authenticate to ThoughtSpot. The access token is a string, which you must include in the `Authorization` header to authorize your API requests. +Token-based authentication:: +In this method, the REST clients obtain a bearer authentication token from ThoughtSpot and use this token in their subsequent API calls to authorize their requests. Based on your client setup, You can use one of the following methods to obtain an authentication token: -Trusted authentication:: -In this method, the REST clients must xref:authentication.adoc#trusted-auth-v2[obtain an authentication token] to sign in to a ThoughtSpot instance. -+ -Administrators can request an authentication token on behalf of another user by providing the `secret key` as input in the API request. The API users must pass the token obtained from ThoughtSpot in the `Authorization` header of their requests. + +xref:authentication.adoc#_basic_authentication[Basis authentication];; +In this method, a REST client sends the `username` and `password` to authenticate to ThoughtSpot and obtains a token. + +xref:authentication.adoc#trusted-auth-v2[Trusted authentication];; +In this method, a 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. + -The trusted authentication method also supports creating a user just-in-time and assigning privileges. +The trusted authentication method also supports xref:just-in-time-provisioning.adoc[creating a user and assigning privileges just in time]. [#loginTS] -== Basic authentication -In the basic authentication method, user credentials are sent in the API request. - -To sign in to ThoughtSpot and create a session, REST clients must send a `POST` request with the following attributes to the `/api/rest/2.0/auth/session/login` API endpoint: +== Cookie-based authentication +For cookie-based authentication, make an API call to the `/api/rest/2.0/auth/session/login` endpoint with the `username`, `password`, and other attributes in the request body. +=== Request parameters [width="100%" cols="1,4"] [options='header'] |===== @@ -41,8 +41,11 @@ To sign in to ThoughtSpot and create a session, REST clients must send a `POST` |__String__. Name of ID of the Org. If no Org ID is specified, the user will be logged into the Org context of their previous session. |`remember_me` +__Optional__ |__Boolean__. A flag to remember the user session. -When set to true, the session cookie persists in subsequent API calls. +When set to true, the session cookie persists in subsequent API calls for about 7 days. + +If `remember_me` is set to `false`, the user session times out after three hours of inactivity. To get a cookie assigned to your user session, you need to log in to ThoughtSpot again. |===== === Example request @@ -66,7 +69,12 @@ POST {ThoughtSpot-Host}/api/rest/2.0/auth/session/login === Example response -If the login is successful, ThoughtSpot returns the 204 response code. +If the login is successful, ThoughtSpot returns the 204 response code. A session cookie is assigned to the logged-in user and sent in the response header. + +---- +Set-Cookie: JSESSIONID=b9a5b821-fa91-49ea-99fc-12817a141e76; Path=/; HttpOnly +Set-Cookie: clientId=76d83461-1b8a-425a-9116-66c8d6f006bb; Path=/; Secure; HttpOnly +---- === Response codes @@ -85,10 +93,45 @@ Invalid username or password |Operation failed |===== +=== Cookie usage in subsequent API requests + +The session cookie is automatically set in the request header when you make your subsequent API calls via a web browser. Note that if you are using a Web browser or Postman to make a REST API call, the session cookie obtained from the `/tspublic/v1/session/login` API call is automatically set. REST clients in a non-browser environment must include the session cookie in the request header as shown in the following example: + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/search' \ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + -H 'Cookie: JSESSIONID=fc3424f9-d3f0-4a24-bd33-400fd826cac7; clientId=70cf1328-af97-40b2-9bd5-1c520e133963' \ + --data-raw '{ + "metadata": [ + { + "type": "LIVEBOARD" + } + ] + }' +---- + +[NOTE] +==== +If you are accessing the REST API outside a web browser, create a long-lived session object in your code, and then call the login API using that session object. Make subsequent REST API calls with the same session object to send the cookie along with the other aspects of the particular REST API call. +==== + [#bearerToken] -== Bearer token authentication +== Token-based authentication + +To get an access token that grants full access to ThoughtSpot, send a `POST` request to the `/api/rest/2.0/auth/token/full` endpoint with the following parameters in the request body. + +[NOTE] +==== +By default, the token obtained from ThoughtSpot is valid for 5 minutes (300 seconds). If a REST client tries to make an API call with an expired token, the server returns an error. In such cases, obtain a new token and use it in your subsequent API calls. If you want to use the token for more than 5 minutes, set the token expiry duration to a higher value. +==== + -For OAuth 2.0 bearer token-based authorization, you must obtain an OAuth access token. You can obtain a token that grants read-only access to a ThoughtSpot metadata object or full access to the ThoughtSpot app. +=== Basic authentication + +You can obtain a token that grants read-only access to a ThoughtSpot metadata object via a `POST` request to the `/api/rest/2.0/auth/token/object` endpoint, or get a token that grants full access to ThoughtSpot via `/api/rest/2.0/auth/token/full`. ==== Get a token for full access @@ -104,9 +147,11 @@ To get an access token that grants full access to ThoughtSpot, send a `POST` req |__String__. Password of the user account. |`org_id` + __Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org that you want to access. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user. +|`validity_time_in_sec` + +__Optional__|__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. |===== -=== Example request +===== Example request .cURL [sourc,cURL] @@ -117,25 +162,19 @@ curl -X POST \ -H 'Content-Type: application/json' \ --data-raw '{ "username": "tsUserA", - "password": "Guest@123!" + "password": "Guest123!", "org_id": 1, "validity_time_in_sec": 86400 }' ---- -.Request URL -[source,http] ----- -POST {ThoughtSpot-Host}/api/rest/2.0/auth/token/object ----- - -=== Example response +===== Example response If the API request is successful, ThoughtSpot returns the access token in the response body. [source,JSON] ---- { - "token": "{access-token}", + "token": "{AUTH_TOKEN}", "creation_time_in_millis": 1675129264089, "expiration_time_in_millis": 1675129564089, "scope": { @@ -143,12 +182,12 @@ If the API request is successful, ThoughtSpot returns the access token in the re "org_id": 1, "metadata_id": null }, - "valid_for_user_id": "59481331-ee53-42be-a548-bd87be6ddd4a", + "valid_for_user_id": "59a122dc0-38d7-43e7-bb90-86f724c7b602", "valid_for_username": "tsUserA" } ---- -==== Response codes +===== Response codes [width="100%" cols="1,4"] [options='header'] |===== @@ -166,9 +205,9 @@ Invalid parameter |Operation failed |===== -=== Get an access token to view a specific object +==== Get a token to access a specific object -To get an OAuth token to access a specific metadata object in ThoughtSpot, send a `POST` request to the `/api/rest/2.0/auth/token/object` endpoint with the following attributes in the request body: +To get a token that grants read-only access to a ThoughtSpot metadata object, send a `POST` request to the `/api/rest/2.0/auth/token/object` endpoint with the following parameters in the request body. [width="100%" cols="1,4"] [options='header'] @@ -183,54 +222,51 @@ To get an OAuth token to access a specific metadata object in ThoughtSpot, send The token obtained from this API request grants `Read-Only` access to the specified object. |`org_id` + __Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org that you want to access. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user. +|`validity_time_in_sec` + +__Optional__|__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. |===== -==== Example request +===== Example request .cURL [sourc,cURL] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \ + -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ - -H 'Accept: application/json' \ --data-raw '{ "username": "tsUserA", - "object_id": "bea79810-145f-4ad0-a02c-4177a6e7d861", - "password": "Guest@123!" + "object_id": "e65d7d3b-c934-4a59-baa1-d5cb7b679cc9", + "org_id": 1, + "validity_time_in_sec": 86400, + "password": "Guest123!" }' ---- -.Request URL -[source,http] ----- -POST {ThoughtSpot-Host}/api/rest/2.0/auth/token/object ----- - -==== Example response +===== Example response If the API request is successful, ThoughtSpot returns the access token in the response body. [source,JSON] ---- { - "token": "{access-token}", - "creation_time_in_millis": 1674665089872, - "expiration_time_in_millis": 1674665389872, + "token": "{AUTH_TOKEN}", + "creation_time_in_millis": 1675129264089, + "expiration_time_in_millis": 1675129564089, "scope": { "access_type": "REPORT_BOOK_VIEW", - "org_id": 0, - "metadata_id": "9bd202f5-d431-44bf-9a07-b4f7be372125" + "org_id": 1, + "metadata_id": "e65d7d3b-c934-4a59-baa1-d5cb7b679cc9" }, - "valid_for_user_id": "59481331-ee53-42be-a548-bd87be6ddd4a", + "valid_for_user_id": "59a122dc0-38d7-43e7-bb90-86f724c7b602", "valid_for_username": "tsUserA" } ---- -==== Response codes - +===== Response codes [width="100%" cols="1,4"] [options='header'] -|==== +|===== |HTTP status code|Description |**204** |Successful logon @@ -243,10 +279,11 @@ Invalid parameter |Forbidden access |**500** |Operation failed -|==== +|===== + [#trusted-auth-v2] -== Trusted authentication +=== Trusted authentication Trusted authentication allows an authenticator service to request tokens on behalf of users who require access to the ThoughtSpot content embedded in a third-party application. @@ -256,7 +293,7 @@ To request a token on behalf of another user, you need administrator privileges The token generation API endpoints also allow creating a user just-in-time and dynamically assign privileges, groups, and Org to the new user. -==== Get an access token for full access +==== Get a token for full access To get an access token that grants full access to ThoughtSpot, send a `POST` request with the following attributes to the `/api/rest/2.0/auth/token/full` endpoint: @@ -268,17 +305,19 @@ To get an access token that grants full access to ThoughtSpot, send a `POST` req |__String__. Username of the ThoughtSpot user. If the user is not available in ThoughtSpot, you can set the `auto_create` parameter to `true` to create a user just-in-time(JIT). |`secret_key` |__String__. The secret key string provided by the ThoughtSpot server. ThoughtSpot generates this secret key xref:trusted-authentication.adoc#trusted-auth-enable[when trusted authentication is enabled]. -|`org_id` + -__Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org to which the user belongs. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user. |`validity_time_in_sec` + __Optional__| __Integer__. Token expiry duration in seconds. The default duration is 300 seconds. +|`org_id` + +__Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org to which the user belongs. By default, ThoughtSpot returns a token that grants access to the current logged-in Org context of the requesting user. +|`email` |__String__. Email address of the user. Use this parameter to add email address of the user during JIT provisioning. +|`display_name` |__String__. Display name of the user. Use this parameter when adding a user just-in-time (JIT). |`auto_create` + __Optional__|__Boolean__. Creates a user if the specified username is not already available in ThoughtSpot. The default value is `false`. |`group_identifiers` + -__Optional__|__String__. GUID or name of the groups to which the user belongs. This attribute can be used in conjunction with `auto_create` to dynamically assign groups and privileges to a user. +__Optional__|__Array of Strings__. GUIDs or names of the groups to assign the user to. This attribute can be used in conjunction with `auto_create` to dynamically assign groups and privileges to a user. |===== -=== Example request +===== Example request The following example shows the code sample to request an object access token for a ThoughtSpot user: @@ -287,7 +326,7 @@ The following example shows the code sample to request an object access token fo ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full' \ - -H 'Authorization: Bearer {admin-access-token}'\ + -H 'Authorization: Bearer {AUTH_TOKEN}'\ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ --data-raw '{ @@ -304,7 +343,7 @@ The following example shows the code sample to obtain a token for a user, which ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/full' \ - -H 'Authorization: Bearer {admin-access-token}'\ + -H 'Authorization: Bearer {AUTH_TOKEN}'\ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ @@ -312,6 +351,8 @@ curl -X POST \ "object_id": "061457a2-27bc-43a9-9754-0cd873691bf0", "secret_key": "69fb6d98-1696-42c0-9841-22b078c04060", "org_id": 2 + "email": "userA@example.com", + "display_name": "User A" "auto_create": true, "group_identifiers": [ "DataAdmin", @@ -320,13 +361,13 @@ curl -X POST \ }' ---- -=== Example response +===== Example response If the API request is successful, ThoughtSpot returns the token in the response body. [source,JSON] ---- { - "token":"dHNVc2VyQTpKSE5vYVhKdk1TUlRTRUV0TWpVMkpEVXdNREF3TUNSelRuQk1Xa0pPYVZkMldWWmFUMk5xZVhnMlR6ZFJQVDBrYmtsbU0xZFZSRmhyYkZsMGFUWkthMDlOWmt0V0wySXhjMWtyY3pSWlNrOUtVbmRGU0d4RllsSmhTVDA=", + "token":"{AUTH_TOKEN}", "creation_time_in_millis":1675163671270, "expiration_time_in_millis":1675163971270, "scope":{ @@ -357,7 +398,7 @@ Invalid parameter |Operation failed |===== -==== Get an authentication token for object access +==== Get a token to access a specific object To get a token that grants a `READ-ONLY` access to a specific metadata object, send a `POST` request with the following attributes to the `/api/rest/2.0/auth/token/object` API endpoint: @@ -393,7 +434,7 @@ The following example shows the code sample to request an object access token fo ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \ - -H 'Authorization: Bearer {admin-access-token}'\ + -H 'Authorization: Bearer {AUTH_TOKEN}'\ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ --data-raw '{ @@ -410,7 +451,7 @@ The following example shows the code sample to obtain a token for a user, which ---- curl -X POST \ --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/object' \ - -H 'Authorization: Bearer {admin-access-token}'\ + -H 'Authorization: Bearer {AUTH_TOKEN}'\ -H 'Accept: application/json'\ -H 'Content-Type: application/json' \ --data-raw '{ @@ -432,7 +473,7 @@ If the API request is successful, ThoughtSpot returns a token for the specified [source,JSON] ---- { - "token":"dHNVc2VyQTpKSE5vYVhKdk1TUlRTRUV0TWpVMkpEVXdNREF3TUNSVlpEVXpaM2RFYTNsU2RUQXdRV3RxVHpOUllYSkJQVDBrVWxKaFRsWm9jSGxsVWtkWWMxTXdiak5xVEdoeVlrRTFSa2xDYTFOR1pWRnViazFIY2psQ1ZGVjNWVDA=", + "token":"{AUTH_TOKEN}", "creation_time_in_millis":1675162190374, "expiration_time_in_millis":1675162490374, "scope":{ @@ -464,29 +505,39 @@ Invalid parameter |Operation failed |===== -== Log in to ThoughtSpot +=== Get details of the token assigned to a user -REST clients can log in to ThoughtSpot using their `username` and `password` or the token obtained from ThoughtSpot. If you send an API request with `usersame`, `password`, and bearer token in the `Authorization` header, the user credentials take precedence over the token specified in the `Authorization` header. +To get the authentication token assigned for the current user's session, send an API request to `/api/rest/2.0/auth/session/token`. +==== Example request + +.cURL [source,cURL] ---- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/session/login' \ - --header 'Authorization: Bearer dHNVc2VyQTpKSE5vYVhKdk1TUlRTRUV0TWpVMkpEVXdNREF3TUNSRmIxazVaa3BQTjFGR1VYTlRXa2xRUTJwaFVqbDNQVDBrTjBGR01FSlhiVGhzWmpaRWRYWjJWMkZYTm5KTlRGSlRibTlUTURCQ1V6RkdlR3N6TWpCbFRFVlhjejA=' +curl -X GET \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/session/token' \ + -H 'Accept: application/json' ---- -By default, the token obtained from ThoughtSpot is valid for 300 seconds. You can configure the token expiry duration as per your requirement or request a new token and use it in your subsequent API calls. If a REST client tries to make an API call with an expired token, the server returns an error. +==== Example response + +[source,JSON] +---- + { + "token": "{AUTH_TOKEN}" + "creation_time_in_millis":1704471154477 + "expiration_time_in_millis":1704557554477 + "valid_for_user_id":"59481331-ee53-42be-a548-bd87be6ddd4a" + "valid_for_username":"tsadmin" + } +---- -[TIP] -==== -If you are accessing the REST API outside a web browser, create a long-lived session object in your code, and then call the login API using that session object. Make subsequent REST API calls with the same session object to send the cookies along with the other aspects of the particular REST API call. -==== -== Revoke a token +=== Revoke a token To revoke a token, send a `POST` request with the following attributes to the `/api/rest/2.0/auth/token/revoke` endpoint. -=== Request parameters +===== Request parameters [width="100%" cols="1,4"] [options='header'] @@ -498,14 +549,14 @@ To revoke a token, send a `POST` request with the following attributes to the `/ |__String__. Token issued for the user specified in `user_identifier`. |===== -=== Example request +===== Example request .cURL [source, cURL] ---- curl -X POST \ --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/token/revoke' \ - -H 'Authorization: Bearer {admin_access_token}'\ + -H 'Authorization: Bearer {AUTH_TOKEN}'\ -H 'Content-Type: application/json' \ --data-raw '{ "user_identifier": "tsUserA, @@ -513,18 +564,11 @@ curl -X POST \ }' ---- -.Request URL - ----- -https://{ThoughtSpot-host}/api/rest/2.0/auth/token/revoke ----- - -=== Example response +===== Example response If the API request is successful, the access token is revoked, and the current user session becomes invalid. Before making another API call, you must obtain a new token. - -=== Response codes +===== Response codes [options="header", cols="1,4"] |==== @@ -541,16 +585,6 @@ If the API request is successful, the access token is revoked, and the current u To get details of the session object for the currently logged-in user, send a `GET` request to the `GET /api/rest/2.0/auth/session/user` endpoint. -=== Resource URL - ----- -GET /api/rest/2.0/auth/session/user ----- - -=== Request parameters - -None - === Example request .cURL @@ -558,16 +592,10 @@ None ---- curl -X GET \ --url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/session/user' \ - -H 'Authorization: Bearer {OAUTH_TOKEN}'\ + -H 'Authorization: Bearer {AUTH_TOKEN}'\ -H 'Accept: application/json' ---- -.Request URL - ----- -https://{ThoughtSpot-host}/api/rest/2.0/auth/session/user ----- - === Example response If the API request is successful, ThoughtSpot returns the following response: @@ -686,11 +714,6 @@ If the API request is successful, ThoughtSpot returns the following response: To log out of your current session, send a `POST` request to the `/api/rest/2.0/auth/session/logout` API endpoint. -=== Resource URL ----- -POST /api/rest/2.0/auth/session/logout ----- - === Example request .cURL @@ -702,14 +725,9 @@ curl -X POST \ -H 'Accept-Language: application/json' ---- -.Request URL ----- -https://{ThoughtSpot-host}/api/rest/2.0/auth/session/logout ----- - === Example response -If the API request is successful, the currently logged-in user is signed out of ThoughtSpot. +If the API request is successful, ThoughtSpot returns the 204 response code and ends the user session. === Response codes 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..d48c29bce 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] @@ -70,7 +71,7 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/events-app-integration[Events and app interactions] *** link:{{navprefix}}/runtime-filters[Runtime overrides] **** link:{{navprefix}}/runtime-filters[Runtime filters] -**** link:{{navprefix}}/runtime-params[Runtime parameter overrides] +**** link:{{navprefix}}/runtime-params[Runtime Parameter overrides] *** link:{{navprefix}}/custom-action-intro[Custom actions] **** link:{{navprefix}}/customize-actions[Create and manage custom actions] **** link:{{navprefix}}/edit-custom-action[Set the position of a custom action] @@ -85,6 +86,7 @@ include::generated/typedoc/CustomSideNav.adoc[] **** link:{{navprefix}}/custom-css[Customize CSS] *** link:{{navprefix}}/customize-links[Customize links] *** link:{{navprefix}}/action-config[Show or hide menu items] +**** link:{{navprefix}}/actions[Actions reference] *** link:{{navprefix}}/full-app-customize[Customize full application embedding] *** link:{{navprefix}}/in-app-navigation[Customize navigation components] *** link:{{navprefix}}/set-locale[Customize locale] @@ -111,6 +113,7 @@ include::generated/typedoc/CustomSideNav.adoc[] **** link:{{navprefix}}/rest-apiv2-users-search[Search users] **** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] **** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] +*** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] ** link:{{navprefix}}/restV2-playground[REST API v2.0 Reference] ** link:{{navprefix}}/rest-api-v1[REST API v1] 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/css-customization.adoc b/modules/ROOT/pages/css-customization.adoc index 0c8403d83..bcb309c4e 100644 --- a/modules/ROOT/pages/css-customization.adoc +++ b/modules/ROOT/pages/css-customization.adoc @@ -375,6 +375,25 @@ CSS variables for dialogs that prompt the user to select an option or enter info |`--ts-var-dialog-footer-background`|Background color of the footer area on dialogs. |====== +==== Natural Language Search interface +The Natural Language Search interface is also referred to as Sage Search. The Sage Search interface includes several elements such as the header, search bar, suggested queries, and sample questions panel. + +[width="100%" cols="7,7"] +[options='header'] +|====== +| `--ts-var-sage-bar-header-background-color` | Background color of the header bar on the Sage Search page. +| `--ts-var-source-selector-background-color`| Background color of the data source selector. +| `--ts-var-sage-search-box-font-color`| Font color of the search text. +| `--ts-var-sage-search-box-background-color`| Background color of the Sage search box. +| `--ts-var-sage-embed-background-color` | Background color of the Answer page generated from a Sage Search query. +|`--ts-var-sage-seed-questions-background`| Background color of the sample questions panel. +| `--ts-var-sage-seed-questions-font-color`| Font color of the search query text in the sample questions panel. +|`--ts-var-sage-seed-questions-hover-background`| Background color of the sample question panel on hover +|`--ts-var-sage-bar-img-url`| URL path of the search icon on the header bar. +|`--ts-var-sage-bar-img-color`| Color of the search icon on the header bar. +|`--ts-var-sage-bar-img-visibility`| Visibility of the search icon on the header bar. +|====== + === UI element reference The following figures show the customizable elements and example definitions for CSS variables. diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc new file mode 100644 index 000000000..759c46dfd --- /dev/null +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -0,0 +1,353 @@ += Data and Report APIs +:toc: true +:toclevels: 2 + +:page-title: data-apis +:page-pageid: fetch-data-and-report-apis +:page-description: Data and Report APIs + +== Data APIs +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. +* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. +* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. + +=== Search data API + +The `/api/rest/2.0/searchdata` endpoint requires you to specify data source object ID and query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. + +==== Data source +To search data via API call, you require at least view access to the data source object. The data source object can be a Worksheet, View, or Table. + +You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Worksheets, Views, or Tables in a single API request. + +To find the GUID of the Worksheet, View, or Table, use one of the following methods: + +Get data object GUID via API:: + +Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + + ++ +.**Example** +[source,JSON] +---- + "metadata": [ + { + "identifier": "my_worksheet", + "type": "LOGICAL_TABLE" + } + ] +---- + ++ +If you don't know the exact name of the data source object, you can search metadata by specifying the `type` as `LOGICAL_TABLE` and examine the API response and copy the GUID of the data object. + +Find the GUID of the data object via UI:: +. Log in to your ThoughtSpot application instance: +. Navigate to *Data*. ++ +---- +https:///#/data/tables/ +---- +. On the **Data** > **Home** page, click on data object type. For example, if the data source object is a Worksheet, click **Worksheets** and open the Worksheet. +. In the address bar of the web browser, note the GUID of the data object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: ++ +---- +https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f +---- +. Copy the GUID. + +==== Search query + +include::{path}/search-query-string.adoc[] + +.**Example** +[source,JSON] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Authorization: Bearer {access-token} + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query_string": "[sales][store]", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", +}' +---- + +=== Fetch Liveboard Data API +To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, you require at least view access to the Liveboard. + +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. + +.**Example** +[source,JSON] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "data_format": "COMPACT", + "visualization_identifiers": [ + "a9655c18-9855-4a73-9e7b-ff4fb6da334b", + "bf4c9814-82c1-4ec4-b879-57eae2134cb4", + "8c46d2b6-94c7-4ba7-a628-6e74e297f973", + "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" + ] +}' +---- + +[#transient-lb-content] +==== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +.**Sample browser fetch request** + +[source,JavaScript] +---- +< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> +< script src = "/path/to/liveboard.js" > < /script> +< script > + const embed = new LiveboardEmbed("#embed", { + frameParams: {}, + }); + async function liveboardData() { + const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); + const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/metadata/liveboard/data", { + method: "POST", + body: createFormDataObjectWith({ + "data_format": "COMPACT", + "transient_content": transientPinboardContent, + }), + }); + } +< /script> +---- + +=== Fetch Answer Data API +To get data from saved Answer object via `POST /api/rest/2.0/metadata/answer/data` endpoint, you require at least view access to the saved Answer. + +The API request body must include the name or GUID of the saved Answer. + +.**Example** +[source,JSON] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", +}' +---- + +== Report APIs + +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + +Download data from a Liveboard in the PDF, PNG, CSV, or XLSX file format. +* xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + +Download data from a saved Answer in the 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` privilege and at least view access to the Liveboard. + +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`. + +The default `file_format` is CSV. For PDF and PNG file format, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. +For PNG file format, you can include cover page and filters. + +.**Example** +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG", + "visualization_identifiers": [ + "9bd202f5-d431-44bf-9a07-b4f7be372125", + "9bd202f5-d431-44bf-9a07-b4f7be372125", + "9bd202f5-d431-44bf-9a07-b4f7be372125" + ], + "png_options": { + "include_cover_page": true, + "include_filter_page": true + } +}' +---- + +[#transient-lb-content] +==== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +.**Sample browser fetch request** + +[source,JavaScript] +---- +< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> +< script src = "/path/to/liveboard.js" > < /script> +< script > + const embed = new LiveboardEmbed("#embed", { + frameParams: {}, + }); + async function liveboardData() { + const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); + const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { + method: "POST", + body: createFormDataObjectWith({ + "transient_content": transientPinboardContent, + }), + }); + } +< /script> +---- + +=== 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. + +In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. + +You can download thw Answer data in the `PNG`, `PDF`, `CSV`, or `XLSX` format. The default `file_format` is CSV. + +.**Example** + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125", + "file_format": "PNG" +}' +---- + +== Pagination settings for Data and Report APIs + +When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: + +[source,JSON] +---- +{ + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +} +---- + +You can set `record_size` to `-1` and `record_offset` to `0` for precise and complete results. The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. + +== Runtime overrides +The Data API endpoints support the following runtime overrides: + +* Runtime filters +* Runtime sorting of columns +* Runtime Parameters + +=== Runtime filters +To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", +} +---- + +To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", + "col2": "tea", + "op2": "EQ", + "val2": "barley" +} +---- + +Some operators such as allow more than one value in the `val` parameter: + +[source,JSON] +---- + "runtime_filter": { + "col1": "tea", + "op1": "CONTAINS", + "val1": [ + "barley", + "mint" + ], + "col2": "type", + "op2": "CONTAINS", + "val2": [ + "roasted", + "loose leaves" + ] +} +---- + +For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. + +=== Runtime parameters + +To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. + +To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Worksheet used for generating Liveboard visualizations and Answer. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5 + } +---- + +To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5, + "param2": "Date Param", + "paramVal2": 1696932000 + } +---- + +For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. + +=== Runtime sort + +To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. + + +[source,JSON] +---- + "runtime_sort": { + "sortCol1": "sales", + "asc1": true, + "sortCol2": "region", + "asc2": false + } +---- + +For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. + diff --git a/modules/ROOT/pages/developer-playground.adoc b/modules/ROOT/pages/developer-playground.adoc index 31237b404..82c952085 100644 --- a/modules/ROOT/pages/developer-playground.adoc +++ b/modules/ROOT/pages/developer-playground.adoc @@ -1,5 +1,6 @@ = Visual Embed Playground :toc: true +:toclevels: 2 :page-title: Visual Embed Playground :page-pageid: dev-playground @@ -20,20 +21,18 @@ 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. - +. Try out the following customization settings and click *Run* to preview the result. ++ [width="100%"] |==== -a|**Collapse data panel** - +| +a|**Collapse data panel** + Minimizes the data panel on the left navigation bar. - ++++ Try it out ++++ - -a|**Hide data panel** +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. @@ -49,16 +48,49 @@ Hides the charts and tables that appear beneath the search bar by default. For e Try it out ++++ -a|**Modify available actions** +a|**Modify available actions** + include::{path}/modify-available-actions.adoc[] -a|**Add search tokens** +++++ +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 constructing a TML-based search query string to set search tokens and execute search. +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: { @@ -66,14 +98,89 @@ searchOptions: { executeSearch: true, } ---- - + ++++ Try it out ++++ -|*Handle custom actions* +a|*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 +++++ + +a|Use Host Event +Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. + +++++ +Try it out +++++ +a|**Apply custom styles** + +Shows the code for interface customization. You can define custom styles and define CSS variables to change the look and feel of the embedded components. +For more information about CSS variables, styles, and customizations options, see xref:css-customization.adoc[Customize CSS]. + +++++ +Try it out +++++ +| +|==== + +[#playground-nls-search] +== Natural Language Search + +To explore the Search embed function: + +. Go to *Playground* > *Natural Language Search*. +. Select a Worksheet. +. +++Try out+++ the following customization settings and click *Run* to preview the result. + ++ +[width="100%"] +|==== +| +a|**Disable changing worksheet** + +Disables the Worksheet selection option. Users can search data only from the Worksheet specified in the SDK. + +a|**Hide worksheet selector** + + +Hides Worksheet selector. Users can search data only from the Worksheet specified in the SDK. + +a|**Add search query** + + +Allows you to define search query and execute search. + + +[source, Javascript] +---- +searchOptions: { + searchQuery: 'average sales by country and product type', + executeSearch: true, +} +---- + +a|**Hide sample questions** + +Hides the AI-Suggested sample questions. + +a|**Modify available actions** + + +include::{path}/modify-available-actions.adoc[] + +a|*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. + +a|**Use Host Event** + +Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. + +a|**Apply custom styles** + +Shows the code for interface customization. You can define custom styles and define CSS variables to change the look and feel of the embedded components. +For more information about CSS variables, styles, and customizations options, see xref:css-customization.adoc[Customize CSS]. +| |==== [#playground-visualization] @@ -84,10 +191,9 @@ To explore the visualization embedding function: . 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[] @@ -114,18 +220,29 @@ runtimeFilters: [{ For more information, see xref:runtime-filters.adoc[Runtime filters]. -|**Handle custom actions** +a|**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. -|**Enable Search Assist** +++++ +Try it out +++++ -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. +a|Use Host Event +Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. ++++ -Try it out +Try it out ++++ +a|**Apply custom styles** +Shows the code for interface customization. You can define custom styles and define CSS variables to change the look and feel of the embedded components. +For more information about CSS variables, styles, and customizations options, see xref:css-customization.adoc[Customize CSS]. + +++++ +Try it out +++++ +| |==== [#playground-liveboard] @@ -149,7 +266,6 @@ If the embedded Liveboard does not fit vertically within your application page, Try it out ++++ - a|**Modify available actions ** include::{path}/modify-available-actions.adoc[] @@ -176,9 +292,29 @@ runtimeFilters: [{ For more information, see xref:runtime-filters.adoc[Runtime filters]. -|*Handle custom actions* +a|*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 +++++ + +a|**Use Host Event** +Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. + +++++ +Try it out +++++ + +a|**Apply custom styles** + +Shows the code for interface customization. You can define custom styles and define CSS variables to change the look and feel of the embedded components. +For more information about CSS variables, styles, and customizations options, see xref:css-customization.adoc[Customize CSS]. + +++++ +Try it out +++++ |==== [#playground-fullapp] @@ -201,6 +337,15 @@ Displays the ThoughtSpot top navigation bar. By default, the navigation bar is h ++++ Try it out ++++ + +a|**Hide profile and help** + + +Hides the user profile and help icons in the top navigation bar. + +++++ +Try it out +++++ + a|**Navigate to URL** Allows you to define a specific URL path for loading a ThoughtSpot application page. @@ -234,9 +379,29 @@ runtimeFilters: [{ For more information, see xref:runtime-filters.adoc[Runtime filters]. -|**Handle custom actions** +a|**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 +++++ + +a|**Use Host Event** +Allows registering a host event. The registered event triggers an action in the embedded on clicking **Try Event**. + +++++ +Try it out +++++ + +a|**Apply custom styles** + +Shows the code for interface customization. You can define custom styles and define CSS variables to change the look and feel of the embedded components. +For more information about CSS variables, styles, and customizations options, see xref:css-customization.adoc[Customize CSS]. + +++++ +Try it out +++++ |==== == Related information diff --git a/modules/ROOT/pages/embed-action-ref.adoc b/modules/ROOT/pages/embed-action-ref.adoc index d0d9ba140..149342c0f 100644 --- a/modules/ROOT/pages/embed-action-ref.adoc +++ b/modules/ROOT/pages/embed-action-ref.adoc @@ -30,7 +30,7 @@ Opens Liveboard in the edit mode. |`Action.AddFilter` a| `LiveboardEmbed` + `AppEmbed` |*Add filters* + -Allows filters to visualizations in a Liveboard. +Adds filters to visualizations on a Liveboard. |`Action.ConfigureFilter` a| `LiveboardEmbed` + `AppEmbed` @@ -81,7 +81,6 @@ Displays information about the Liveboard. Deletes a Liveboard. |==== - [#liveboardv2-viz-actions] == Visualizations on a Liveboard (New experience) The following actions are available for ThoughtSpot visualizations pinned to a Liveboard: @@ -108,8 +107,19 @@ Pins a visualization to a Liveboard. Displays detailed information and raw data for a given visualization. Available as a contextual menu action |`Action.Download`|`LiveboardEmbed` + -`AppEmbed`|*Download* + -The Download submenu with actions to download a visualization as CSV, PDF, PNG, and XLSX. +`AppEmbed` a|*Download* + +The **Download** menu action to download a visualization as CSV, PDF, PNG, and XLSX. + +If you are using Visual Embed SDK version 1.21.0 or later, note the following behavior: + + +* To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. +* If you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` + +==== |`Action.DownloadAsCsv`|`LiveboardEmbed` + `AppEmbed` |*Download* > *CSV* + Downloads the answer data in the CSV file format. @@ -217,19 +227,19 @@ Downloads the Liveboard as a PDF file. Presents the Liveboard in fullscreen mode. |`Action.SchedulesList`| `LiveboardEmbed` + `AppEmbed` | *Manage schedules* + - Allows you to manage Liveboard jobs. +Allows you to manage Liveboard jobs. |`Action.LiveboardInfo`|`LiveboardEmbed` + `AppEmbed` | *Liveboard info* + Displays information about the Liveboard.| - + `Action.EditTML`|`AppEmbed` | *Edit TML* + -Allows editing the ThoughtSpot Modelling Language (TML) representation of a Liveboard object loaded on the ThoughtSpot server. +Allows editing the ThoughtSpot Modelling Language (TML) representation of a Liveboard object loaded on the ThoughtSpot server. |`Action.ImportTML`|`AppEmbed` | *Import TML* + -Allows importing the TML representation of a Liveboard object to ThoughtSpot. +Allows importing the TML representation of a Liveboard object to ThoughtSpot. |`Action.ExportTML`| `LiveboardEmbed` + `AppEmbed` | *Export TML* + -Exports the TML representation of a Liveboard object from ThoughtSpot. +Exports the TML representation of a Liveboard object from ThoughtSpot. |`Action.UpdateTML`|`LiveboardEmbed` + `AppEmbed` | *Update TML* + Publishes the modified TML representation of a Liveboard object. @@ -288,7 +298,7 @@ Removes the visualization from the Liveboard. Allows resizing a visualization on a Liveboard.| `Action.DrillDown`|`LiveboardEmbed` + `AppEmbed`|*Drill down* + - Allows drilling down the visualization to get granular data. Available as a contextual menu action. +Allows drilling down the visualization to get granular data. Available as a contextual menu action. |`Action.DrillExclude`|`LiveboardEmbed` + `AppEmbed`|*Exclude* + Allows you to exclude a specific data point on a search answer. Available as a contextual menu action. @@ -313,6 +323,18 @@ The following actions are available for saved answers and the answers generated [options='header'] |=== |Action string in SDK| Required SDK library|Action label in the UI +|`Action.ChooseDataSources`| `SearchEmbed` + +`SearchBarEmbed` + +`AppEmbed`| *Choose sources* option in the data panel on a Search page + +Allows selecting data sources from which you want to query data. + +|`Action.AddFormula`| `SearchEmbed` + +`SearchBarEmbed` + +`AppEmbed`| *Create formula* option in the data panel on a Search page + +Allows adding formulas to a search query. + +|`Action.AddParameter`| `SearchEmbed` + +`SearchBarEmbed` + +`AppEmbed`| *Add Parameters* option in the data panel on a Search page + +Allows adding parameters to a search Answer. |`Action.AnswerChartSwitcher`| `SearchEmbed` + `AppEmbed` | Chart toggle icon + Allows switching to the table or chart mode. @@ -336,11 +358,23 @@ a|The *Query visualizer* and *Query SQL* buttons in *Query details* + |`Action.Save`|`SearchEmbed` + `AppEmbed` | *Save* + - Saves the answer and any modifications made to the answer. +Saves the answer and any modifications made to the answer. |`Action.Download`|`SearchEmbed` + -`AppEmbed`|*Download* + -The Download submenu with actions to download the Answer data as CSV, PDF, PNG, and XLSX. +`AppEmbed` a|*Download* + +The **Download** action to download the Answer data as CSV, PDF, PNG, and XLSX. + +If you are using Visual Embed SDK version 1.21.0 or later, note the following behavior: + + +* To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. +* If you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following action enumerations along with `Action.Download` in the array: + + +** `Action.DownloadAsCsv` + +** `Action.DownloadAsPdf` + +** `Action.DownloadAsXlsx` + +** `Action.DownloadAsPng` + + |`Action.DownloadAsCsv`|`SearchEmbed` + `AppEmbed` |*Download* > *CSV* + Downloads the answer data in the CSV file format. @@ -393,10 +427,6 @@ Allows editing the TML representation of the answer object. This action is avail Allows importing the TML representation of an answer into ThoughtSpot. This action is available on the saved answers page. |`Action.UpdateTML`|`AppEmbed` | *Update TML* + Publishes the modified TML representation of an answer. -|`Action.AddParameter`| `SearchEmbed` + -`SearchBarEmbed` + -`AppEmbed`| *Add Parameters* option in the data panel on a Search page + -Allows adding parameters to a search Answer. + |=== == Axis and column customization actions on charts and tables @@ -509,16 +539,17 @@ The following action enumerations are available for the menu actions on the *Dat [options='header'] |=== |Action string in SDK| Required SDK library|Action label in the UI -|`Action.Share`|`AppEmbed` | *Share* action on the *Data* > *Home* page+ -Allows sharing a saved Answer with another user or group. +|`Action.Share`|`AppEmbed` | *Share* action on the *Data* > *Home* page + +Allows sharing a Worksheet, Table, or View with another user or group. |`Action.Remove`|`AppEmbed` | *Delete* action on the *Data* > *Home* and *Data* > *Connections* pages + -Allows deleting an Answer. +Allows deleting a Worksheet, Table, or View. |`Action.ExportTML`| `AppEmbed` | *Export TML* action on the *Data* > *Home* page + -Allows exporting a saved Answer as a TML object. +Allows exporting a Worksheet, Table, or View as a TML file. |`Action.EditTML`| `AppEmbed` | *Edit TML* action on the *Data* > *Home* page + -Opens the TML Editor that allows you to modify the properties of an Answer object. +Opens the TML Editor that allows you to modify the TML file of Worksheet, Table, or View. |=== + == Additional resources * For information about showing or hiding UI actions, see xref:embed-actions.adoc[Show or hide actions]. -* See also link:{{visualEmbedSDKPrefix}}/enums/Action.html[Action, window=_blank]. +* See also xref:Action.adoc[Actions]. \ No newline at end of file diff --git a/modules/ROOT/pages/embed-actions.adoc b/modules/ROOT/pages/embed-actions.adoc index 2d17cfc14..75906717f 100644 --- a/modules/ROOT/pages/embed-actions.adoc +++ b/modules/ROOT/pages/embed-actions.adoc @@ -36,10 +36,10 @@ For example, if you set the attribute as: [source,Javascript] ---- -visibleActions: [Action.Save,Action.ShowUnderlyingData,Action.DownloadAsCSV,Action.Pin] +visibleActions: [Action.Save,Action.ShowUnderlyingData,Action.Download,Action.DownloadAsCSV,Action.Pin] ---- -only the actions specified in the `visibleActions` attribute will appear in the embedded UI. The embedded application users can access and use the **Save**, **Show underlying data**, *Download as CSV*, and *Pin* menu actions. +Only the actions specified in the `visibleActions` attribute will appear in the embedded UI. The embedded application users can access and use the **Save**, **Show underlying data**, *Download as CSV*, and *Pin* menu actions. ++++ 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] +---- +