diff --git a/modules/tutorials/pages/rest-api/rest-api-intro.adoc b/modules/tutorials/pages/rest-api/rest-api-intro.adoc index a1857d2c6..2d0ecd835 100644 --- a/modules/tutorials/pages/rest-api/rest-api-intro.adoc +++ b/modules/tutorials/pages/rest-api/rest-api-intro.adoc @@ -23,7 +23,7 @@ Your setup must have the following applications and tools installed: * Chrome or Firefox * Python 3.8 or higher * link:https://code.visualstudio.com/[Visual Studio Code, window=_blank] or link:https://www.jetbrains.com/pycharm/[PyCharm, window=_blank] -* link:https://github.com/thoughtspot/thoughtspot_rest_api_python[The `thoughtspot_rest_api` GitHub repository, window=_blank] (supports REST API V1 and V2.0) in your local Python environment +* link:https://github.com/thoughtspot/thoughtspot_rest_api_python[The `thoughtspot_rest_api` GitHub repository, window=_blank] (supports REST API V1 and V2.0), installed in your local Python environment with `python3 -m pip install thoughtspot_rest_api` Download the entire link:https://github.com/thoughtspot/tse-api-tutorial[tse-api-tutorial repository, window=_blank] as a ZIP file from GitHub, then unzip it on your system: diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc index dfb69b6cb..f8d5edcb7 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-01.adoc @@ -51,7 +51,7 @@ Reports:: exports in a file format Security:: permissions and access control (sharing) Data:: exports in a JSON data format -Once you click on an individual endpoint, you will see the specification for that endpoint in the middle area, and an example of using cURL to issue the request to the endpoint properly on the left: +Once you click on an individual endpoint, you will see the specification for that endpoint in the middle area, and an example of using cURL to issue the request to the endpoint properly on the right: [.widthAuto] [.bordered] @@ -77,15 +77,15 @@ DELETE:: delete, often only has a URL (but some systems use a body) [NOTE] ==== -ThoughtSpot REST API V2.0 only uses *GET* and *POST* verbs. +ThoughtSpot REST API V2.0 mostly uses *POST* and *GET* verbs. A few endpoints use *PUT* or *DELETE*. The full endpoint name includes the action the endpoint will take, rather than the same endpoint responding to different HTTP verbs. ==== -Any endpoint that ends in `/search` is a `GET` request for querying information. +Most endpoints that end in `/search` are `POST` requests for querying information. The criteria for the search are sent as a JSON body, which is required even if it is empty (`{}`). === HTTP headers -Headers describe aspects of the request, and are mandatory for any given endpoint. +Headers describe aspects of the request, and some are required for any given endpoint. ThoughtSpot's V2.0 REST API typically requires the following headers: ---- @@ -98,7 +98,7 @@ The endpoints to request access tokens do not require the `Authorization` header Endpoints that return something other than a JSON response do not use the `Accept: application/json` header. === HTTP Body -Body is data sent with the request, that does not appear in the URL (is secure). The body will vary with each endpoint, and some endpoints do not require a body at all. +Body is data sent with the request, that does not appear in the URL. The body will vary with each endpoint, and some endpoints do not require a body at all. The body of all V2.0 REST API requests will be in JSON format. @@ -111,7 +111,7 @@ You can copy the JSON request from the Playground and use directly in JavaScript == 03 - HTTP responses Each HTTP request will result in some action within the web server and then a *response*. -For *GET* requests, the only expected action is a *response* with some element. For example, the `/search` endpoints within the V2.0 REST API are *GET* requests that return sets of information about the system. +For requests that only read information, the only expected action is a *response* with some element. For example, the `/search` endpoints within the V2.0 REST API are *POST* requests that return sets of information about the system without changing it. Other types of requests cause a state change on the server, and then a response describing the new state after the action has completed. diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc index 09465f8d9..276196a16 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-02.adoc @@ -6,7 +6,7 @@ [IMPORTANT] ==== -The workflows and examples in this tutorial use a legacy version of the ThoughtSpot REST API link:https://github.com/thoughtspot/thoughtspot_rest_api_python[ThoughtSpot Community SDK, window=_blank]. We recommend using the xref:python-sdk.adoc[ThoughtSpot-provided Python SDK for REST API v2], which supports both asynchronous and synchronous invocation, transparent token refresh, server-sent event (SSE) streaming, file uploads and downloads, and error handling. +The workflows and examples in this tutorial use a legacy version of the ThoughtSpot REST API link:https://github.com/thoughtspot/thoughtspot_rest_api_python[ThoughtSpot Community SDK, window=_blank]. We recommend using the xref:rest-api-python-sdk.adoc[ThoughtSpot-provided Python SDK for REST API v2], which supports both asynchronous and synchronous invocation, transparent token refresh, server-sent event (SSE) streaming, file uploads and downloads, and error handling. ==== == Get started @@ -14,14 +14,12 @@ We'll use the files from the link:https://github.com/thoughtspot/tse-api-tutoria . Open your IDE + Visual Studio Code will be used in all images and instructions. -The files for this lesson are `api_training_python_1_begin.py` and `api_training_python_1_end.py`. +The files for this lesson are `api_training_python_1_begin.py` and `api_training_python_1_final.py`. . Open up your command line or terminal environment as well. [NOTE] ==== -There are many ways to install and configure Python on a system. This tutorial shows "plain" versions of all commands as if you are using the main system-wide install of Python for the tutorial. - -Please adjust all Python commands according to your own environment. +The commands in this tutorial are the basic versions, which assume that you use the system-wide Python installation. If your environment is different, for example a virtual environment, adjust the Python commands accordingly. ==== == 01 - Imports and variables @@ -101,7 +99,9 @@ requests_session = requests.Session() requests_session.headers.update(api_headers) # Define the JSON message, in Python object syntax (close but not exactly JSON) -json_post_data = { # a request body } +json_post_data = { + # a request body +} # Set the URL of the endpoint url = base_url + "{api_endpoint_ending}" @@ -175,7 +175,7 @@ image:images/tutorials/rest-api/python-command-in-terminal.png[Running script in If you have a more complex local Python environment you are using, find the appropriate way to send the script you have updated through the Python environment set up for this tutorial. === Update the Session object headers -Almost all REST API endpoints other than the token requests require authentication, either within the cookies or via an `Authentication: Bearer {token}` header. +Almost all REST API endpoints other than the token requests require authentication, either within the cookies or via an `Authorization: Bearer {token}` header. You need to update the `Session` object with this new header while keeping the original ones. @@ -219,6 +219,7 @@ try: except Exception as e: # do whatever is necessary in exception case + print(e) # Code after the try block will now run even after Exception ---- @@ -236,7 +237,7 @@ try: resp = requests_session.post(url=url, json=json_post_data) resp.raise_for_status() print(resp) - token = resp["token"] + token = resp.json()["token"] except requests.exceptions.HTTPError as e: print(e) print(e.request) @@ -258,6 +259,15 @@ thoughtspot_url = 'https://{}.thoughtspot.cloud' org_id = 0 api_version = '2.0' +base_url = '{thoughtspot_url}/api/rest/{version}/'.format(thoughtspot_url=thoughtspot_url, version=api_version) +api_headers = { + 'X-Requested-By': 'ThoughtSpot', + 'Accept': 'application/json' +} + +requests_session = requests.Session() +requests_session.headers.update(api_headers) + endpoint = 'auth/token/full' url = base_url + endpoint @@ -293,6 +303,7 @@ except requests.exceptions.HTTPError as e: print(e.request.headers) print(e.request.body) print(e.response.content) + exit() # Stop here, because there is no token to use # Update api_headers from before with header for Bearer token api_headers['Authorization'] = 'Bearer {}'.format(token) @@ -305,9 +316,13 @@ user_search_url = base_url + "users/search" # Every request must be wrapped in try...except try: - search_resp = requests_session.get(url=user_search_url) + # Search endpoints are POST requests and need a JSON body, even if it is only {} + search_resp = requests_session.post(url=user_search_url, json={"record_offset": 0, "record_size": 10}) search_resp.raise_for_status() -... + print(json.dumps(search_resp.json(), indent=2)) +except requests.exceptions.HTTPError as e: + print(e) + print(e.response.content) ---- You may have noticed many steps that are repeated each time for any given request. diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc index a205c4325..361fbb9a8 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-03.adoc @@ -5,7 +5,7 @@ :toc!: == Get started -The files for this tutorial are `api_training_python_2_begin.py` and `api_training_python_2_end.py`. +The files for this tutorial are `api_training_python_2_begin.py` and `api_training_python_2_final.py`. You must have installed the `thoughtspot_rest_api` library in the Python environment you are using, based on the tutorial prerequisites. Despite the name, the library has components for interacting with both the V1 and V2.0 ThoughtSpot REST APIs. @@ -180,7 +180,7 @@ The first of our tasks is: # Is this a case-sensitive or case-insensitive operation? Are we finding anywhere in the name or just at the start or end? ---- -Information about the objects in the system lives under the `Metadata` heading within the Playground. Endpoints labeled `Search` are `GET` methods that query information without causing any changes. +Information about the objects in the system lives under the `Metadata` heading within the Playground. Endpoints labeled `Search` are `POST` requests that query information without causing any changes. `/metadata/search` has many different xref:rest-api-v2-metadata-search.adoc[request parameters] available to help filter and select all of the necessary information. diff --git a/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc b/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc index effe6ca22..9a191ac52 100644 --- a/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc +++ b/modules/tutorials/pages/rest-api/rest-api_lesson-04.adoc @@ -112,7 +112,7 @@ const apiRequestObject = { The `fetch()` function in JavaScript uses the browser itself as a store of cookies and other details when you use the `credentials: "include"` parameter. -`fetch` is an asynchronous call that returns a `Promise`, which has `.then()` and `.error()` methods for calling the next code to run once the REST API response is returned: +`fetch` is an asynchronous call that returns a `Promise`, which has `.then()` and `.catch()` methods for calling the next code to run once the REST API response is returned: [source,javascript] ---- @@ -122,7 +122,7 @@ const apiFullEndpoint = tsHost + "/" + publicApiUrl + endpoint; await fetch( apiFullEndpoint, // URL { - method: ‘POST’, + method: 'POST', headers: { "Accept": "application/json", "X-Requested-By": "ThoughtSpot", @@ -159,7 +159,7 @@ const apiFullEndpoint = tsHost + "/" + publicApiUrl + endpoint; await tokenizedFetch( apiFullEndpoint, // URL { - method: ‘POST’, + method: 'POST', headers: { "Accept": "application/json", "X-Requested-By": "ThoughtSpot", @@ -276,7 +276,7 @@ To use such a function you define your request object, copied from the REST API [source,javascript] ---- // Here we actually CALL the functions to make the request -function makeSearchRequest(){ +async function makeSearchRequest(){ // Copy the request directly from the REST API Playground, substituting in any variables you need const apiRequestObject = { "metadata": [ @@ -294,7 +294,7 @@ function makeSearchRequest(){ } - let results = callMetadataSearchApi(apiRequestObject); + let results = await callMetadataSearchApi(apiRequestObject); console.log("Final results from the callMetadataSearchApi function: "); console.log(results); } diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc index 74b307c13..6184bccd8 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-02.adoc @@ -37,7 +37,7 @@ The code includes examples of several settings that are commented out using the . Click *Run* again to see the updated results. == Available options for component element customization -There are many more configurations available for each component than those available in the Playground. To see all available options, see link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_interfaces[Embed Classes^] and link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_interfaces[Embed Interfaces^]. +There are many more configurations available for each component than those available in the Playground. To see all available options, see link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_classes[Embed Classes^] and link:https://developers.thoughtspot.com/docs/VisualEmbedSdk#_interfaces[Embed Interfaces^]. [.bordered] diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc index 751027c1a..da9f72406 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-03.adoc @@ -69,7 +69,7 @@ Variables declare a __single__ property, therefore are defined as `"{var-name}" Selectors apply properties to elements with many layers of styling. Always add `!important` after each property to ensure the browser overrides whatever other style rules may be applied for the same property. ==== -One use case of the `rules_UNSTABLE` section is `xref:css-customization.adoc#font-declarations[@font-face]` declarations, which have many properties for one selector. +One use case of the `rules_UNSTABLE` section is xref:css-customization.adoc#_font_declarations[`@font-face`] declarations, which have many properties for one selector. We'll switch the main font to link:https://fonts.google.com/specimen/Poppins[Poppins^], available from Google Fonts: @@ -107,7 +107,7 @@ Notice the format shows the selector as the __key__, then an object block contai == CSS files You can collect a set of variables and selectors into a CSS file, rather than declaring them in the JavaScript code block. -CSS files can be included from any domain, but they must be added to the *CSP style-src domains* and *CSP font-src* domains on the *Develop* > *Customizations* -> *Security settings* page. +CSS files can be included from any domain, but they must be added to the *CSP style-src domains* and *CSP font-src domains* lists on the *Develop* > *Customizations* > *Security settings* page. Both `\https://cdn.jsdelivr.net` and `\https://fonts.gstatic.com` sites are automatically added to ThoughtSpot's CSP allowlist. @@ -118,7 +118,7 @@ In your CSS file, the global variables must be declared in the `:root { }` block :root { --ts-var-button--primary-background: #2359B6; --ts-var-button--primary--hover-background: blue; - --ts-var-button--primary--font-family: Poppins,Helvetica,Arial,sans-serif;; + --ts-var-button--primary--font-family: Poppins,Helvetica,Arial,sans-serif; } @font-face { @@ -141,7 +141,7 @@ As seen in the CSS file example above, one of the use cases for selectors is to Make sure that the selector you use is specific and does not affect other elements that you don't intend to hide. -If you have been hiding certain elements via CSS selectors, link:https://community.thoughtspot.com/s/ideas[contact ThoughtSpot^] to request configuration options for such elements, so that the overall configurations can be expanded over time. Similarly, provide feedback on properties that variables are unavailable by submitting an idea to the link:https://community.thoughtspot.com/s/ideas[ThoughtSpot Community^]. +If you have been hiding certain elements via CSS selectors, link:https://community.thoughtspot.com/s/ideas[contact ThoughtSpot^] to request configuration options for such elements, so that the overall configurations can be expanded over time. Similarly, provide feedback on properties for which variables are unavailable by submitting an idea to the link:https://community.thoughtspot.com/s/ideas[ThoughtSpot Community^]. ++++
diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc index 847d09907..5158167b2 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-04.adoc @@ -5,11 +5,11 @@ :page-pageid: style-customization__step-04 :page-description: Replace text strings and icon sprites in embedded ThoughtSpot content using the customizations framework. -The `customizations` object allows replacing replace specific xref:customize-text-strings.adoc[text strings] and xref:customize-icons.adoc[icons]. +The `customizations` object allows replacing specific xref:customize-text-strings.adoc[text strings] and xref:customize-icons.adoc[icons]. == Replace text strings -Let's add the `content` property above the `style` property in the `customizations` code and then add the `strings` property block within this code. Now we can declare the exact text elements to replace within ThoughtSpot: +Let's add the `content` property above the `style` property in the `customizations` code and then add the `strings` property block within this code. Now we can declare the exact text elements to replace within ThoughtSpot: [source,javascript] ---- @@ -23,7 +23,7 @@ customizations: { } }, style: { - ... + // ... your style settings from the previous step }, }, ---- @@ -45,7 +45,7 @@ customizations: { } }, style: { - ... + // ... your style settings from the previous step }, }, ---- diff --git a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc index 6e4e41fea..bb8d769c3 100644 --- a/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc +++ b/modules/tutorials/pages/style-customization/style-customization_tutorial-step-06.adoc @@ -7,7 +7,7 @@ This tutorial has covered how to customize the UI and UX of ThoughtSpot's embedded components, but only within the Visual Embed SDK Playground. -The next steps are to move this code into your application page and configure the CSP and CORS settings for your application's test environments, so you begin integrating ThoughtSpot directly into your application. +The next steps are to move this code into your application page and configure the CSP and CORS settings for your application's test environments, so that you can begin integrating ThoughtSpot directly into your application. ++++
diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc index c199d0f96..88154fb0e 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-intro.adoc @@ -1,7 +1,7 @@ = ThoughtSpot Embedding fundamentals :toc!: -:page-title: ThoughtSpot Embeddig fundamentals +:page-title: ThoughtSpot Embedding fundamentals :page-pageid: tse-fundamentals__intro :page-description: This is a self-guided course on ThoughtSpot Embedding Fundamentals. @@ -11,9 +11,9 @@ Each section is broken down into a concrete topic along with instructions on the == Requirements -This course was created using version 9.10.0.cl. -Features are regularly updated, so if you are using a more recent version, then things may have changed. -To use some features, your ThoughtSpot instance should be on a more recent release version. +ThoughtSpot features and the Visual Embed SDK are updated regularly, so the UI and code samples in this course may differ slightly from the version you are using. +To use some features, your ThoughtSpot instance and the Visual Embed SDK must be on a recent release version. +For the latest changes, see xref:whats-new.adoc[What's New]. == Resources @@ -23,15 +23,15 @@ For this tutorial, you will need the following: Google Chrome is recommended, but not required. All examples in this tutorial use Chrome. * Access to a ThoughtSpot instance with ThoughtSpot Embedded enabled. + -If you don't have an account, you can create a link:https://thoughtspot.com/trial?tsref=dev=stepbystep[trial account, window=_blank]. -* A code editor for editing the Javascript code. + +If you don't have an account, you can create a link:https://www.thoughtspot.com/trial?tsref=ts-dev-training[trial account, window=_blank]. +* A code editor for editing the JavaScript code. + The examples in this tutorial use link:https://code.visualstudio.com/[Visual Studio Code, window=_blank], a free editor that works on many operating systems. * A web server that will host static web content (.html, .css, .js files). The examples in this tutorial use the Live Server plug-in for Visual Studio Code. * A basic understanding of ThoughtSpot. + This can be obtained by taking introductory courses. For information about the courses you can take to learn the basics, see the link:https://training.thoughtspot.com/[ThoughtSpot Training site, window=_blank] for courses. -Ideally, you will have some experience with HTML and Javascript, but it's not required. +Ideally, you will have some experience with HTML and JavaScript, but it's not required. == Lessons This tutorial is split into smaller lessons, with specific objectives for each section. diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc index 60d6667f5..d394843a1 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-02.adoc @@ -48,11 +48,11 @@ image:images/tutorials/tse-fundamentals/lesson-02-doc-links.png[Access Guides fr To open the Playground, go to *Visual Embed SDK* > *Playground* on the *Develop* page. The playground lets you quickly and easily generate working code that you can embed into your application. -The following figure shows the Playground page for embedding Natural Language Search. +The following figure shows an example of the Playground page. [.widthAuto] [.bordered] -image:images/tutorials/tse-fundamentals/lesson-02-playground-sage-search.png[Using the playground to generate code, scale=50%] +image:images/tutorials/tse-fundamentals/lesson-02-playground-lb.png[Using the playground to generate code, scale=70%] The image above has three main sections: diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc index 49cd95c62..9b8cdd8d9 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc @@ -2,7 +2,7 @@ :toc!: :page-title: Security setup -:page-pageid: tse-fundamentals__lesson-03 +:page-pageid: tse-fundamentals__lesson-03 :page-description: This lesson covers the security setup necessary to embed ThoughtSpot into TSE applications. ThoughtSpot Embedded applications operate securely with ThoughtSpot. This lesson will walk you through the security setup required for embedding ThoughtSpot. @@ -24,11 +24,10 @@ Security when using ThoughtSpot and ThoughtSpot Embedded can be in the following [options='header'] |===== |Security setting| Managed at -|Embed / web security are the security settings that allow you to embed ThoughtSpot into your application|ThoughtSpot Embedded +|Embed / web security are the security settings that allow you to embed ThoughtSpot into your application. For more information, see <<_embed_web_security,Embed / web security>>.|ThoughtSpot Embedded |Authentication determines how you will authenticate the user with ThoughtSpot. Both the authentication supported by ThoughtSpot and ThoughtSpot Embedded have to be considered.| ThoughtSpot Embedded + ThoughtSpot Analytics application -|Content security is managed by ThoughtSpot to determine what content a user has access to, such as Tables, Models (formerly Worksheets), and Liveboards. Data security can be controlled separately | ThoughtSpot Analytics application. -For more information, see xref:_embed_web_security[the following sections]. +|Content security is managed by ThoughtSpot to determine what content a user has access to, such as Tables, Models (formerly Worksheets), and Liveboards. Data security can be controlled separately | ThoughtSpot Analytics application |System privileges / roles define what a user can do inside ThoughtSpot, such as downloading data or using SpotIQ.|ThoughtSpot Analytics application |Data security restricts the columns or rows of data from the source data. Data security is managed via row-level security settings or column sharing in ThoughtSpot. It can also be controlled using pass-through security to the Cloud data warehouse.| ThoughtSpot Analytics application |===== @@ -37,7 +36,7 @@ For more information, see xref:_embed_web_security[the following sections]. The embed and web security settings determine which applications can embed ThoughtSpot and make API calls via JavaScript (cross-site scripting). -Security settings are set on the *Developer > Customisations > Security Settings* page in the ThoughtSpot UI. You can see this page if you have Developer or Administrator privileges. To configure the settings, you will need administrator privileges. +Security settings are set on the *Develop* > *Customizations* > *Security settings* page in the ThoughtSpot UI. You can see this page if you have Developer or Administrator privileges. To configure the settings, you will need administrator privileges. [.widthAuto] [.bordered] @@ -47,7 +46,7 @@ The following are the most important settings for embedding ThoughtSpot. Except === CSP visual embed hosts -CSP visual embed hosts are the URLs that are permitted to embed ThoughtSpot. For example, `\https://mycoolapp.mycompany.com`. If your app URL is not in the list, then you will get CSP errors when embedding. For development, you can add localhost, but it's not recommended for production environments. You only need a port if you are using a non-standard port such as 80, 443. +CSP visual embed hosts are the URLs that are permitted to embed ThoughtSpot. For example, `\https://mycoolapp.mycompany.com`. If your app URL is not in the list, then you will get CSP errors when embedding. For development, you can add localhost, but it's not recommended for production environments. You only need to specify a port if you are using a non-standard port such as 8080. If you add `localhost` or any non-HTTPS domain, include the `http` protocol, for example `\http://localhost:8000`. === CSP connect-src domains @@ -55,9 +54,9 @@ The CSP connect-src domains are those domains that you can send data _to_. This === CORS trusted domains -Domains added to CORS allowlist can use cross-site scripting, that is, calling web service endpoints (including login) from a web application. Command-line applications and tools, such as CURL, are not impacted by this setting. The values are the list of domains (without protocol) and any non-standard ports, such as 8080. If CORS isn't set, you will see CORS errors in the console log for web service calls. +Domains added to CORS allowlist can use cross-site scripting, that is, calling web service endpoints (including login) from a web application. Command-line applications and tools, such as CURL, are not impacted by this setting. The values are the list of domains and any non-standard ports, such as 8080. You can omit the protocol for `https` domains, but you must include it for `localhost` and other non-HTTPS domains. If CORS isn't set, you will see CORS errors in the console log for web service calls. -You will need to add the CORS setting either in your system or the trial instance. Add `localhost:8000` if that's your URL. Note that `127.0.0.1` is not the same, so if you are using an IP, set that instead. +You will need to add the CORS setting either in your system or the trial instance. Add `\http://localhost:8000` if that's your URL. Note that `127.0.0.1` is not the same, so if you are using an IP, set that instead. For more details, see the link:https://developers.thoughtspot.com/docs/security-settings[security setting] documentation, which also includes constraints on values for the above settings. @@ -75,7 +74,8 @@ The following table lists the types of authentication, the associated link:https | SSO with iframe redirect | AuthType.EmbeddedSSO | SSO or OIDC when iframe redirect is supported by the IdP. | No | link:https://en.wikipedia.org/wiki/SAML_2.0[SAML] | AuthType.SAMLRedirect | SSO with SAML | Yes | link:https://openid.net/connect/[OIDC] | AuthType.OIDCRedirect | SSO with Open ID Connect | No -| Trusted Authentication | AuthType.AuthServer | ThoughtSpot token-based approach | Yes +| Trusted Authentication (cookie-based) | AuthType.TrustedAuthToken | ThoughtSpot token-based approach that creates a session cookie | Yes +| Trusted Authentication (cookieless) | AuthType.TrustedAuthTokenCookieless | ThoughtSpot token-based approach that doesn't depend on third-party cookies. Recommended for production. | Yes |=== Each of these approaches is explored in detail in the following sections. @@ -103,7 +103,7 @@ SAML configuration requires Administrator privileges in ThoughtSpot. It shows up [.bordered] image::images/tutorials/tse-fundamentals/lesson-03-saml-configuration.png[SAML configuration dialog] -Once you have the SAML federation set up for ThoughtSpot, you also have to enable the SAML redirect for the authentication. This is set from the *Developer | Security Settings*. If this value is not set, then you will get errors trying to redirect back to your application. +Once you have the SAML federation set up for ThoughtSpot, you also have to enable the SAML redirect for the authentication. This is set from the *Develop* > *Customizations* > *Security settings* page. If this value is not set, then you will get errors trying to redirect back to your application. [.widthAuto] [.bordered] @@ -126,7 +126,7 @@ Trusted authentication is a ThoughtSpot specific approach to authentication that [.bordered] image:images/tutorials/tse-fundamentals/lesson-03-saml-trusted-auth-config.png[Trusted auth configuration] -To enable trusted authentication you have to navigate to the Developer | Security Settings page and enable it via the toggle switch. Note that only an administrator can make this change. Once enabled, you will get a cluster wide key that you can copy and use in API calls. KEEP THIS KEY PRIVATE! It is a cluster wide key that allows you to create sessions on behalf of any user. +To enable trusted authentication you have to navigate to the *Develop* > *Customizations* > *Security settings* page and enable it via the toggle switch. Note that only an administrator can make this change. Once enabled, you will get a cluster wide key that you can copy and use in API calls. KEEP THIS KEY PRIVATE! It is a cluster wide key that allows you to create sessions on behalf of any user. NOTE: On instances with Orgs enabled, you can also enable trusted authentication at the org level in addition to the instance level. The token created can only be used to log into the given org. diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc index 041c3d018..2d1ad8307 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-04.adoc @@ -21,7 +21,7 @@ The examples here use link:https://code.visualstudio.com/[Visual Studio Code, wi == Make a copy of the code -You can work directly in the code you downloaded from GitHub, but it's usually better to create a copy, so you can always revert if needed The path you choose is entirely up to you. +You can work directly in the code you downloaded from GitHub, but it's usually better to create a copy, so you can always revert if needed. The path you choose is entirely up to you. Whichever approach you take, you should end up with a folder with the files shown below. diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc index 55af07228..7b57a2eda 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-05.adoc @@ -57,7 +57,7 @@ const onSearch = () => { Refresh the application and click on the Search link. You should see a message in the console window of the developer tools. If not, check for errors. -You can also reference the example code (in the `src` folder). +You can also reference the example code (in the `src-updates/05-src` folder in the link:https://github.com/thoughtspot/tse-fundamentals-step-by-step[tse-fundamentals-step-by-step repository, window=_blank]). [.widthAuto] [.bordered] @@ -125,13 +125,13 @@ image:images/tutorials/tse-fundamentals/lesson-05-data-source-added.png[data sou 2. Click on **Collapse data panel** to collapse the data panel in the embed. 3. Click on **Add search tokens**. This adds code for search options. -The `searchTokenString` uses a TML query. +The `searchTokenString` contains the search tokens (the search query) to run. Here's an example: [source,javascript] ---- searchOptions: { - searchTokenString: '[sales] by [item type]', // Example TML query + searchTokenString: '[sales] [item type]', // Example search query executeSearch: true, }, ---- @@ -159,8 +159,7 @@ Every embed component requires two steps: 2. Render the object (with optional event listeners). Copy the generated code from the Playground into the `onSearch` function after the `console.log` statement. -Be sure to change the ID from `#your-own-div` to `#embed` to match the `index.html` file. Note that all IDs will -be unique to your environment. +Be sure to change the ID from `#your-own-div` to `#embed` to match the `index.html` file. Note that all IDs will be unique to your environment. [source,javascript] ---- @@ -170,7 +169,7 @@ const embed = new SearchEmbed("#embed", { disabledActions: [Action.Download], disabledActionReason: "Permission required", hiddenActions: [Action.Share], - dataSources: ["4d98d3f5-5c6a-44eb-82fb-d529ca20e31f"], // Your data source ID + dataSource: "4d98d3f5-5c6a-44eb-82fb-d529ca20e31f", // Your data source ID searchOptions: { searchTokenString: '[sales] [item type]', executeSearch: true, @@ -193,7 +192,7 @@ const onSearch = () => { disabledActions: [Action.Download], disabledActionReason: "Permission required", hiddenActions: [Action.Share], - dataSources: ["4d98d3f5-5c6a-44eb-82fb-d529ca20e31f"], // Your data source ID + dataSource: "4d98d3f5-5c6a-44eb-82fb-d529ca20e31f", // Your data source ID searchOptions: { searchTokenString: "[sales] [item type]", executeSearch: true, @@ -229,7 +228,7 @@ However, with caching disabled during development, re-downloading will still occ 6. Add a `render()` call. 7. Test the code. -If you run into issues, you can reference the code in the `src` folder. +If you run into issues, you can reference the code in the `src-updates/05-src` folder in the link:https://github.com/thoughtspot/tse-fundamentals-step-by-step[tse-fundamentals-step-by-step repository, window=_blank]. == Files changed diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc index 25a1a71e0..016f68b18 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc @@ -3,138 +3,12 @@ :page-title: Lesson 6 - Embed Natural Language Search :page-pageid: tse-fundamentals__lesson-06 -:page-description: This lesson demonstrates embedding a Natural Language Search component into the application using the same pattern as earlier lessons. +:page-description: ThoughtSpot has deprecated embedding Natural Language Search with SageEmbed. For AI Search and conversational analytics, embed Spotter. -Now that you've embedded a search, you'll notice that the rest of the embedding follows the same basic pattern: - -* Create the component in the Playground. -* Add the component to your code and render it. - -In this lesson, we'll embed Natural Language Search components into the application. - -== Pre-conditions - -You should have already completed all the lessons through xref:tse-fundamentals-lesson-05.adoc[lesson 05]. - -== Add a nav link and function for the natural language search - -First, add a nav link for the natural language embed. In the `index.html` file, add a new `
  • ` for the natural language search page. We'll also add a pipe character `|` as a separator in the menu. Your code should look like this: - -[source,html] ----- - ----- - -Now run the application to verify everything is working. You should see the Search and Natural Language links in the menu. - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-new-sage-link.png[Nav bar with sage link added] - -== Add a listener for the search link - -In `tse.js`, add the following line of code to register a listener for the click event. When clicked, it will call the `onSage` function. Place this after the listener added in the previous lesson. The event listener section should now have two listeners. - -[source,javascript] ----- -document.getElementById("search-link").addEventListener("click", onSearch); -document.getElementById("sage-link").addEventListener("click", onSage); ----- - -Next, add the `onSage` function. Initially, this will just log a message to the console to confirm it's being triggered. - -[source,javascript] ----- -const onSage = () => { - console.log('using natural language search'); -} ----- - -Refresh the application and click the Natural Language link. You should see the console log message in the developer tools. If not, check for errors. - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-console-message.png[Console message showing onSage was called] - -== Generate a natural language search to embed - -If you're not already in the Visual SDK playground, navigate there and select **Natural Language Search** from the dropdown menu. You should see an empty page with the Natural Language Search bar as shown here: - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-empty-sage-embed.png[empty sage search embed in the playground] - -Let's review the SageEmbed-specific settings and configure the embed. - -* The `Select data source` dropdown is similar to what we used for the Search embed. It will display any Models enabled for natural language search. Select one from the dropdown to update the code with the data source's GUID. - -Unlike the Search embed, you can only have one data source for natural language search, and a data source is always required for natural language search, though it can be user-provided. - -Now, set some additional options: - -* **Disable changing model**: Prevents the user from changing the pre-selected data source. -* **Hide Sage Answer header**: Hides the "AI answer" header in the results. -* **Add search query**: Predefines a text query to run automatically, similar to the search embed. - -For this exercise, select the options **Disable changing model**, **Hide Sage Answer header**, and **Add search query**. Enter a search query, then press **Run**. You should see a result like this: - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-sage-embed-playground.png[complete sage embed in the playground] - -== Embed the natural language search into the application - -Now that we've created the natural language embed component using the playground, let's add it to the `onSage` function. Remember to update the `div` ID from `#your-own-div` to `#embed` to match the `index.html` file. Finally, add a call to `render()`. - -Here is the resulting function with comments removed and the DIV ID updated: - -[source,javascript] ----- -const onSage = () => { - const embed = new SageEmbed("#embed", { - frameParams: {}, - disableWorksheetChange: true, - hideSageAnswerHeader: true, - dataSource: "4d98d3f5-5c6a-44eb-82fb-d529ca20e31f", // Your data source ID - searchOptions: { - searchQuery: "top selling items", - executeSearch: true, - }, - }); - - embed.render(); -}; ----- - -== Test natural language search embed - -The final step is to test the Sage embed. Refresh the application (with cache disabled), then click the Sage link. You should see something like this: - -[.widthAuto] -[.bordered] -image:images/tutorials/tse-fundamentals/lesson-06-sage-embed-results.png[final sage embed in the application] - -== Activities - -1. Add the nav link and handler to your code. -2. Import `SageEmbed`. -3. Use the playground to create a natural language search embed component. -4. Copy the search embed component from the playground to your code and modify the DIV ID. -5. Add a `render()` call. -6. Test the code. - -If you run into issues, you can reference the code in the `src` folder. - -== Files changed - -* index.html -* tse.js +[IMPORTANT] +==== +ThoughtSpot has deprecated embedding Natural Language Search with `SageEmbed`. To embed AI Search and conversational analytics, ThoughtSpot strongly recommends using Spotter. For more information, see the xref:embed-spotter.adoc[Spotter embed] and xref:customize-spotter-embed.adoc[customization] documentation. +==== ++++
    diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc index 42cf6ea95..8ef70894c 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-07.adoc @@ -2,7 +2,7 @@ :toc!: :page-title: Embed a Liveboard -:page-pageid: tse-fundamentals__lesson-07 +:page-pageid: tse-fundamentals__lesson-07 :page-description: In this lesson we'll embed a full Liveboard using the `LiveboardEmbed` component. == Pre-conditions @@ -19,9 +19,7 @@ First, we want to add another nav link to the nav bar. In the `index.html` file
    ---- @@ -34,7 +32,7 @@ image::images/tutorials/tse-fundamentals/lesson-07-new-liveboard-link.png[Nav ba == Add a listener for the Liveboard links -In `tse.js` add the following lines of code. It adds a listener for the click events, so when the user clicks, it will call the `onLiveboard` function. Add the following line after the one we added for the `sage-link`. +In `tse.js` add the following lines of code. It adds a listener for the click events, so when the user clicks, it will call the `onLiveboard` function. Add the following line after the one we added for the `search-link`. [source,javascript] ---- @@ -99,7 +97,7 @@ image:images/tutorials/tse-fundamentals/lesson-07-liveboard-selected.png[Liveboa == Embed the Liveboard into the application -As with Search and Natural Language Search embedding, we'll copy the code from the playground into the application. +As with Search embedding, we'll copy the code from the playground into the application. . Copy the component creation section. Your code will show as follows. . Paste this code into the `onLiveboard` function. @@ -148,7 +146,7 @@ image:images/tutorials/tse-fundamentals/lesson-07-liveboard-embed-results.png[Li 4. Copy and paste the generated code (adding `render()`) into your application 5. Test the code -If you run into problems, you can look at the code in the `src` folder in this section. +If you run into problems, you can look at the code in the `src-updates/07-src` folder in the link:https://github.com/thoughtspot/tse-fundamentals-step-by-step[tse-fundamentals-step-by-step repository, window=_blank]. == Files changed diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc index 64d207308..102131c6f 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-08.adoc @@ -1,7 +1,7 @@ = Embed a Liveboard visualization :toc!: -:page-title: Embed a Liveboard Visualization +:page-title: Embed a Liveboard Visualization :page-pageid: tse-fundamentals__lesson-08 :page-description: In this lesson we'll embed a single visualization from a Liveboard using the `LiveboardEmbed` component. @@ -20,8 +20,6 @@ In the `index.html` file add a new `
  • ` for the separator and Liveboard visual