diff --git a/modules/ROOT/pages/abac-user-parameters.adoc b/modules/ROOT/pages/abac-user-parameters.adoc index 059271ba6..572196c58 100644 --- a/modules/ROOT/pages/abac-user-parameters.adoc +++ b/modules/ROOT/pages/abac-user-parameters.adoc @@ -1,76 +1,63 @@ -= ABAC via tokens += ABAC via tokens (Legacy method) :toc: true -:toclevels: 3 +:toclevels: 2 :page-title: ABAC via tokens :page-pageid: abac-user-parameters :page-description: Attribute-based access control pattern can be achieved via user parameters sent in the login token -In Attribute-Based Access Control (ABAC) implementation, security entitlements are sent in as lists of attributes at session creation time via the authentication service. - -This article provides a detailed overview of the ABAC implementation via tokens for row-level security (RLS), and lists configuration recommendations, and best practices. +ThoughtSpot's Attribute-Based Access Control (ABAC) implementation allows administrators to send user-specific security entitlements as attributes at session creation via JSON Web Token (JWT) tokens. [IMPORTANT] ==== -The ABAC feature is disabled by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +The ABAC feature is disabled by default on ThoughtSpot instances. To implement ABAC with data security in ThoughtSpot, refer to the instructions in the xref:abac_rls-variables.adoc[ABAC via RLS with template variables] documentation. ==== +== Overview -// * The `user_parameters` property in `auth/token/full` and `auth/token/object` APIs used for the beta implementation of ABAC is deprecated in 10.4.0.cl. -// * Starting with 10.4.0.cl, security attributes for ABAC will not be stored in the `user` > `user_parameters` object. All ABAC-related security rules and filters applied via token generated using the `/api/rest/2.0/auth/token/custom` API endpoint are stored in the `user` > `access_control_properties` object. -// * The +++Custom access token +++ REST API endpoint. - - -== Configuration recommendations and best practices - -Before you begin, note the following recommendations and feature limitations: +To generate JWT tokens for ABAC implementation, you must use the `/api/rest/2.0/auth/token/custom` REST API endpoint. -Indexing:: -Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in Explore mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. - + -You must turn off indexing for any field that needs to be restricted by RLS when using ABAC via tokens for RLS, or also include an RLS Rule on fields that must also be filtered for the Indexing system. - -//// -+ [NOTE] ==== -ABAC rules are not supported on Liveboards with AI Highlights and Change Analysis features, and on the Answers generated from Spotter. +* To pass different data contexts, based on the data slices that your users are allowed to visualize, use runtime filters and Parameters. These features are designed to keep your embedded ThoughtSpot content in sync with the context of host application. +* Runtime filters and runtime parameters are not security features. For data security, use xref:rls-rules.adoc[RLS rules]. ==== -//// -Mandatory token filters:: -When setting filter rules within the token, you must place the `is_mandatory_token_filter: true` property on every column in a Worksheet or Model where a filter rule is expected. This will deny any access to data if a user has not been assigned values for the expected set of fields. +To create an easier implementation of data security for your application users, ThoughtSpot recommends using RLS rules with system variables such as `ts_username` or `ts_groups`, or by using xref:abac_rls-variables.adoc[custom variable references] whose values can be assigned to users as login tokens. -+ -[NOTE] -==== -On instances running 10.5.0.cl and 10.4.0.cl versions, if a column is set as hidden (`is_hidden: true`), the `is_mandatory_token_filter: true` setting will not be applied to the column. Due to this, the user may see no data. To work around this issue, we recommend upgrading your instance to 10.6.0.cl. On versions lower than 10.6.0.cl, ensure that you set the `is_hidden` parameter to `false` on the column before applying filter rules. -==== +=== ABAC attributes -[#column-name-warning] -Column names in Worksheet/ Model:: -The filter rules require passing the *exact* ThoughtSpot Worksheet or Model column name, or the values will not bind to any column. You must coordinate between the team that maintains the Worksheets or Models and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] to know if any changes will be made to a Model or Worksheet. + -For the same reasons, the end users of an embedded app cannot have *edit* access to any Worksheet or Model using ABAC RLS via tokens. + -Setting the `is_mandatory_token_filter: true` property on every column where a filter rule is expected ensures that no data gets returned for users when column names change. +Administrators can set the following attributes for a user via the authentication token, along with the capability to assign the user to ThoughtSpot groups: -API for token generation:: -The ABAC via tokens feature in ThoughtSpot 10.4.0.cl and later versions involves generating a token with filter rules and parameter values using the +++auth/token/custom+++ API endpoint. Customers using the xref:abac-user-parameters-beta.adoc[beta version of ABAC with the V2.0 Get token APIs] (`auth/token/full` or `auth/token/object`) to `/api/rest/2.0/auth/token/custom`, refer to the instructions in the xref:jwt-migration.adoc[migration guide]. +* Filter rules + +This method uses xref:runtime-filters.adoc[runtime filters] (`filter_rules`) in the token to create data security rules. It can filter multiple values of any data type and binds to any Column in any Model with a matching column name in ThoughtSpot. +* Parameter values + +This method uses xref:runtime-parameters.adoc[runtime Parameters] (`parameter_values`) in the token to create data security rules. It binds a single value to any Parameter in any Model by Parameter Name and Type match. Parameters can be used in *Formulas* and then as *Filters* in Models. -== ABAC attributes +=== Mandatory token filters -Administrators can set the following attributes for a user via the authentication token, along with the capability to assign the user to ThoughtSpot groups: +The `is_mandatory_token_filter: true` setting in object TML enforces that a filter rule must be provided for a specific column. When this attribute is set on a column in a Model, ThoughtSpot will deny all data access for users who do not have a corresponding filter rule for that column in their ABAC token. -* xref:runtime-filters.adoc[Filter rules] + -Can filter multiple values of any data type. Binds to any Column in any Model or Worksheet with a matching column name in ThoughtSpot (and not the underlying database table column name). +When setting filter rules within the token, you must place the `is_mandatory_token_filter: true` property on every column in a Model where a filter rule is expected. This setting will deny any access to data if a user has not been assigned values for the expected set of fields. -* xref:runtime-parameters.adoc[Parameter values] + -Binds a single value to any Parameter in any Worksheet or Model by Parameter Name and Type match. Parameters can be used in *Worksheet formulas* and then as *Worksheet filters*. +[#column-name-warning] +The filter rules require passing the *exact* column name as defined in the Model. Otherwise, the values will not bind to any column. You must coordinate between the team that maintains the data objects and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] to know if any changes will be made to a Model and to ensure column names remain consistent. + +For this reason, end users of an embedded app must not be granted edit access to any Model using ABAC rules via tokens. Setting the `is_mandatory_token_filter: true` property on every column where a filter rule is expected ensures that no data is returned for users when column names change. + +[NOTE] +==== +If a column is set with both `is_hidden: true` and `is_mandatory_token_filter: true`, and filter conditions for that column are defined in the ABAC token, the filter will be applied as expected. The column will be hidden from the user interface, but the mandatory filter requirement will still be enforced, and data will be shown according to the filter values provided in the token. +==== + +=== Indexing +Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in *Explore* mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. This means the indexed columns may expose values in search suggestions or autocompletion that a user should not see, even if ABAC filters would block access to the underlying data. To prevent this, you can do one of the following: -The request for a token with ABAC details can xref:abac-user-parameters.adoc#persistForUser[persist] the set of filters and Parameter values to user sessions within ThoughtSpot, after which all sessions and scheduled reports will use the persisted values until they are changed by another token generation request. +- Disable indexing for columns and fields that must be restricted by ABAC. You may also want to disable indexing on all sensitive columns. +- Define an RLS rule on those fields, since RLS is enforced at the indexing layer and will secure suggestions and sample values. == Token request -The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format. This token can be used as a bearer token for Cookieless trusted authentication or REST API access. You can also use it as a sign-in token to create a session, in which case, we recommend that the ABAC user properties be *persisted*, to ensure scheduled exports remain secure after the session ends. +The ABAC message to ThoughtSpot is encoded in JSON Web Token (JWT) format. This token can be used as a bearer token for Cookieless trusted authentication or REST API access. You can also use it as a sign-in token to create a session, in which case, we recommend that the ABAC user properties be *persisted*, to ensure scheduled exports remain secure after the session ends. [NOTE] ==== @@ -455,24 +442,6 @@ An example workflow might be: 4. Worksheets that need these entitlements use the combination of pass-through function with parameter + formula + filter so that all queries in ThoughtSpot include a WHERE clause with the sub-select. == Known limitations -The ABAC via tokens method requires using trusted authentication and using Worksheets or Models as data sources for Liveboards and Answers, rather than individual Table objects. - -For indexing recommendations, see xref:abac-user-parameters.adoc#_configuration_recommendations_and_best_practices[Configuration recommendations and best practices]. - -//// -* Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in *Explore* mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. -+ -You must turn off indexing for any field that needs to be restricted by RLS when using ABAC via tokens for RLS, or also include an RLS Rule on fields that must also be filtered for the Indexing system. - - -// * Schedules created with JWT using ABAC will not follow the same security rules as schedules created with standard RLS set up in ThoughtSpot. + -// Schedules created by users in a session secured via RLS using ABAC currently do not follow any data security rules, that is, all data will be shown in schedules. ThoughtSpot recommends removing the ability to create schedules for your end users. The improvements in the upcoming versions include: -// .. The security rules applied to the schedule will be those of the schedule creator -// .. Using `persist:true` in the JWT for security rules will ensure that the schedule is run using the filter rules persisted on the user. -//* Runtime filter conditions must match the column names in your worksheet to avoid data leakage. - -//+ -//The `runtime_filters` must include the exact ThoughtSpot worksheet column name, or they will not apply to the data set. If a worksheet is changed, you must coordinate between the team that maintains it and the team that builds the token request service, or the filters will no longer be applied. For the same reasons, the end users of an embedded app cannot have edit access to any worksheet using ABAC RLS via tokens. + -// + +The ABAC via tokens method requires using xref:trusted-authentication.adoc[trusted authentication], and using Worksheets or Models as data sources for Liveboards and Answers, rather than individual Table objects. -// You can pass in runtime filters and Parameters for a user via their login token. Both features work like the runtime filters and Parameters available within the Visual Embed SDK, but values set via token cannot be overridden by any user action within the ThoughtSpot UI. +For indexing recommendations, see xref:abac-user-parameters.adoc#_indexing[Indexing]. diff --git a/modules/ROOT/pages/abac_rls-variables.adoc b/modules/ROOT/pages/abac_rls-variables.adoc new file mode 100644 index 000000000..838b31e49 --- /dev/null +++ b/modules/ROOT/pages/abac_rls-variables.adoc @@ -0,0 +1,409 @@ += ABAC via RLS with variables +:toc: true +:toclevels: 2 + +:page-title: ABAC via tokens +:page-pageid: abac-via-rls-variables +:page-description: Attribute-based access control pattern with variable attributes referenced in Row-Level Security (RLS) rules on a given table. + +Attribute-Based Access Control (ABAC) is an access control model in which security entitlements are determined by evaluating a set of attributes included in a token generated for a user. The attributes are passed in a JSON Web Token (JWT) at session creation to dynamically filter data and enable user-specific security policies. + +== Overview + +To implement data security for application users, administrators can define RLS rules that use system variables such as `ts_username` or `ts_groups`. If a ThoughtSpot deployment requires granular access control and dynamic assignments beyond what system variables can support, administrators can use formula variables within RLS rules. + +Formula variables are custom variables that enable dynamic and context-aware logic in RLS rules. They can be assigned at the Org, user, and data model levels. + +In embedded analytics scenarios, where each user may require different data access, administrators can assign security attributes and rules on a per-user basis. For these use cases, administrators can implement a JWT-based ABAC model combined with RLS to enforce data security using dynamic attributes derived from formula variables. + +In the ABAC via RLS with variables method, administrators add formula variables to RLS rules and pass their values (`variable_values`) as security attributes and entitlements to the user session through a JWT. All derived objects then inherit the data security rules from the underlying Table and are filtered according to the user’s entitlements provided in the token. + +[NOTE] +==== +* Formula variables are available on ThoughtSpot starting from 10.15.0.cl. If this feature is not enabled on your instance, contact ThoughtSpot Support. + +* ABAC via RLS does not support session-based ABAC (`persist_option: NONE`). If you are using `persist_option: NONE`, create dedicated user accounts for your application users and apply persisted rules. This approach ensures that Liveboard schedule attachments enforce security rules and deliver only secured output to your end users. + +When combined with cookieless authentication, this configuration addresses all use cases that previously relied on session-based JWT. You can simplify user provisioning and programmatically manage user creation and deletion workflows using ThoughtSpot's REST APIs. +==== + +=== Indexing +Several features within ThoughtSpot, such as autocompletion in Search on values within columns, use ThoughtSpot indexing. Due to the runtime nature of ABAC tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. This means the indexed columns may expose values in search suggestions or autocompletion that a user should not see, even if ABAC filters would block access to the underlying data. To prevent this, you can do one of the following: + +* Disable indexing for columns and fields that must be restricted by ABAC. You may also want to disable indexing on all sensitive columns. +* Define an RLS rule on those fields, since RLS is enforced at the indexing layer and will secure suggestions and sample values. + +=== Implementation steps +The ABAC implementation with formula variables and RLS rules includes the following steps: + +* xref:abac_rls-variables.adoc#_create_formula_variables[Creating formula variables] + +To generate tokens with variable attributes, the variables must be available in ThoughtSpot. To create variables, use the xref:variables.adoc#_create_a_variable[Variable REST API]. +* xref:abac_rls-variables.adoc#_add_rls_rules_with_variable_references[Adding RLS rules with formula variables] + +When defining an RLS rule with variables, use the `ts_var` function. These RLS rules will apply to the Models, Liveboards, and other objects derived from that Table. +* xref:abac_rls-variables.adoc#_define_values_and_scope_for_variables[Creating a token request with variable attributes] + +To generate a JWT token, use the `/api/rest/2.0/auth/token/custom` REST API endpoint. The token generation request must include the variable attributes, which will be used for RLS evaluation to enable per‑user entitlements and data filters across all the objects derived from the Table. +* xref:abac_rls-variables.adoc#_verify_the_entitlements[Verifying entitlements] + +To ensure data security rules are applied, check user entitlements and verify if they are translated accurately during query generation. + +The ABAC via tokens method requires the xref:trusted-authentication.adoc[trusted authentication] setup. + +//// +=== Mandatory token filters + +The `is_mandatory_token_filter: true` setting in object TML enforces that a filter rule must be provided for a specific column. When this attribute is set on a column in a Model, ThoughtSpot will deny all data access for users who do not have a corresponding filter rule for that column in their ABAC token. + +When setting filter rules within the token, you must place the `is_mandatory_token_filter: true` property on every column in a Model where a filter rule is expected. This setting will deny any access to data if a user has not been assigned values for the expected set of fields. + +[#column-name-warning] +The filter rules require passing the *exact* column name as defined in the Model. Otherwise, the values will not bind to any column. You must coordinate between the team that maintains the data objects and the team that builds the xref:trusted-auth-token-request-service.adoc[token request service] to know if any changes will be made to a Model and to ensure column names remain consistent. + +For this reason, end users of an embedded app must not be granted edit access to any Model using ABAC rules via tokens. Setting the `is_mandatory_token_filter: true` property on every column where a filter rule is expected ensures that no data is returned for users when column names change. + +[NOTE] +==== +If a column is set with both `is_hidden: true` and `is_mandatory_token_filter: true`, and filter conditions for that column are defined in the ABAC token, the filter will be applied as expected. The column will be hidden from the user interface, but the mandatory filter requirement will still be enforced, and data will be shown according to the filter values provided in the token. +==== +//// + +== Create formula variables + +To view the variables available on your instance, use the `POST /api/rest/2.0/template/variables/search` API call. To create a new variable, use the `/api/rest/2.0/template/variables/create` API endpoint. + +To configure formula variables for all Orgs on your instance or the Primary Org, cluster administration privileges are required. Org administrators can configure formula variables for their respective Orgs. Users with the `CAN_MANAGE_VARIABLES` (*Can manage variables*) role privilege can also create and manage variables for their Org context. + +The `/api/rest/2.0/template/variables/create` API endpoint allows creating formula variables for the following data types: + +* `VARCHAR` +* `INT32` +* `INT64` +* `DOUBLE` +* `DATE` +* `DATE_TIME` + +During variable creation, specify the xref:variables.adoc#data_type[`data_type`]. + +Formula variables for `BOOLEAN` and `TIME` data types are not supported. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/]api/rest/2.0/template/variables/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "type": "FORMULA_VARIABLE", + "name": "country_var", + "is_sensitive": false, + "data_type": "VARCHAR" +}' +---- + +The variable update API allows assigning variable values and setting the scope. In the ABAC implementation, administrators can set the variable values and scope when xref:abac_rls-variables.adoc#_create_an_abac_token_request_with_variable_attributes[generating a JWT] using the `/api/rest/2.0/auth/token/custom` API endpoint. + +== Add RLS rules with variable references +To define RLS rules with variables for a Table: + +. Navigate to the Data workspace and click the Table for which to define RLS rules. +. Click *Row security* and then click *+ Add row security*. +. In the *Row Security Editor*, define the rules. To reference the formula variable in the rule, use the `ts_var` function. For example, If you want to limit user access to data of a specific region, you can create a region-specific variable, `region = ts_var('region_var')`, and assign values in the token request. + + +=== RLS rule with a single variable reference + +In this formula example, `country` refers to the "country" column in the data table, and `country_var` is the variable. + +---- +country = ts_var('country_var') +---- + +If `country_var` is assigned a single value, the user is permitted to view only rows where the `country` column matches that value. + +If `country_var` is assigned multiple values, the formula translates to `country IN ('value1', 'value2', ...)`. The query engine interprets `=` as the `IN` clause in this case and returns rows that match these values; for example, `WHERE country IN ('Australia', 'Germany')`. + +=== RLS rules with multiple variables +The RLS rules support the `AND` operator, which means that you can combine multiple conditions in a single RLS rule, so that a row is accessible only if all the specified conditions are met. + +The following rule restricts data access to rows if the `country` column in the data table matches the value assigned to `country_var` and the `Department` column matches the value assigned to `department_var` for that user. + +---- +country = ts_var('country_var') AND Department = ts_var('department_var') +---- + +The rule in this example restricts data access to rows where the `region` column in the table matches the value assigned to `region_var` and the `product` column matches the value assigned to `product_var`. + +---- +region = ts_var('region_var') AND product = ts_var('product_var') +---- + +=== Allow all rule with a TS_WILDCARD_ALL variable +In this example, `customer` represents the column `customer` in the table and `customer_var` represents variable. If the value of the customer_var variable is set to `TS_WILDCARD_ALL`, the user can access all customers in the column. + +---- +customer = ts_var('customer_var') +---- + +=== Group override rule with variable-based check +In any security formula you build, you may want a clause that gives access to all data to certain groups. In the rule definition, you can include system variables, such as `ts_groups`, to build your preferred logic: + +In this example, users can access data if they are in the "data developers" group, or if the `Department` column matches the value assigned to their `department_var` variable. + +---- +'data developers' in ts_groups OR Department = ts_var('department_var') +---- + +==== Variables with numeric and Date data types + +The following rule enforces a numeric threshold and restricts access to rows where the Revenue value is less than or equal to the value provided by the `revenue_cap_var` variable. + +---- +Revenue <= to_double(ts_var('revenue_cap_var')) +---- + +The following rule restricts access to rows where the `date_column` is within the range defined by the `start_date_var` and `end_date_var` variables. Only rows with dates greater than or equal to the start date and less than or equal to the end date specified for these variables will be visible for the user. + +---- +(date_column >= ts_var('start_date_var')) AND (date_column <= ts_var('end_date_var')) +---- + +== Create an ABAC token request with variable attributes + +To generate a token with variable attributes, use the `POST /api/rest/2.0/auth/token/custom` API call. + +The variable attributes defined in the token request take effect only if they are referenced in an RLS rule. If the variables are not used in any formula or RLS rule, they will have no impact on data access. Before generating the request with variable attributes, ensure that the xref:abac_rls-variables.adoc#_add_rls_rules_with_formula_variables_to_tables[variables are added to the RLS rules] for the Table. + +In the token request, include the following properties along with the `username`, xref:trusted-auth-secret-key.adoc[`secret_key`]: + +* `variable_values` +* `persist_option` + +Optionally, you can specify the `objects` and `org_identifier` to set the scope of access control. + +=== Variable values + +The `variable_values` array requires the following parameters: + +* `name` + +__String__. Name of the formula variable. The formula variable referenced on the token request must be available in ThoughtSpot and included in the RLS rule. +* `values` + +__Array of strings or numeric values__. When assigning values, ensure the data format of values matches the data type set of that variable. If you are adding a variable to filter by country with the `VARCHAR` data type, specify the string values as shown in this example: + +[source,JSON] +---- +"variable_values": [ + { + "name": "country_var", + "values": [ + "Japan", + "Singapore", + "Australia" + ] + } + ] +---- + +All values are passed into the token as *arrays of strings*, even if the column is a numeric or date type in ThoughtSpot and the database. The column data type will be respected in the query issued to the database. + +==== Allow all values by default + +To allow all values by default, specify `["TS_WILDCARD_ALL"]` as the variable value to grant access to all values in a given column. + +In this example, the user is allowed all access for one variable, while for the others, specific values are set. + +[source,JSON] +---- +"variable_values": [ + { + "name": "country_var", + "values": [ + "Japan", + "Singapore", + "Australia" + ] + }, + { + "name": "department_var", + "values": [ + "Sales", + "Marketing" + ] + }, + { + "name": "product_var", + "values": [ + "TS_WILDCARD_ALL" + ] + } + ] +---- + +If `TS_WILDCARD_ALL` is set for variable attributes, ensure that the RLS rules are defined clearly on the Table to avoid unintended data exposure. + +==== Deny all by default +For every variable included in the token request, you can assign one or more values. All variables referenced in RLS rules are required. If a variable is not assigned any value, query generation will fail with the following error. + +`Error in loading data +No values are assigned to some or all Formula Variables` + +[.bordered] +[.widthAuto] +image:./images/formula-variable-error.png[Formula variable error, scale=25%] + +Due to this error, no data is returned, effectively denying all data access for the user. + +=== Persist options and session-based rules + +Variable attributes must be *persisted* for them to apply to user sessions when using xref:trusted-authentication.adoc#cookie[cookie-based trusted authentication] or scheduled reports. To specify whether variable attributes and rules should persist for user sessions, you must define the `persist_option` parameter. + +To append or replace the attributes, use the following options: + +* `APPEND` + +Adds the attributes defined in the API request to the user properties. These properties will be applied to the current and future user sessions and scheduled reports until they are explicitly changed through a token update request. + +* `REPLACE` + +Replaces existing variable assignments with the new values. + +[NOTE] +==== +* The ABAC implementation with RLS and formula variables does not support session-based rules. Therefore, ThoughtSpot does not recommend setting the `persist_option` attribute to `NONE`. +* If you don't want to append or replace any attributes, do not pass any variable values in the token update request. +* Passing an empty array does not reset the attributes. +* Resetting attributes via `"persist_option": "RESET"` is not supported. +==== + +=== Variable scope +To restrict the scope of the variable attributes and rules to a specific Org context and object, define the `org_identifier` and `objects`. + +==== Apply to specific objects +To apply variable entitlements to a specific object, specify the object IDs in the `objects` array as shown in this example: + +[source,JSON] +---- +"objects": [ + { + // example of the format + "type": "{OBJECT_TYPE}", + "identifier": "{id or name of the object}" + }, + { + "type": "LOGICAL_TABLE", + "identifier": "9b751df2-d344-4850-9756-18535797378c" + } +] +---- + +The API supports only the `LOGICAL_TABLE` object type. + +If the object ID is not specified in the API request, the variable values will be applied to all formulas and rules that use those variables, across all objects in the Org for that user. + +==== Apply to Org context + +The `org_identifier` attribute in the token request specifies the Org context for the user session and entitlements. + +If the `org_identifier` parameter is not defined in the token request, the token is issued for the user's last logged-in Org. For new users, the token will be assigned to the default Org on their instance. + +To apply variable entitlements to a user session, you must ensure that the RLS rules with variables and relevant objects are available in the Org context specified in the token request. + +=== Example request body + +The following example shows the request body for generating a token with formula variable attributes: + +[source,cURL] +---- + curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/auth/token/custom' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "username": "UserA", + "validity_time_in_sec": 300, + "persist_option": "APPEND", + "auto_create": true, + "secret_key": "f8aa445b-5ff1-4a35-a58f-e324133320d5", + "variable_values": [ + { + "name": "country_var", + "values": [ + "Japan", + "Singapore", + "Australia" + ] + }, + { + "name": "department_var", + "values": [ + "Sales", + "Marketing" + ] + }, + { + "name": "product_var", + "values": [ + "TS_WILDCARD_ALL" + ] + } + ], + "objects": [ + { + "type": "LOGICAL_TABLE", + "identifier": "35aa85fe-fbb4-4862-a335-f69679ebb6e0" + } + ] +}' +---- + +If the request is successful, ThoughtSpot generates a token and sends the token details in the API response. + +[NOTE] +==== +ABAC details are sent in a JWT that can be used as a bearer token for cookieless trusted authentication, REST API calls, or as a sign-in token to start a session. JWTs are compressed by default to handle large payloads. It is recommended to keep the compression enabled to ensure all JWT tokens can get properly interpreted by the application regardless of their size, and to obfuscate the values passed in the JWT payload. If you want to disable it, contact ThoughtSpot Support. +==== + +=== Verify the variable assignment + +To verify the variable assignment, use the `POST /api/rest/2.0/users/search` API call and check `variable_values` in the user properties in the API response. + +[source,JSON] +---- +//... +{ + "variable_values": { + "821119045": { + "ALL": { + "variable_values": [ + { + "name": "country_var", + "values": [ + "Japan", + "Singapore", + "Australia" + ] + }, + { + "name": "department_var", + "values": [ + "Sales", + "Marketing" + ] + } + ] + } + } + } +} +---- + +To verify the security entitlements, start a user session using the JWT and inspect the generated SQL for your query or visualization. + +== Verify the entitlements +To verify the entitlements: + +. Log in to your app with a user account that does not have the *Can administer and bypass RLS* privilege, and initiate the user session with the ABAC token. +. Access a Liveboard, Saved Answer, or start a new search query. +. Inspect the generated SQL for your query or visualization. +. Verify the rules and check whether only the permitted rows are displayed. +. Verify whether data is displayed when no variable values are defined. +. Repeat the steps for different variable assignments to confirm the RLS rule is enforced as expected for all scenarios. + +== Additional resources + +* For information about variables and variable APIs, see link:https://docs.thoughtspot.com/cloud/latest/rls-variables-reference[Variables] and xref:variables.adoc[Variable APIs]. +* For information about RLS rules,see xref:rls-rules.adoc[RLS Rules] and link:https://docs.thoughtspot.com/cloud/latest/security-rls[ThoughtSpot Product Documentation, window=_blank]. diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 7eb58168c..510e867e7 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,7 +8,34 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. -== November 2025 +== Version 1.44.x, January 2026 + +[width="100%" cols="1,4"] +|==== + +|[tag redBackground]#DEPRECATED# |**`defaultHeight` replaced with `minimumHeight` ** + + +The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. +To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. + +|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: + +//* `enableApiIntercept` + +//When set to true, enables the feature on your ThoughtSpot embed. +* `interceptUrls` + +Allows configuring which API calls to intercept. +* `interceptTimeout` + +Sets the timeout duration for handling interception. +* `isOnBeforeGetVizDataInterceptEnabled` + +When set to true, it enables the use of `EmbedEvent.OnBeforeGetVizDataIntercept` event to emit and intercept search execution calls initiated by the users and implement custom logic or workflow to allow or restrict search execution. +* `EmbedEvent.ApiIntercept` + +Emits when an API call matching the conditions defined in `interceptUrls` is detected. + +For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +|==== + +== Version 1.43.0, November 2025 [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# a| *Code-based custom actions* @@ -33,7 +60,7 @@ The Visual Embed SDK now supports runtime overrides in Spotter embed. * To apply runtime filters, use the `runtimeFilters` object * To apply runtime Parameters, use the `runtimeParameters` object. -|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* +|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. The SDK also provides the following action IDs: @@ -184,7 +211,6 @@ To use these attributes effectively in embedded applications, your ThoughtSpot i |==== - == Version 1.39.0, July 2025 [width="100%" cols="1,4"] @@ -203,7 +229,7 @@ Replaced with `SpotterAgentEmbedViewConfig` The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. |[tag greenBackground]#NEW FEATURE# a| *Action ID of Spotter coaching* + -For ThoughtSpot instances that have the new Spotter feedback and coaching workflow enabled, SDK provides the action ID `Action.InCoversationTraining` to manage the visibility of the *Add to coaching* button on Answer generated from Spotter prompts. +For ThoughtSpot instances that have the new Spotter feedback and coaching workflow enabled, SDK provides the action ID `Action.InConversationTraining` to manage the visibility of the *Add to coaching* button on Answer generated from Spotter prompts. [NOTE] The **Add to Coaching** feature is currently in beta and is turned off by default on embed deployments. To enable this feature on your instance, contact ThoughtSpot Support. diff --git a/modules/ROOT/pages/api-intercept.adoc b/modules/ROOT/pages/api-intercept.adoc new file mode 100644 index 000000000..a3ba7e5e5 --- /dev/null +++ b/modules/ROOT/pages/api-intercept.adoc @@ -0,0 +1,268 @@ += Intercept API and data fetch requests +:toc: true +:toclevels: 2 + +:page-title: Intercept API calls from embedded components +:page-pageid: api-search-intercept +:page-description: Developers can intercept and control API calls originating from the embedded ThoughtSpot components + +Developers can intercept data fetch and other API requests initiated by the embedded ThoughtSpot application using the following features: + +* Intercept data fetch requests: + +To enable interception of search execution requests by search embed or full application embed, use the `isOnBeforeGetVizDataInterceptEnabled` attribute. When enabled, you can implement custom logic using the `OnBeforeGetVizDataIntercept` embed event, allow or block search requests, and show custom messages to users. + +* Intercept a specific API call or all requests: + +If you want to intercept other API calls initiated by the embedded application, define the URLs that you want to intercept in the `interceptUrls` attribute and handle interception using the `ApiIntercept` embed event. + +Developers can use these interception features for: + +* Custom data handling +* Securing sensitive data before sending a response +* Debugging API failures or delays +* Integrating with external systems or applying business logic before data is rendered + +== Intercepting data fetch requests + +To enable interception of data fetch requests, set the `isOnBeforeGetVizDataInterceptEnabled` attribute to `true` in the SDK. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed', { + //...viewConfig, + isOnBeforeGetVizDataInterceptEnabled: true, + //... +}); +---- + +When enabled, you can intercept and control search execution and data fetch requests, and implement a custom logic to trigger a response when the `EmbedEvent.OnBeforeGetVizDataIntercept` event is emitted. + +The following example blocks the search request and returns a custom error message. + +[source,JavaScript] +---- +embed.on(EmbedEvent.OnBeforeGetVizDataIntercept, +(payload, responder) => { + responder({ + data: { + execute: false, // Block the search from executing + error: { + // Custom error message shown to the user when the search is blocked + errorText: "This search query cannot be run. Please contact your administrator for more details." + } + } + }) +}) +---- + +The following example blocks the search only if the query contains both `sales` and `county`; otherwise, it allows the search to proceed. It also provides an error message explaining why the search was blocked: + +[source,JavaScript] +---- +embed.on(EmbedEvent.OnBeforeGetVizDataIntercept, +(payload, responder) => { + const query = payload.data.data.answer.search_query + responder({ + data: { + // Allow the search only if the query does NOT include both 'sales' AND 'county' + execute: !(query.includes("sales") && query.includes("county")), + error: { + // Custom error message and description shown if the search is blocked + errorText: "Error Occurred", + errorDescription: "You can't use this query :" + query + + ". The 'sales' measures can never be used at the 'county' level. Please try another measure, or remove 'county' from your search." + } + } + }) +}) +---- + +== Intercept specific URLs or all API calls + +The API intercept feature lets you intercept API calls made by the embedded application, modify or block requests, and provide custom responses before they are sent to the backend. + +//// +=== Enable API interception + +To enable this feature on your embed, you must set the `enableApiIntercept` flag to `true` in the SDK. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed', { + //...viewConfig, + enableApiIntercept: true, + //... +}); +---- +//// + +To intercept API requests from specific URLs, define the URLs in the `interceptUrls` array: + +Valid values for `interceptUrls` are: + +** `ALL` - Allows intercepting all API requests + +** `AnswerData` - Allows intercepting APIs that fetch data for a search query or visualization. + +** `LiveboardData` - Allows intercepting APIs requesting data for the embedded Liveboard. + +You can also set a specific URL that you want to intercept by specifying the array in the following format: + +`interceptUrls: [Type.AnswerData, '{URL-to-intercept}']` + +[NOTE] +==== +You must specify at least one API type or URL in the array for interception to be effective. If `interceptUrls` is set as an empty array, no URLs will be intercepted. +==== + +=== Intercept timeout threshold +To set a threshold for the interception handling, configure the `interceptTimeout` value in milliseconds. The default value is 30000. If the interception is not handled within the configured threshold, the API returns an error. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed', { + ...viewConfig, + interceptUrls: [InterceptedApiType.AnswerData], + interceptTimeout: 2000, +}); +---- + +=== Event handling with custom workflows + +To listen to the API intercept event and trigger custom workflows, use `EmbedEvent.ApiIntercept`. You can implement a custom workflow or logic to handle interception and respond when the event is emitted. The structure of the response determines whether the user sees an error or receives custom data instead of the original API result. + +The following code intercepts the API call and blocks its execution. It returns an error message when the `EmbedEvent.ApiIntercept` event is emitted. + +[source,JavaScript] +---- +LiveboardEmbed.on(EmbedEvent.ApiIntercept, (payload, responder) => { + console.log('payload', payload); // Log the intercepted API call payload for debugging. + responder({ + data: { + execute: false, // Block the API call from proceeding. + error: { + errorText: 'Error Occurred', // Provide an error message indicating the API call was blocked. + } + } + }) +}) +---- + +The following example returns a detailed error response structure when an intercepted call is blocked, and the `EmbedEvent.ApiIntercept` event is emitted. + +[source,JavaScript] +---- +embed.on(EmbedEvent.ApiIntercept, (payload, responder) => { + console.log('payload', payload); // Log the intercepted API call payload for debugging. + responder({ + data: { + execute: false, // Block the API call from proceeding. + response: { + body: { + errors: [{ + title: 'Error Occurred', // Error title shown to the user. + description: 'Error Description', // Detailed error description. + isUserError: true, // Indicates this is a user-facing error. + }], + data: {}, // Optionally include additional data in the response. + }, + } + } + }) +}) +---- + +The following example returns a custom response when an intercepted call is blocked and the `EmbedEvent.ApiIntercept` event is emitted. + +[source,JavaScript] +---- +embed.on(EmbedEvent.ApiIntercept, (payload, responder) => { + console.log('payload', payload); // Log the intercepted API call payload for debugging. + responder({ + data: { + execute: false, // Block the API call from proceeding. + response: { + body: { + data: { // You can provide a custom data object here to override the API response. + }, + } + } + } + }) +}) +---- + +== Use both methods for comprehensive interception +To provide comprehensive control over data access and workflow customization, use both data fetch and API request interception properties in the SDK. In such configurations, API interception settings allow developers to intercept and manage API calls made by the embedded component, while `isOnBeforeGetVizDataInterceptEnabled` allows intercepting data fetch requests for visualizations and search queries before they are executed. + +[source,JavaScript] +---- +const embed = new SearchEmbed('#embed', { + //...viewConfig, + isOnBeforeGetVizDataInterceptEnabled: true, + interceptUrls: [InterceptedApiType.AnswerData], + interceptTimeout: 2000, +}); +---- + +The following example shows how to handle events when using both methods of interception: + +[source,JavaScript] +---- +// Intercept visualization data fetch before execution +embed.on(EmbedEvent.OnBeforeGetVizDataIntercept, (payload, responder) => { + // Extract the search query from the payload + const searchQuery = payload.data.data.answer.search_query; + + // Block execution if the query contains a restricted column + if (searchQuery.includes('restricted_column')) { + responder({ + data: { + execute: false, + error: { + errorText: 'Query contains restricted columns', + errorDescription: 'Please modify your search to exclude restricted data.', + }, + }, + }); + } else { // Allow execution if no restricted columns are present + responder({ data: { execute: true } }); + } +}); + +// Intercept API calls +embed.on(EmbedEvent.ApiIntercept, (payload, responder) => { + // Intercept AnswerData API calls + if (payload.urlType === InterceptedApiType.AnswerData) { + const requestBody = payload.init.body; + + // Custom validation logic for the request body + if (validateRequest(requestBody)) { + responder({ data: { execute: true } }); + } else { + // Block execution and return a custom error response + responder({ + data: { + execute: false, + response: { + body: { + errors: [ + { + title: 'Validation Failed', + description: 'Request validation failed', + isUserError: true, + }, + ], + data: {}, + }, + }, + }, + }); + } + } else if (payload.urlType === InterceptedApiType.LiveboardData) { + // Allow LiveboardData API calls by default + responder({ data: { execute: true } }); + } +}); +---- + +== Related resources +See the xref:EmbedEvent.adoc#_apiintercept[Event reference documentation]. + diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 8278520d1..70a7bade7 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -739,18 +739,18 @@ If the API request is successful, ThoughtSpot returns a token with the security [source,JSON] ---- { - "id": "3eefc15a-cad0-4de0-a85c-de6407a14fca", + "id": "58185cfd-4c04-4570-8bab-63bc8dad2c98", "token": "{AUTH_TOKEN}", "org": { "id": 0, "name": "Primary" }, "user": { - "id": "46228fb2-8db9-4b84-b015-82ea2f3b220d", - "name": "UserA" + "id": "00000845-7688-795c-c4a1-857dc78d799d", + "name": "userA" }, - "creation_time_in_millis": 1733323274948, - "expiration_time_in_millis": 1733323574708 + "creation_time_in_millis": 1763654650210, + "expiration_time_in_millis": 1763654949981 } ---- diff --git a/modules/ROOT/pages/code-based-custom-actions.adoc b/modules/ROOT/pages/code-based-custom-actions.adoc index 7bcf90082..bdf0111c1 100644 --- a/modules/ROOT/pages/code-based-custom-actions.adoc +++ b/modules/ROOT/pages/code-based-custom-actions.adoc @@ -99,7 +99,7 @@ const customActions = [{ position: CustomActionPosition.PRIMARY, target: CustomActionTarget.LIVEBOARD, metadataIds: { - liveboardIds: ['lb1-GUID'], + liveboardIds: ['lb1-GUID'] }, }, ]; ---- @@ -114,10 +114,10 @@ const customActions = [{ position: CustomActionPosition.PRIMARY, target: CustomActionTarget.LIVEBOARD, metadataIds: { - liveboardId: ['lb1-GUID'], + liveboardId: ['lb1-GUID'] }, groupId: ['grp1-GUID'], - orgId: ['org1-GUID'], + orgId: ['org1-GUID'] }, ]; ---- @@ -229,10 +229,10 @@ In this example: const customActions = [{ name: 'CA1', id: 'ca1', - position: 'CustomActionPosition.PRIMARY, + position: CustomActionPosition.PRIMARY, target: CustomActionTarget.VIZ, metadataIds: { - liveboardIds: ['lb2-GUID'], + liveboardIds: ['lb2-GUID'] }, dataModelIds: { modelIds: ['model1-GUID'] @@ -258,14 +258,14 @@ In this example: const customActions = [{ name: 'CA1', id: 'ca1', - position: 'CustomActionPosition.PRIMARY, + position: CustomActionPosition.PRIMARY, target: CustomActionTarget.VIZ, metadataIds: { - liveboardIds: ['lb2-GUID'], + liveboardIds: ['lb2-GUID'] }, dataModelIds: { - modelIds: ['model1-GUID'] - modelColumnNames: ["model2-GUID::col1"] + modelIds: ['model1-GUID'], + modelColumnNames: ['model2-GUID::col1-column-name'] }, }, ]; ---- @@ -284,13 +284,13 @@ In this example: const customActions = [{ name: 'CA1', id: 'ca1', - position: 'CustomActionPosition.PRIMARY, + position: CustomActionPosition.PRIMARY, target: CustomActionTarget.VIZ, metadataIds: { - liveboardIds: ['lb2-GUID'], + liveboardIds: ['lb2-GUID'] }, dataModelIds: { - modelIds: ["model1-GUID"::"col2"], + modelColumnNames: ['model1-GUID::col2-column-name'] }, }, ]; @@ -321,7 +321,7 @@ const customActions = [{ position: CustomActionsPosition.PRIMARY, target: CustomActionTarget.ANSWER, metadataIds: { - answerIds: ['ans1-GUID'], + answerIds: ['ans1-GUID'] }, }, ]; @@ -343,10 +343,10 @@ const customActions = [{ position: CustomActionsPosition.PRIMARY, target: CustomActionTarget.ANSWER, metadataIds: { - answerIds: ['ans1-GUID'], + answerIds: ['ans1-GUID'] }, dataModelIds: { - modelIds: [model1-GUID], + modelIds: ['model1-GUID'] }, }, ]; ---- @@ -368,11 +368,11 @@ const customActions = [{ position: CustomActionsPosition.PRIMARY, target: CustomActionTarget.ANSWER, metadataIds: { - answerIds: ['ans1-GUID'], + answerIds: ['ans1-GUID'] }, dataModelIds: { modelIds: ['model1-GUID'], - modelColumnNames: ["model2-GUID::col1"], + modelColumnNames: ['model2-GUID::col1-column-name'] }, }, ]; ---- diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index b28908fb5..424fadb95 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -66,18 +66,21 @@ **** link:{{navprefix}}/embed-spotter[Embed Spotter] **** link:{{navprefix}}/embed-spotter-agent[Embed Spotter Agent] **** link:{{navprefix}}/embed-nls[Embed Natural Language Search (legacy interface)] -*** Embed full app experience -**** link:{{navprefix}}/full-embed[Embed full app] -**** link:{{navprefix}}/full-app-customize[Customize full application embedding] +*** link:{{navprefix}}/full-embed[Embed full application] +**** link:{{navprefix}}/full-app-customize[Customize your embed] +**** link:{{navprefix}}/customize-nav-controls[Customize navigation panels] +**** link:{{navprefix}}/set-default-page[Customize default page and navigation path] +**** link:{{navprefix}}/customize-homepage-experience[Customize home page experience] + *** Embed token-based Search **** link:{{navprefix}}/search-embed[Embed Search] **** link:{{navprefix}}/embed-searchbar[Embed search bar] *** link:{{navprefix}}/react-app-embed[Embed with React components] ** link:{{navprefix}}/mobile-embed[Embed ThoughtSpot in a mobile app] -*** link:{{navprefix}}/embed-ts-mobile-react-native[React Native SDK ^Beta^] -*** link:{{navprefix}}/embed-ts-flutter[Flutter embed SDK ^Beta^] -*** link:{{navprefix}}/embed-ts-swift[Swift Embed SDK ^Beta^] -*** link:{{navprefix}}/embed-ts-android[Android Embed SDK ^Beta^] +*** link:{{navprefix}}/embed-ts-mobile-react-native[React Native SDK] +*** link:{{navprefix}}/embed-ts-flutter[Flutter embed SDK] +*** link:{{navprefix}}/embed-ts-swift[Swift Embed SDK] +*** link:{{navprefix}}/embed-ts-android[Android Embed SDK] ** Customize and integrate *** link:{{navprefix}}/style-customization[Customize UX and styles] @@ -96,6 +99,7 @@ *** link:{{navprefix}}/action-config[Customize menus] **** link:{{navprefix}}/actions[Action IDs in the SDK] *** link:{{navprefix}}/events-app-integration[Events and app interactions] +**** link:{{navprefix}}/api-search-intercept[Intercept API and data fetch requests] *** link:{{navprefix}}/custom-action-intro[Custom actions] **** link:{{navprefix}}/customize-actions[Custom actions through the UI] ***** link:{{navprefix}}/custom-action-url[URL actions] @@ -125,10 +129,9 @@ *** link:{{navprefix}}/access-control-sharing[Access control and sharing] *** link:{{navprefix}}/privileges-and-roles[Privileges and Roles] *** link:{{navprefix}}/data-security[Data security] -**** link:{{navprefix}}/abac-user-parameters[ABAC via tokens] -**** link:{{navprefix}}/abac-migration-guide[Migrate ABAC ^BETA^ implementation to custom token API] -**** link:{{navprefix}}/abac-user-parameters-beta[ABAC via tokens (pre-10.4.0.cl)] **** link:{{navprefix}}/rls-rules[RLS Rules] +**** link:{{navprefix}}/abac-via-rls-variables[ABAC via RLS with variables] +**** link:{{navprefix}}/abac-user-parameters[ABAC via tokens (Legacy method)] *** link:{{navprefix}}/selective-user-access[User access] ** link:{{navprefix}}/best-practices[Performance optimization] *** link:{{navprefix}}/best-practices[Best practices] @@ -215,14 +218,14 @@ include::generated/typedoc/CustomSideNav.adoc[] * link:{{navprefix}}/development-and-deployment[Deployment and integration] ** link:{{navprefix}}/development-and-deployment[Development and deployment] *** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects overview] +*** link:{{navprefix}}/variables[Custom variables ^Beta^] *** link:{{navprefix}}/git-integration[Deploy with Git] **** link:{{navprefix}}/git-configuration[Configure Git integration] **** link:{{navprefix}}/git-api[Version Control REST APIs] **** link:{{navprefix}}/guid-mapping[GUID mapping] *** link:{{navprefix}}/deploy-with-tml-apis[Deploy with TML APIs] **** link:{{navprefix}}/modify-tml[TML modification] -*** link:{{navprefix}}/publish-data-overview[Publish content to Orgs ^Beta^] -**** link:{{navprefix}}/variables[Configure template variables ^Beta^] +*** link:{{navprefix}}/publish-data-overview[Publish content ^Beta^] **** link:{{navprefix}}/parameterze-metdata[Parameterize metadata ^Beta^] **** link:{{navprefix}}/publish-to-orgs[Publish objects to Orgs ^Beta^] @@ -255,4 +258,5 @@ include::generated/typedoc/CustomSideNav.adoc[] ** link:https://training.thoughtspot.com/page/developer[Training resources, window=_blank] ** link:https://docs.thoughtspot.com[Product Documentation, window=_blank] ** link:{{navprefix}}/rest-apiv2-beta-reference[REST API v2 ^Beta^ Reference (Deprecated)] +** link:{{navprefix}}/abac-user-parameters-beta[ABAC via tokens (pre-10.4.0.cl) (Deprecated)] diff --git a/modules/ROOT/pages/customize-homepage-full-embed.adoc b/modules/ROOT/pages/customize-homepage-full-embed.adoc new file mode 100644 index 000000000..3d4f40ac2 --- /dev/null +++ b/modules/ROOT/pages/customize-homepage-full-embed.adoc @@ -0,0 +1,370 @@ += Customize home page experience +:toc: true +:toclevels: 2 + +:page-title: Customize home page experience +:page-pageid: customize-homepage-experience +:page-description: Customize the home page experience by including or excluding specific modules and arrange them as needed in full application embedding + +Developers can customize the home page experience in full application embedding to show either the classic layout or the new modular home page. + +In the classic (V1) experience, the home page has a static layout and does not support SDK modular customization settings. + +In the V2 and V3 experience modes, you can customize the home page by specifying which modules are visible, their order, and the overall layout using configuration options available in the SDK. + +[div announcementBlock] +-- +[IMPORTANT] +The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. +-- + + +== Home page layout in the V3 experience + +In the V3 experience, the SDK provides the xref:HomePage.adoc[homePage] attribute that allows you to choose the desired home page layout: + +* `homePage: HomePage.ModularWithStylingChanges` + +Enables the V3 modular home page experience with customizable components, styling options, and enhanced layout and visual elements. +* `homePage: HomePage.Modular` + +Enables the basic modular home page experience with customizable components. + +== Customization settings for home page +The following customization settings are available for the modular home page in the V2 and V3 experience modes. + +[width="100%", cols="2,2,2,2"] +[options='header'] +|==== +|SDK property|Classic (V1) experience|V2 experience|V3 experience +| `hiddenHomepageModules` + +Controls the visibility of the modules on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `reorderedHomepageModules` + +Arranges home page modules in the specified order. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `homePageSearchBarMode` + +Sets the home page search bar experience to object search, Spotter/AI search, or none. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `isUnifiedSearchExperienceEnabled` + +Enables a combined interface with both Object Search and Natural Language Search. The unified experience is disabled by default. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `hideHomepageLeftNav` + +Hides the xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on_home_page[left navigation panel] on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `hiddenHomeLeftNavItems` + +Hides xref:customize-nav-full-embed.adoc#_customize_the_left_navigation_panel_on_home_page[specific menu items of the left navigation panel] on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +|==== + +== Control the visibility of home page modules + +In the V2 and V3 experience modes, the home page includes sections such as *Watchlist*, *Favorites*, *Library*, *Trending* charts, and more. You can hide a specific section of the home page and reorder these modules as needed using the xref:AppViewConfig.adoc#_hiddenhomepagemodules[hiddenHomepageModules] and xref:AppViewConfig.adoc#_reorderedhomepagemodules[reorderedHomepageModules] configuration options in the embed SDK. + +The `hiddenHomepageModules` and `reorderedHomepageModules` attributes support the following settings: + +[width="100%", cols="2,2,2,2"] +[options='header'] +|=== +| Allowed values +| Classic (V1) experience +| V2 experience +| V3 experience + +| `HomepageModule.Favorite` + +For the *Favorites* module on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomepageModule.Learning` + +For *Learning* section, which displays learning videos and resources on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomepageModule.MyLibrary` + + For the Library section, which lists Answers and Liveboard objects. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomepageModule.Search` + +For the search module on the home page. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomepageModule.Trending` + +For the Trending section, which shows a list of trending Answers and Liveboards. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +|`HomepageModule.Watchlist` + +For the **Watchlist** section, which is used for KPI monitoring. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +|=== + +=== Customize home page modules in the V3 experience +The following example shows the configuration properties for customizing the home page modules: + +[source,javascript] +---- +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + PrimaryNavbarVersion // Enum for V3 experience setting + HomePage, // Enum for home page experience settings + HomepageModule // Enum for home page modules +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Enable V3 navigation and home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enables V3 experience + homePage: HomePage.ModularWithStylingChanges, // Enables V3 home page + }, + // Hide modules from the home page + hiddenHomepageModules: [ + HomepageModule.Learning, + HomepageModule.Trending + ], + // Custom order for visible modules + reorderedHomepageModules: [ + HomepageModule.Search, + HomepageModule.Favorite, + HomepageModule.Watchlist, + HomepageModule.MyLibrary + ], + //... other view configuration properties +}); +---- + +=== Customize home page modules in the V2 experience +The following example shows the configuration properties for customizing the home page modules in the V2 experience: + +[source,javascript] +---- + + import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomepageModule // Enum for home page modules + } from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { + // Enable V2 experience + modularHomeExperience: true + // Hide modules from the home page + hiddenHomepageModules: [ + HomepageModule.Learning, + HomepageModule.Trending + ], + // Set the order of home page modules + reorderedHomepageModules: [ + HomepageModule.Search, + HomepageModule.Favorite, + HomepageModule.Watchlist, + HomepageModule.MyLibrary + ], + //... Other view configuration properties + }); +---- + +[#_search_experience_on_home_page] +=== Customize the search experience on home page +You can set the search experience on the home page to function as an object search bar that allows finding popular objects, or as an AI search interface that allows natural language queries or Spotter sessions. You can also choose to hide it from the home page. +To configure your preference, specify the following values in the `homePageSearchBarMode` attribute. + +[width="100%", cols="4,8"] +[options='header'] +|===== +|Search bar mode|Description +|`HomePageSearchBarMode.AI_ANSWER` | +Sets the natural language search bar that allows queries in natural language. +If Spotter is enabled on your instance, you can use this setting to set the Spotter search bar on the home page. +|`HomePageSearchBarMode.OBJECT_SEARCH` |Enables object search that allows users to find objects from the library. +|`HomePageSearchBarMode.NONE` a| Hides the search bar on the home page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. + +To hide the search bar on the home page, you can also use the xref:customize-homepage-full-embed.adoc#_control_the_visibility_of_home_page_modules[homepageModule: HomepageModule.Search] setting. +|| +|===== + +[NOTE] +==== +If your instance is using the Classic (v1) experience and if the `homePageSearchBarMode` parameter does not set the search context defined in the attribute, set `isUnifiedSearchExperienceEnabled` to `false`. +==== + +==== Examples +The following examples show code snippets to set the home page search bar mode to Spotter or AI search in different experience modes: + +V3 experience:: + +[source,javascript] +---- +import { + AppEmbed, + PrimaryNavbarVersion // Enum for V3 navigation experience + HomePage, // Enum for home page experience settings + HomePageSearchBarMode // Import the enum for search bar mode options +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable v3 experience + homePage: HomePage.ModularWithStylingChanges // Enable v3 home page experience + }, + // Set the home page search bar to show the Spotter / AI search bar + homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER + // Other view configuration attributes +}); +---- + +V2 experience:: + +[source,javascript] +---- +import { + AppEmbed, + HomePageSearchBarMode // Import the enum for search bar mode options +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + modularHomeExperience: true, // Enable v2 modular home page experience + // Set the home page search bar to show the Spotter / AI search bar + homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER + // Other view configuration attributes +}); +---- + + +Classic (V1) experience:: + +[source,javascript] +---- +import { + AppEmbed, + HomePageSearchBarMode // Import the enum for search bar mode options +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Set the home page search bar to show the Spotter / AI search bar + homePageSearchBarMode: HomePageSearchBarMode.aiAnswer, + // Disable the unified search experience + isUnifiedSearchExperienceEnabled: false, + //... other embed view configuration attributes +}); +---- + +//// +==== Enable AI Search +To set AI Search as the default search experience on the Home page, use the settings shown in the following examples. + +==== Enable AI Search with Spotter (Recommended) +To set Spotter as the default search experience on the Home page, use the settings shown in the following examples. + +===== New Home page experience + +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + isUnifiedSearchExperienceEnabled: "false", + homePageSearchBarMode: "aiAnswer", +}); +---- + +Home page search experience:: + + +Spotter page;; +[.bordered] +[.widthAuto] +image::./images/spotter-fullApp2.png[] + +===== Home page classic experience + +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + isUnifiedSearchExperienceEnabled: "false", + homePageSearchBarMode: "aiAnswer", +}); +---- + + + +Spotter page;; +[.bordered] +[.widthAuto] +image::./images/spotter-fullApp2.png[] + +==== Enable AI Search (legacy) +To enable Natural Language Search (legacy), use the settings shown in these examples: + +===== New Home page experience + +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + homePageSearchBarMode: "aiAnswer", +}); +---- +Home page search experience:: +[.widthAuto] +[.bordered] +image::./images/sage-search-new-exp.png[] + +AI Search page:: + +[.widthAuto] +[.bordered] +image::./images/sage-search-home.png[] + +===== Home page classic experience + +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + homePageSearchBarMode: "aiAnswer", +}); +---- + +Home page search experience:: + +[.widthAuto] +[.bordered] +image::./images/sage_search-home-classic.png[] + +AI Search page:: + +[.widthAuto] +[.bordered] +image::./images/sage-search-home.png[] + +//// + +== Additional resources + +See also: + +* xref:full-embed.adoc[Embed full application] +* xref:full-app-customize.adoc[Customize full application embed] +* xref:AppViewConfig.adoc[AppViewConfig reference page] +* xref:HostEvent.adoc[Host events] +* xref:EmbedEvent.adoc[Embed Events] +* xref:Action.adoc[Actions] diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc new file mode 100644 index 000000000..b66347f3f --- /dev/null +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -0,0 +1,289 @@ += Customize navigation panels +:toc: true +:toclevels: 2 + +:page-title: Customize navigation panels +:page-pageid: customize-nav-controls +:page-description: Customize the the navigation panel and menu items in full application embedding using the settings in the Visual Embed SDK + +You can customize the navigation experience and the visibility of navigation menu elements using the Visual Embed SDK. + +[div announcementBlock] +-- +[IMPORTANT] +The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. +-- + +== Navigation experience +The navigation structure in ThoughtSpot UI varies based on the UI experience mode set in your embed view. + +[width="100%", cols="2,4"] +[options='header'] +|==== +|UI experience| Navigation options +|Classic (V1) experience a|A standard top navigation bar with the following components: + + +* A horizontal application menu +* Help and user profile icons +* Org switcher + +|V2 experience a| +* Simplified top navigation structure. Includes the following components: + +** Object search bar +** The application selector to switch between different application contexts +** Help and profile icons +** Org switcher for instances with Orgs +* A left navigation panel for each application context. +|V3 experience +a| +* Top navigation bar with a modern look and feel. Includes the following components: +** A hamburger icon for the sliding navigation overlay +** Object search bar +** Help and profile icons + +The user profile includes *Admin settings* option, which is visible to users with administration privileges. +** Org switcher +* Left navigation +** A sliding left navigation panel controlled via the hamburger icon +** Persona-based app selection icons in the panel header +** Left navigation menu that adjusts its contents according to the application context. +|==== + +== Customize the top navigation bar +The following customization settings are available for the top navigation bar. + +[width="100%", cols="2,2,2,2"] +[options='header'] +|==== +| SDK property +| Classic (V1) experience +| V2 experience +| V3 experience +|`showPrimaryNavbar` + +To show or hide the navigation experience. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `hideApplicationSwitcher` + +To show or hide the application switcher. +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported + +In V2 experience, hides the app selector in the top navigation bar. +| [tag greenBackground tick]#✓# Supported + +In the V3 experience, hides the app selection icons on the left navigation panel and the *Admin settings* option in the Profile menu. +| `disableProfileAndHelp` + +To show or hide the help and user profile icons in top navigation bar. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +Also hides or shows *Help* menu on the left navigation panel of the home page. +| [tag greenBackground tick]#✓# Supported + +Also hides the *Admin settings* menu in the profile dropdown. + +| `hideOrgSwitcher` + +To show or hide the Org switcher. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `hideNotification` + +To show or hide the notification (bell) icon. +| [tag redBackground tick]#x# Not supported +| [tag redBackground tick]#x# Not supported +| [tag greenBackground tick]#✓# Supported + +| `hideObjectSearch` + +To show or hide the object search bar in the top navigation bar. +| __Not applicable__ + +The object search bar is hidden by default. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `hideHamburger` + +To show or hide the hamburger icon in the top navigation bar. +| __ Not applicable__ +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported + +Hides the hamburger icon available on pages where the left navigation panel is hidden by default. +|==== + +=== Example + +The following example hides the icons in the top navigation and the application selection menu: + +[source,JavaScript] +---- +const embed = new AppEmbed("#embed", { + //... V3 experience attributes + // Show navigation bar + showPrimaryNavbar: true, + hideApplicationSwitcher: true, + // Hide Help and User Profile icons in top navigation + disableProfileAndHelp: true, + // Hide object search bar in top navigation + hideObjectSearch: true, + // Hide the alert icon in top navigation + hideNotification: true, + //... other attributes +}); +---- + +== Customize the left navigation panel on the home page +In the V2 and V3 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides the left navigation only on the home page. + +If you want to include the left navigation, but hide only a specific section in the *Insights* panel, use the `hiddenHomeLeftNavItems` property and specify the menu items to hide. The allowed values for `hiddenHomeLeftNavItems` are listed in the following table: + +[width="100%", cols="2,2,2,2"] +[options='header'] + +|=== +|Allowed values +| Classic (V1) experience +| V2 experience +| V3 experience + +| `HomeLeftNavItem.Create` + +To show or hide the `+` icon that allows users to create a Liveboard or Answer in the *Insights* panel. +| __ Not applicable__ +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.Home` + +To show or hide the *Home* menu in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.Spotter` + +To show or hide the *Spotter* menu item in the *Insights* panel. +| __ Not applicable__ +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.SearchData` + +To show or hide the *Search Data* in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.Liveboards` + +To show or hide the *Liveboards* menu in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.Answers` + +To show or hide the *Answers* menu in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.LiveboardSchedules` + +To show or hide the *LiveboardSchedules* menu in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.MonitorSubscription` + +To show or hide the *Monitor subscriptions* in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.SpotIQAnalysis` + +To show or hide the *SpotIQ analyses* in the *Insights* panel. +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + +| `HomeLeftNavItem.Favorites` + +To show or hide the `Favorites` section in the *Insights* panel. +| __ Not applicable__ +| __ Not applicable__ +| [tag greenBackground tick]#✓# Supported +|=== + +== Examples +The following sections show code samples for customizing the default left navigation panel in the *Insights* section and the home page. + +=== V3 experience + +[source,JavaScript] +---- +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomePage, // Enum for home page experience setting + PrimaryNavbarVersion, // Enum for navigation bar version + HomeLeftNavItem, // Enum for left navigation items +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation + homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page + }, + // Show navigation bar + showPrimaryNavbar: true, + // Show left navigation on home page + hideHomepageLeftNav: false, + // Hide SpotIQ analysis and Favorites menu options + hiddenHomeLeftNavItems: [ + HomeLeftNavItem.Favorites, + HomeLeftNavItem.SpotIQAnalysis + ], + //... other embed view configuration attributes +}); +---- + +=== V2 experience + +[source,JavaScript] +---- +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomeLeftNavItem, // Enum for left navigation items +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Enable the V2 navigation experience + modularHomeExperience: true, + // Show left navigation panel + hideHomepageLeftNav: false, + // Hide SpotIQ analysis and Monitor subscriptions menu options + hiddenHomeLeftNavItems: [ + HomeLeftNavItem.MonitorSubscription, + HomeLeftNavItem.SpotIQAnalysis + ], + //... other embed view configuration attributes +}); +---- + +== Customize the Help menu + +If you want to include the help menu and link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links, window=_blank] to it, ensure that the top navigation bar is visible and `disableProfileAndHelp` is set to `false`. + +By default, the help menu in the embedded view shows the legacy information center controlled using Pendo. To enable the new information center and add custom links, set `enablePendoHelp` to `false`. + +To add custom links to the help menu, use the customization settings available on the **Admin settings** > **Help customization** page. For more information, refer to the link:https://docs.thoughtspot.com/cloud/latest/customize-help[ThoughtSpot Product Documentation]. + +[source,JavaScript] +---- +const embed = new AppEmbed("#embed", { + // Display the top navigation bar + showPrimaryNavbar: true, + // Show the profile and help icons in the top navigation bar. + disableProfileAndHelp: false, + // Use the new ThoughtSpot information center for help and support. + enablePendoHelp: false, + //... other embed view configuration attributes +}); +---- + +== Additional resources +See also: + +* xref:full-app-customize.adoc[Customize full application embed] +* xref:full-embed.adoc[Embed full application] +* xref:AppViewConfig.adoc[AppViewConfig reference page] +* xref:HostEvent.adoc[Host events] +* xref:EmbedEvent.adoc[Embed Events] +* xref:Action.adoc[Actions] diff --git a/modules/ROOT/pages/data-security.adoc b/modules/ROOT/pages/data-security.adoc index 99e98c112..ae6adf312 100644 --- a/modules/ROOT/pages/data-security.adoc +++ b/modules/ROOT/pages/data-security.adoc @@ -15,9 +15,10 @@ Row Level Security (RLS) is the term for filtering down to rows of data based on ThoughtSpot has three mechanisms for row-level security: -* xref:rls-rules.adoc[RLS Rules, window=_blank] applied to the ThoughtSpot table objects -* xref:abac-user-parameters.adoc[Attribute-Based Access Control (ABAC)] filters and parameters passed in via login token -* link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-oauth[OAuth connections, _target=blank]: Individualized login to the data warehouse connection using OAuth, where security rules have already been implemented for each user. +* xref:rls-rules.adoc[RLS Rules, window=_blank] applied to the ThoughtSpot table objects. +* xref:abac_rls-variables.adoc[Attribute-Based Access Control (ABAC)] with custom variables referenced in RLS rules passed in via login token. +* xref:abac-user-parameters.adoc[Attribute-Based Access Control (ABAC)] with filters parameters passed in via login token. +* link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-oauth[OAuth connections, window=_blank]: Individualized login to the data warehouse connection using OAuth, where security rules have already been implemented for each user. The OAuth workflow requires opening a new window or redirecting to the OAuth provider for the initial sign-in workflow, making it less seamless than using a service account and defining data security via ThoughtSpot. It tends to be used for non-embedded ThoughtSpot use cases or for embedded applications for an organization's internal users with existing individual data warehouse user accounts. diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index 8db175032..b64e3d751 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -14,7 +14,7 @@ As ThoughtSpot applications evolve, some existing features will be deprecated an [options='header'] |===== |Feature|Impacted interface and release versions|Deprecation date |End of Support / removal from the product - +a|xref:deprecated-features.adoc#_answer_data_panel_classic_experience_deprecation[Answer Data panel classic experience] |ThoughtSpot Cloud 26.4.0.cl and later | April 2026 | August 2026 a|xref:deprecated-features.adoc#_worksheet_deprecation_and_removal[Worksheets] a| ThoughtSpot Cloud 10.4.0.cl and later |November 2024 | September 2025 @@ -79,7 +79,14 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic |September 2022| January 2023 |||| |===== - + +== Answer Data panel classic experience deprecation +The classic Data panel experience in Search and Answer pages will be deprecated in ThoughtSpot 26.4.0.cl release version. The new data panel experience, which provides a more intuitive layout with improved organization of data elements and features such as query sets and custom groups, will be the default data panel experience on all ThoughtSpot Embedded instances using Visual Embed SDK v1.41.1 or later. + +Recommended action:: +If your instance is still using the classic experience, we recommend switching to the new experience, testing your rollout, and updating your application workflows for a seamless embedding experience. You can enable the new data panel experience using the xref:embed-search.adoc#_data_panel_experience_in_the_embedded_search_page[dataPanelV2] attribute in the Visual Embed SDK. + +For more information and migration assistance, contact ThoughtSpot Support. + == Worksheet deprecation and removal Starting with 10.4.0.cl, Worksheets are deprecated and disabled by default in ThoughtSpot. In ThoughtSpot Cloud 10.12.0.cl and later versions, the ability to create new Worksheets will be removed, and all existing Worksheets will be automatically migrated to Models. diff --git a/modules/ROOT/pages/embed-events.adoc b/modules/ROOT/pages/embed-events.adoc index 6369e3433..ba6616f20 100644 --- a/modules/ROOT/pages/embed-events.adoc +++ b/modules/ROOT/pages/embed-events.adoc @@ -513,9 +513,8 @@ Fires when a change occurs in the data sources, including the initial load of th Fires when a change occurs in the search bar, including the initial load of the `SearchEmbed` component. The returned object includes a `data.search` property with the TML search query from the search box. //// - == Related resources -* Visual Embed SDK documentation xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent] SDK documentation. +* See xref:EmbedEvent.adoc[EmbedEvent] and xref:HostEvent.adoc[HostEvent] SDK documentation. * For information about triggering events on React components, see xref:https://developers.thoughtspot.com/docs/tutorials/react-components/lesson-04[Event listeners for React components]. diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 8a8c35d46..943f8f627 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -64,9 +64,9 @@ For more information about the Liveboard embed object, classes, methods, interfa == Customize Liveboard view -The second argument of the `LiveboardEmbed()` constructor is a `xref:LiveboardViewConfig.adoc[LiveboardViewConfig]` object. This object includes several attributes and properties that are frequently used to customize the `LiveboardEmbed` component to fit within the embedding app's UI experience. +The `LiveboardEmbed` component includes the `xref:LiveboardViewConfig.adoc[LiveboardViewConfig]` object. This object provides various attributes and properties to customize the xref:css-customization.adoc[look and feel of the Liveboard page], xref:embed-actions.adoc[control the visibility of menu actions] and features, and xref:embed-events.adoc[manage interactions between the host and embedded app]. -The most common customization is xref:embed-actions.adoc[controlling the visibility of menu items in the embedded view] by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of xref:Action.adoc[Action] IDs. For information about the other frequently used properties, see xref:embed-pinboard.adoc#common-customizations[common customization options]. +The most common customization is controlling the visibility of menu items in the embedded view by configuring the `disabledActions`, `hiddenActions`, and `visibleActions` properties with an array of xref:Action.adoc[Action] IDs. For information about the other frequently used properties, see xref:embed-pinboard.adoc#common-customizations[common customization options]. == Register, handle, and trigger events diff --git a/modules/ROOT/pages/embed-search.adoc b/modules/ROOT/pages/embed-search.adoc index 7e0cd2918..ffa6e9468 100644 --- a/modules/ROOT/pages/embed-search.adoc +++ b/modules/ROOT/pages/embed-search.adoc @@ -265,9 +265,7 @@ For more information about the search embed object, classes, methods, interface === Data panel experience in the embedded Search page -By default, the data panel on an embedded Search page is presented in the classic experience mode. You can enable the new data panel experience either via ThoughtSpot UI or by setting the `dataPanelV2` property to `true` in the SDK. - -Create an instance of the SearchEmbed object and customize your search page view with the new data panel experience. +The data panel on an embedded Search or Answer page can vary based on the data panel experience configured on your instance. If your instance is using classic experience, you can switch to the new data panel experience either via ThoughtSpot UI or by setting the `dataPanelV2` attribute to `true` in the SDK. [source,javascript] ---- @@ -284,12 +282,8 @@ const searchEmbed = new SearchEmbed(document.getElementById('ts-embed'), { }, }); ---- -[IMPORTANT] -==== -Some action enumerations and variables for custom styling are not supported in the new data panel experience. -==== -For more information about the new data panel experience, see link:https://docs.thoughtspot.com/cloud/latest/search-start[ThoughtSpot product documentation]. +For more information about the new data panel, see link:https://docs.thoughtspot.com/cloud/latest/search-start[ThoughtSpot product documentation]. == Register, handle, and trigger events diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 8474cd352..eef5f426f 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -1,635 +1,395 @@ -= Customize full application embed += Customize full application embedding :toc: true -:toclevels: 2 +:toclevels: 3 :page-title: Customize full application embedding :page-pageid: full-app-customize :page-description: Customize full application embedding -== UI and navigation experience +The Visual Embed SDK provides several controls to customize the embedded view, including setting the default landing page, navigation style, visibility of modules and menu items, and more. -In full application embedding, the ThoughtSpot UI and navigation are available in the following modes: +[div announcementBlock] +-- +[IMPORTANT] +The classic (V1) experience and V2 experience modes will be deprecated in an upcoming release in 2026. Therefore, ThoughtSpot recommends upgrading the UI experience of your full application embedding to the V3 experience. +-- -* Classic experience (default) -* xref:full-app-customize.adoc#_new_modular_home_page_with_a_sliding_navigation_panel[New modular home page with sliding navigation panel] [earlyAccess eaBackground]#Early Access# -* xref:full-app-customize.adoc#_new_navigation_and_home_page_experience_without_the_sliding_panel[New modular home page and navigation without the sliding panel] [earlyAccess eaBackground]#Early Access# +== UI experience modes +ThoughtSpot application supports the following UI experience modes: -=== New modular home page with a sliding navigation panel +* xref:full-app-customize.adoc#_upgrade_to_the_v3_experience[V3 navigation and home page experience] (__Recommended__) +* xref:full-app-customize.adoc#_upgrade_from_the_v2_experience_to_v3_experience[V2 navigation and home page experience] +* Classic (V1) experience (__Default experience__) -The new navigation and modular home page experience provides an intuitive and efficient navigation structure. It organizes the application menu into persona-based modules designed specifically to address users' needs. Each module has a menu selector with a visual icon, to allow users to switch between contexts easily. Users can slide out the left navigation panel by clicking the hamburger icon in the header. +The key differences between these UI experience modes are listed in the following table: -If your application instance has classic experience, you'll notice the following changes when the new experience is enabled: - -* A redesigned UI with a sliding navigation panel. -* The app selector icons for *Insights*, *Data workspace*, and *Develop* appear in the header section of the left navigation panel. This selector provides access to persona-based apps, replacing the old top navigation menu. The left navigation panel provides quick access to different modules and can be customized. -* The *Admin* module is available under the user settings section in the top right corner. -* The *Home* page is available in the *Insights* section. The Home page is customizable and includes features such as Natural Language Search, watchlist, favorites, a library of Answers and Liveboards, and trending charts. -* The *Insights* section in the left navigation panel provides quick access to the Home page, Answers, Liveboards, and more. The panel also includes a list of users' favorites. -* The top navigation panel includes the following components: -** A Hamburger icon to allow users to slide out or slide in the navigation panel. -** Object search bar with quick access to the library. -** An Alert icon that shows notifications -** Help icon to access documentation -** Org switcher to switch between Org contexts -** Access to *Profile*, *Admin settings* (if the user has administrator privilege), and *Sign out* options. - -The following figure shows the new navigation panel and modular Home page: - -[.bordered] -[.widthAuto] -image::./images/new-nav3.png[New home page] - -==== Modular Home page -The customizable home page in ThoughtSpot’s new experience is available in the *Insights* section. It allows users to personalize the layout and content modules. Users can reorder sections, such as watchlist, favorites, library, trending charts, and more. For full app embedding application users, developers can set a default layout to include only the modules they want. - -==== Configure new experience -The navigation and home page experience is turned off by default. Administrators can enable it on their instance at the cluster level for all users. When this feature is enabled on the instance, users can switch between classic and new experience by turning off or enabling the experience in their profile settings. On embedded applications, you'll need to enable this experience using the `discoveryExperience` property as shown in this example: - -[source,JavaScript] ----- -const embed = new AppEmbed('#tsEmbed', { - // Enable the new modular home page and navigation experience - modularHomeExperience: true, - // Set the top navigation bar in the embedded view - showPrimaryNavbar: true, - discoveryExperience: { - // Set the navigation bar to use the new sliding (icon-based) style - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, - // Set the home page to use the modular layout - homePage: 'Modular', - }, - //other options -}); ----- - -=== New navigation and Home page experience without the sliding panel - -In the new navigation and Home page experience, the app selector image:./images/app_switcher.png[the app switcher menu] appears on the top header bar. The app selector consists of different persona-based contextual elements to allow users to switch between contexts. Clicking an app in the app selector menu opens the corresponding application page. Each application module has a separate left navigation panel. - -If your application instance has classic experience, you'll notice the following changes in the UI: - -[.bordered] -[.widthAuto] -image::./images/homepage.png[New home page] - -The new navigation and Home page experience introduces several UI changes. - -.View UI changes -[%collapsible] -==== -[width="100%", cols="3,7,7"] +[div boxAuto] +-- +[width="100%", cols="2,4,4,5"] [options='header'] |===== -||Classic experience |New navigation and Home page experience -|Navigation a|Top navigation menu with the following buttons: - -* **Home** + -Opens Home page + -* **Answers** + -Opens Answers page + -* **Liveboards** + -Opens Liveboards page + -* **SpotIQ** + -Opens SpotIQ analyses page + -* **Monitor** + -Opens subscription alerts page + -* **Data** + -Opens the Data workspace page (Requires data management privilege) + -* **Admin** + -Opens Admin page (Requires administration privilege) + -* **Develop** + -Opens **Develop** page (Requires developer privilege) + -* **Search data** + -Opens Search data page - -a| App selector image:./images/app_switcher.png[the app switcher menu] with the following apps: - -* **Insights** + -Opens the Insights page. Note that the Answers, Liveboards, SpootIQ, and Monitor Subscriptions are grouped as Insights in the new Home page experience. + -** **Insights** > **Home** + -Opens Home page -** **Insights** > **Search Data** + -Opens the Search Data page. -** **Insights** > **Answers** + -Opens the Answers page. -** **Insights** > **Liveboards** + -Opens the Liveboards page. -** **Insights** > **SpotIQ Analysis** + -Opens the SpotIQ page. -** **Insights** > **Monitor Subscriptions** + -Opens Monitor alerts page. + -The **Insights** page also includes **Help** and **Chat with Support** menu options. -* **Data workspace** + -Opens the Data workspace page (Requires data management privilege) -* **Admin** + -Opens Admin page (Requires administration privilege) -* **Developer** + -Opens **Develop** page (Requires developer privilege) -* **Search Data** + -Opens Search data page -* **View all Liveboards** + -Opens Liveboards page -* **View all Answers** + -Opens Answers page -|Home page experience |In the classic experience mode, the **Home** page shows the Natural Language Search panel, a list of Answers and Liveboards, and trending charts. | The **Insights** page in new experience mode shows a customizable home page with features such as Natural Language Search panel, watchlist, favorites, a library of Answers and Liveboards, trending charts, and more. With the new left-hand navigation, users can navigate to your Liveboards, Answers, SpotIQ analysis, and Monitor subscriptions. -|Application page URLs a| -* **Liveboards** + -`\https://{ThoughtSpot-Host}/#/pinboards` -* **Answers** + -`\https://{ThoughtSpot-Host}/#/answers` -* **SpotIQ** + -`\https://{ThoughtSpot-Host}/#/insights` -* **Monitor** + -`\https://{ThoughtSpot-Host}/#/monitor` -a| -* **Liveboards** + -`\https://{ThoughtSpot-Host}/#/home/liveboards` -* **Answers** + -`\https://{ThoughtSpot-Host}/#/home/answers` -* **SpotIQ** + -`\https://{ThoughtSpot-Host}/#/home/spotiq-analysis` -* **Monitor** + -`\https://{ThoughtSpot-Host}/#/home/monitor-alerts` -|Liveboards and Answers| In the classic experience mode, users can use All, Yours, and Favorites tabs to filter the Liveboards and Answers list| In new experience, the Liveboard and Answers list page provides filters for each column. For example, to view their favorite Liveboards, users can click the star icon in the column head and apply a filter to show only their starred (favorite) Liveboards. Similarly, users can filter the list by author to view only their Liveboards or Answers. -|===== -[%collapsible] -==== +|Feature component |Classic (V1) experience | V2 experience | V3 experience +|**UI experience**| Classic layout + -==== Enable new experience mode without the sliding panel -By default, the new navigation and home page experience is turned off on ThoughtSpot embedding applications. To enable the new experience mode for embedding application users, set `modularHomeExperience` to `true` in the `AppEmbed` component. +Includes a standard top navigation, pages without a left navigation panel, and a static home page with limited customization options.| Improved look and feel + -[source,javascript] ----- -const embed = new AppEmbed("#embed", { - pageId: Page.Home, - modularHomeExperience: true, - frameParams: { - height: '100%', - width: '100%' - } -}); ----- - -== Choose the default page to load -When embedding the full app, you can use either `pageId` or `path` parameter to specify the page to load when the embedded component loads. If both `path` and `pageId` properties are defined, the `path` definition takes precedence. +Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. | Modern look and feel + -=== pageId -The `pageId` parameter of the `AppEmbed` xref:full-embed#_create_an_instance_of_the_appembed_object[parameters object] lets you specify the ThoughtSpot page in the `Page` enumeration that the AppEmbed component loads to. Valid values for this attribute are: +Includes a left navigation panel that dynamically adjusts its menu based on context and a modular home page with enhanced visual elements and customizable components. +|**Navigation experience**| Top navigation includes the application menu. + +Limited customization controls |Redesigned top navigation bar with an app selector and other icons + +Separate left navigation panel for each application context| Sliding left navigation panel with persona-based application icons + +A dynamic left navigation menu that adjusts its contents according to the application context. +|**Home page experience**| Static home page with limited customization control | Modular home page with customizable components |Modular home page with customizable components, enhanced styling, and visual elements. -* `Page.Home` for the ThoughtSpot *Home* page + -* `Page.Search` for the ThoughtSpot *Search* page + -* `Page.Answers` for the *Answers* page + -* `Page.Liveboards` for the *Liveboards* page + -* `Page.Data` for the *Data* page + -* `Page.SpotIQ` for the *SpotIQ* analyses page +|**Feature availability**| Enabled by default| Disabled by default | Disabled by default -[source,javascript] ----- -const embed = new AppEmbed("#embed", { - pageId: Page.Liveboards, - showPrimaryNavbar: false, - frameParams: { - height: '100%', - width: '100%' - } -}); ----- - -=== path -The URL path of the ThoughtSpot application page that you want your embed application users to navigate to. + - -[source,javascript] ----- -const embed = new AppEmbed("#embed", { - path: 'pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9', - frameParams: { - height: '100%', - width: '100%' - } -}); ----- - -The following examples show valid strings for `path`: - -[width="100%", cols="3,6,6"] -[options='header'] -|===== -|Page| Classic experience | New navigation and Home page experience -|Home| `path: "home"` | `path: "home"` -|Answers| `path: "answers"`| `path: "home/answers"` -|Saved Answer| `path: "saved-answer/"` |`path: "saved-answer/"` -|Liveboards| `path: "pinboards"`| `path: "home/liveboards"` -|Liveboard| `path: "pinboard/"`| `path: "pinboard/"` -|SpotIQ analysis list|`path: "insights"`| `path: "home/spotiq-analysis"` -|SpotIQ analysis page| `path: "insight/"`| `path: "insight/"` -|Data| `path: "data/tables/"`| `path: "data/tables/"` -|Model, tables, views|`path: "data/tables/"`| `path: "data/tables/"` -|Monitor| `path: "monitor"` | `path: "monitor"` + -or + -`path: "home/monitor-alerts"` |===== - -=== navigateToPage() - -The `AppEmbed` object has a method called `navigateToPage()` that will switch the currently loaded page in the ThoughtSpot embedded application. The `navigateToPage()` method accepts the values that work for `pageId` or `path` parameters. - -The new navigation menu should call `navigateToPage` for the various pages you want to provide access to: - -[source,JavaScript] ----- -embed.navigateToPage(Page.Answers); -// with noReload option -embed.navigateToPage(Page.Answers, true); ----- - -=== history.back() -Page changes within the `AppEmbed` component register as part of the embedding app's history to the web browser. - -The standard JavaScript `history.back()` function will cause the `AppEmbed` component to go to the previously loaded page up until the very first ThoughtSpot page loaded within the component. - -[#_search_experience_on_home_page] -== Customize Search experience in full app embed - -// ** Create a xref:embed-nls.adoc[Natural Language Search page using SageEmbed] and build a navigation to this page from your embedding application. - -The search components available for full application embed and the configuration settings required for these components are listed in the following table: - -[width="100%", cols="4,8"] +-- +//// +[width="100%", cols="2,8,8,8"] [options='header'] |===== -|Type| Description -|Object Search a| Allows finding popular Liveboards and Answers from the recommended suggestions. +||V1 (Legacy) |V2 experience |V3 experience + +|Navigation style a|* Top navigation bar for application menu. + +* Separate left navigation panels only for specific application context, such as *Data*, *Admin* and *Develop* modules a| +* Persona-based app selector on the top navigation bar + +* A separate left navigation panel for each persona-based application context a| +* Sliding left navigation panel +* Persona-based tabs on the left panel to switch between application context. +* Separate left navigation panel for each application context. +|Home page experience| Basic | Modular and customizable home page | Modular +|Enablement| The default, legacy ThoughtSpot UI. a| Disabled by default. + +Can be enabled by setting `modularHomeExperience: true` in the Visual Embed SDK a| Disabled by default. + +Can be enabled by setting the `discoveryExperience` properties in the Visual Embed SDK. +|Migration considerations| If you want to continue using the classic experience, no migration is required. +If you plan to switch to the new navigation and modular home page experience, ThoughtSpot recommends migrating to the new v3 experience. +| The v2 navigation experience can be enabled by setting `modularHomeExperience` to `true` in the Visual Embed SDK. However, the new v3 experience with left navigation panel provides an improved experience and more customizable components for home page, therefore, we recommend using the v3 experience. +If you are already on v2 experience and want to switch to the new v3 experience, contact ThoughtSpot Support to enable this feature on your instance. +Once enabled, configure the `discoveryExperience` properties and customize your home page experience as per your embedding requirements. +|Contact ThoughtSpot Support to enable the v3 experience on your ThoughtSpot instance. +Once enabled, configure the `discoveryExperience` properties and customize your home page experience as per your embedding application requirements. +|||| +|===== +//// -On instances running 10.1.0.cl or lower, the Home page provides a combined interface with Object Search and Natural Language Search. On instances running 10.3.0.cl or later, with split search experience enabled, the Object Search will be the default search experience on the Home page. +== Customize the embedded application UI for your users -The Object Search bar also appears on the top navigation bar if the top navigation bar visibility is enabled ( `showPrimaryNavbar: true`) in the SDK. +Before updating the UI experience, review the xref:full-app-customize.adoc#_ui_experience_modes[key features, limitations], and available SDK controls for customizing xref:customize-nav-full-embed.adoc[navigation] and the xref:customize-homepage-full-embed.adoc[home page]. -|Spotter Search | In addition to AI Search capabilities, Spotter provides a conversation interface for queries and follow-up questions. + -If Spotter is enabled on your instance, and `homePageSearchBarMode: "aiAnswer"` property is set in the SDK along with split search enabled (`isUnifiedSearchExperienceEnabled: false`), the search experience on the Home page switches to Spotter in full application embed. +For more information about the layout and UI elements in the V3 experience, refer to the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage[ThoughtSpot Product Documentation, window=_blank]. -For more information, see xref:full-app-customize.adoc#_enable_ai_search_with_spotter[Enable AI Search with Spotter]. -| Search data a| Allows searching a data source using keywords and search tokens. This experience is available if you have set the `pageId` attribute to `Page.Search` or enabled navigation to the Search page of your ThoughtSpot application. -|Natural Language Search (legacy interface) a| Allows searching a data source using a natural language query string and get AI-generated Answers. -On instances running 10.3.0.cl or earlier, with split search experience disabled, the Search interface on the Home page provides a combined view of Natural Language Search (legacy interface) and Object Search. However, on instances running 10.3.0.cl or later, split search is enabled by default. Due to this, the Home page will not show Natural Language Search as the default search experience. +=== Upgrade to the V3 experience +If you are using the classic (V1) experience in your embed, ThoughtSpot recommends migrating directly to the V3 experience for an improved user interface, enhanced home page customization options, and navigation controls. -Note that the legacy Natural Language Search option is deprecated and replaced with Spotter Search. You can enable Natural Language Search with Spotter, by setting `homePageSearchBarMode` to `aiAnswer` in the SDK. -|===== +Before you begin: +* Verify if your ThoughtSpot instance has the V3 experience enabled at the cluster level. +* Ensure that your embedding environment has the latest version of the Visual Embed SDK. The minimum supported version for the V3 experience is v1.40.0. +* If you are using direct CSS selectors for style customization, test your customization in the Playground. +* If your embed uses action customization and the SDK events for app interactions, test your customizations for compatibility across different UI experiences to ensure seamless migration. +==== V3 experience settings in the SDK -//// -New home page and navigation experience mode:: -By default, the Object Search bar is displayed in the Search module on the embedded **Home** page: -+ -[.bordered] -image::./images/objSearchNav_modularExp.png[] +To enable the V3 experience, you must use the `discoveryExperience` object in the SDK. This object supports the following properties: -Classic experience mode:: -By default, the Object Search bar is displayed on the embedded **Home** page. +* `primaryNavbarVersion` + +Enables the V3 experience. The valid value for the V3 experience is `PrimaryNavbarVersion.Sliding`. + +If this attribute is not set, no changes will be applied, and the currently enabled UI experience in your app will be retained. -+ -[.bordered] -image::./images/sageDisabledwithNav_classic.png[] -//// +* `homePage` + +Enables the modular home page experience. Valid values include: +** `HomePage.ModularWithStylingChanges` (__Recommended__) + +Enables the V3 modular home page experience. You must include `primaryNavbarVersion` to update the UI experience to the V3 home page. +** `HomePage.Modular` + +Enables the modular home page experience with customizable components. This experience does not include the styling options and visual changes available with the full V3 experience. We do not recommend using this option, as it will be deprecated in an upcoming 2026 release. -=== Home page search experience options - -Developers can customize the Search experience by setting the `homePageSearchBarMode` property in the SDK to a desired value: - -** `objectSearch` (default) + -Displays Object Search bar on the **Home** page. -** `aiAnswer` + -Displays the search bar for Natural Language Search -** `none` + -Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +[IMPORTANT] +==== +* To enable the full V3 experience, both `primaryNavbarVersion` and `homePage` attributes must be set in the SDK. Not setting `primaryNavbarVersion` will result in no changes to the UI experience. +* If you include only the `homePage: HomePage.ModularWithStylingChanges` attribute in `discoveryExperience`, it will be ignored. + +* If you include only the homePage attribute with its value as `HomePage.Modular`, the v2 modular home page experience will be enabled. -==== Enable AI Search -To set AI Search as the default search experience on the Home page, use the settings shown in the following examples. +For information about these configuration combinations and their effects, see xref:full-app-customize.adoc#_ui_customization_options_and_resulting_experience[UI customization options and resulting experience]. +==== -==== Enable AI Search with Spotter (Recommended) -To set Spotter as the default search experience on the Home page, use the settings shown in the following examples. +==== Upgrade from classic (V1) experience to V3 experience +To enable the V3 experience, set the `primaryNavbarVersion` and `homePage` parameters in the `discoveryExperience` object as shown in the following example. -===== New Home page experience +Note that these attributes use the values from the xref:PrimaryNavbarVersion.adoc[PrimaryNavbarVersion] and xref:HomePage.adoc[HomePage] enumerations. -[source,javascript] +[source,JavaScript] ---- +// Import required components and enums for V3 experience +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomePage, // Enum for home page experience settings + PrimaryNavbarVersion // Enum for V3 navigation experience +} from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - isUnifiedSearchExperienceEnabled: "false", - homePageSearchBarMode: "aiAnswer", + // Enable V3 navigation and home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation + homePage: HomePage.ModularWithStylingChanges, // Enable V3 home page experience + }, + // Show navigation panels + showPrimaryNavbar: true, + //... other embed view configuration attributes }); ---- -Home page search experience:: +==== Upgrade from the V2 experience to V3 experience +Both V2 and V3 experience modes support a modular home page with customizable components. The V3 modular home page experience includes additional improvements to the Watchlist, Trending, Learning, and Favorites panels. -[.bordered] -[.widthAuto] -image::./images/spotter-fullApp.png[] - -Spotter page;; -[.bordered] -[.widthAuto] -image::./images/spotter-fullApp2.png[] +To upgrade your UI to the V3 experience, set `homePage` to `HomePage.ModularWithStylingChanges`: -===== Home page classic experience +[source,JavaScript] +---- +// Import required components and enums for V3 experience +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomePage, // Enum for home page experience settings + PrimaryNavbarVersion // Enum for V3 navigation experience +} from '@thoughtspot/visual-embed-sdk'; -[source,javascript] +const embed = new AppEmbed("#embed", { + // Enable V3 navigation and home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable V3 navigation experience + homePage: HomePage.ModularWithStylingChanges, // Enable V3 modular home page + }, + // Show navigation panels + showPrimaryNavbar: true, + //... other embed view configuration attributes +}); +---- +//// +* `homePage: HomePage.Modular` for the V2 modular home page layout. This option doesn't include the customizable components available in the V3 experience. ++ +[source,JavaScript] ---- +// Import required components and enums for V3 experience +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + HomePage, // Enum for home page experience settings + PrimaryNavbarVersion // Enum for V3 navigation experience +} from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { - isUnifiedSearchExperienceEnabled: "false", - homePageSearchBarMode: "aiAnswer", + // Enable V3 navigation and home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enables V3 navigation + homePage: HomePage.ModularWithStylingChanges, // Enables V2 modular home page + }, + // Show navigation panels + showPrimaryNavbar: true, + //... other embed view configuration attributes }); ---- +//// -Home page search experience;; -[.bordered] -[.widthAuto] -image::./images/spotter_search-home-classic.png[] +==== Post migration checks +After you enable the V3 experience: -Spotter page;; +* Ensure the UI shows the V3 navigation and home page. ++ +The following figure shows the user interface with the V3 experience: ++ [.bordered] [.widthAuto] -image::./images/spotter-fullApp2.png[] - -==== Enable AI Search (legacy) -To enable Natural Language Search (legacy), use the settings shown in these examples: +image::./images/new-nav3.png[New home page] -===== New Home page experience +* Verify that all the customization settings are applied correctly. +* If you have set up custom routes for navigation within your embedded app, verify navigation workflows and check for breaking changes. -[source,javascript] ----- -const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - homePageSearchBarMode: "aiAnswer", -}); ----- -Home page search experience:: -[.widthAuto] -[.bordered] -image::./images/sage-search-new-exp.png[] -AI Search page:: +//// +* A sliding left navigation panel with the following components: +** The app selector icons for *Insights*, *Data workspace*, and *Develop* appear in the left navigation panel header. +** The *Liveboards*, *Answers*, *Search Data*, and *Spotter* menu options in the *Insights* section. The *Insights* panel also includes a list of users' favorites. +** The *Home* menu option in the *Insights* section. + +* A top navigation header with the following components: +** A hamburger icon to slide in or close the navigation overlay +** Object search bar +** The alert icon that shows notifications +** Help and user profile icons. The user profile menu includes the *Admin settings* menu. This option is visible only to users with administration privileges. +** Org switcher to switch between Org contexts -[.widthAuto] -[.bordered] -image::./images/sage-search-home.png[] +* Home page experience +** Modular home page with specific sections for Search, Watchlist, Favorites, and so on. +//// -===== Home page classic experience +=== Upgrade from classic (V1) experience to V2 experience +Setting `modularHomeExperience` to `true` in the SDK enables the V2 experience. [source,javascript] ---- const embed = new AppEmbed("#embed", { - homePageSearchBarMode: "aiAnswer", + // Enable the V2 experience + modularHomeExperience: true, + //... other view config attributes }); ---- -Home page search experience:: +[NOTE] +==== +The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features. +==== +//// +The following figure shows the user interface with the V2 experience enabled: -[.widthAuto] [.bordered] -image::./images/sage_search-home-classic.png[] - -AI Search page:: - [.widthAuto] -[.bordered] -image::./images/sage-search-home.png[] - -== Customize navigation controls -The `AppEmbed` package in the Visual Embed SDK provides several parameters to hide or customize navigation controls. +image::./images/homepage.png[New home page] +//// -The top navigation menu bar (classic experience), app selector image:./images/app_switcher.png[the app switcher menu] (New experience), and left navigation panel on the home page (New experience) are hidden by default in the embedded view. To show these elements in the embedded view, set `showPrimaryNavbar` to `true`. If the navigation panel is visible in the embedded view, you can use the following parameters in the `AppEmbed` component for additional customization: +=== UI customization options and resulting experience -* `hideOrgSwitcher` + -Hides the Orgs drop-down. Applicable to only Orgs-enabled clusters. -* `hideApplicationSwitcher` + -Hides the app selector image:./images/app_switcher.png[the app switcher menu]. The app selector is available only in the new navigation and Home page experience mode. -* `disableProfileAndHelp` + -** To hide help and profile icons (Classic experience) + -** To hide help and profile icons, Help and Chat with Support menu options on the Home page (New Experience). +The following table summarizes the resulting UI experience for different configuration combinations: -=== Help menu customization -On ThoughtSpot instances running 10.8.0.cl and later, a unified help and support experience is available. The new information center experience provides access to ThoughtSpot documentation and support and allows administrators to link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links]. +[div boxAuto] +-- +[width="100%", cols="6,7,6"] +[options='header'] +|=== +|If `modularHomeExperience` is | And `discoveryExperience` is| UI experience will be -If you have embedded the full ThoughtSpot application with the top navigation bar and Help (?) icon with the `showPrimaryNavbar: true` and `disableProfileAndHelp: false` settings in the Visual Embed SDK and if you want to try the new information center experience, use the xref:AppViewConfig.adoc#_enablependohelp[enablePendoHelp] attribute in the SDK. +|`true` / `false` + +Not set / Incorrect a| -By default, the `enablePendoHelp` attribute is set to `true` for customer environments using the legacy information center generated by Pendo. To enable the new experience, you need to set `enablePendoHelp` to `false`. [source,JavaScript] ---- -const embed = new AppEmbed("#embed", { - ... // other options - showPrimaryNavbar: true, - disableProfileAndHelp: false, - enablePendoHelp: false, -}); +discoveryExperience: { + // V3 experience and navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // V3 modular home page + homePage: HomePage.ModularWithStylingChanges + } ---- +| V3 navigation and V3 modular home page -=== Customize the left navigation panel on Home page (New experience) -If the new navigation and Home page experience is enabled and `showPrimaryNavbar` to `true`, the home page displays a navigation panel on the left side of the Insights page. The panel consists of menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and so on. +|`true` / `false` + +Not set / Incorrect a| -To hide the left navigation panel in the embedded view, set `hideHomepageLeftNav` to `true`. - -[source,javascript] +[source,JavaScript] ---- -const embed = new AppEmbed("#embed", { - ... // other attributes - modularHomeExperience: true, - showPrimaryNavbar: true, - hideApplicationSwitcher: true, - hideHomepageLeftNav: true, - disableProfileAndHelp: true, -}); +discoveryExperience: { + // V3 navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // modular home page + homePage: HomePage.Modular + }, ---- -If you don't want to hide the left navigation panel, but show only a select few menu items, use xref:AppViewConfig.adoc#_hiddenhomeleftnavitems [`hiddenHomeLeftNavItems`] array. +| V3 navigation and a modular home page that is similar to the V2 experience -[source,javascript] +|`true` / `false` + +/ Not set / incorrect a| +[source,JavaScript] ---- -const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - showPrimaryNavbar: true, - hiddenHomeLeftNavItems: [HomeLeftNavItem.Home,HomeLeftNavItem.Liveboards], -}); +discoveryExperience: { + // V3 navigation + primaryNavbarVersion: PrimaryNavbarVersion.Sliding + }, ---- +|V3 navigation and a modular home page that is similar to the V2 experience -== Customize Home page modules (New experience) -If the new navigation and Home page experience is enabled on your ThoughtSpot instance, the Home page shows modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more. To customize these modules and the Home page experience, use the xref:AppViewConfig.adoc#_hiddenhomepagemodules[`hiddenHomepageModules`] array. +|`true` / `false` + +/ Not set / incorrect a| -[source,javascript] +[source,JavaScript] ---- -const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - hiddenHomepageModules : [HomepageModule.Learning,HomepageModule.MyLibrary] -}); +discoveryExperience: { + // modular home page + homePage: HomePage.Modular + }, ---- -To reorder Home page modules, use the xref:AppViewConfig.adoc#_reorderedhomepagemodules[ `reorderedHomepageModules`] array. +| V2 navigation and V2 modular home page -[source,javascript] +a|`true` a| + +[source,JavaScript] ---- -const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - reorderedHomepageModules:[HomepageModule.Search,HomepageModule.Favorite,HomepageModule.Trending] -}); +discoveryExperience: { + // V3 modular home page + homePage: HomePage.ModularWithStylingChanges + }, ---- +| V2 navigation and V2 modular home page -== Hide columns on list pages -You can hide the following columns on the *Liveboards* and *Answers* listing pages using the xref:AppViewConfig#_hiddenlistcolumns[hiddenListColumns] array: - -* Author -* Favorite -* Last modified -* Tags -* Share - -To hide one or several columns on the list pages, pass the relevant list page column enumerations in the `hiddenListColumns` array: - -* `ListPageColumns.Author` -* `ListPageColumns.Favourite` -* `ListPageColumns.DateSort` -* `ListPageColumns.Tags` -* `ListPageColumns.Share` +a| `false` / Not set / incorrect a| -[source,javascript] +[source,JavaScript] ---- -const embed = new AppEmbed("#embed", { - // hide Author, Share, and Tags columns on Answers and Liveboards list page - hiddenListColumns: [ListPageColumns.Author,ListPageColumns.Share,ListPageColumns.Tags] -}); +discoveryExperience: { + // V3 modular home page + homePage: HomePage.ModularWithStylingChanges + }, ---- +|Classic (V1) experience. -[NOTE] -==== -The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button above the list. To hide both the column and the *Share* (xref:Action.adoc#_share[Action.Share]) button above the list, use the `hiddenActions` or `visibleActions` array. -==== -== Detect changes in the currently loaded page -Various actions the user takes within the embedded ThoughtSpot application may cause navigation within ThoughtSpot. +a|`true` a| Not set | V2 navigation and V2 modular home page -The embedding web application can listen for the `EmbedEvent.RouteChange` event by attaching an event listener to the `AppEmbed` object. The response has a `currentPath` property which is the path after the ThoughtSpot domain, for example: ----- -pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9 ----- +a|`false` / Not set / incorrect a| Not set | Classic (V1) experience +|=== +-- -To parse the `currentPath` into varying useful components, this `tsAppState` object code can be created in the global scope for use by any other web application code: +== Customize navigation experience -[source,JavaScript] ----- -// Simple global object to handle details about what is visible in the AppEmbed component at a given moment -let tsAppState = { - currentPath: startPath, - currentDatasources: [], // Can be set later when detected from TML or other events - // return back what is being viewed at the moment, in the form that will translate to the pageId property if captialized, or path property if not - get pageType() { - if (this.currentPath.includes('/saved-answer/')){ - return 'answer'; - } - else if (this.currentPath.includes('/pinboard/')){ - return 'liveboard'; - } - /* - * Others are meant to match the exact pageId from SDK - */ - else if(this.currentPath.includes('/answer/')){ - return 'Search'; - } - else if(this.currentPath.includes('/answers')){ - return 'Answers'; - } - else if (this.currentPath.includes('/pinboards')){ - return 'Liveboards'; - } - else if(this.currentPath.includes('/insights')){ - return 'SpotIQ'; - } - else if(this.currentPath.includes('/monitor')){ - return 'Monitor'; - } - else if(this.currentPath.includes('/data')){ - return 'Data'; - } - else { - return 'Home'; - } - }, - // If viewing an Answer or Liveboard, returns the GUID of that object from the parsed URL - get objectId() { - let pathParts = this.currentPath.split('/'); - // '/saved-answer/' is path for Answers (vs. /answer/) - if (this.currentPath.includes('/saved-answer/')){ - answerGUID = pathParts[2]; - return pathParts[2]; - } - // '/pinboard/' is path for saved Liveboards - else if (this.currentPath.includes('/pinboard/')){ - let pathParts = this.currentPath.split('/'); - // May need adjustment for tabbed views to add in current Tab - liveboardGUID = pathParts[2]; - return pathParts[2]; - } - else{ - return null; - } - } +For information about the navigation elements in each UI experience mode and the related customization settings in the SDK, see xref:customize-nav-full-embed.adoc[Customize navigation experience]. -} ----- +== Customize home page experience +For information about the home page components and the related customization settings in the SDK, see xref:customize-homepage-full-embed.adoc[Customize home page experience]. -The following example shows the event listener code updating the global `tsAppState` object above whenever there is a change within the embedded ThoughtSpot app: +== Customize the default loading page and navigation routes +In full application embedding, the home page is set as the default landing page when the embedded app loads. You can xref:set-default-page.adoc[customize the default landing page settings] using the `pageId` or `path` attribute. -[source,JavaScript] ----- -embed.on(EmbedEvent.RouteChange, (response) => { - // console.log("RouteChange fires"); - // console.log(response); - // tsAppState object has currentPath property, which allows its other methods to parse out pageId, object type, GUIDs etc. - tsAppState.currentPath = response.data.currentPath; - console.log("TS App page is now: ", tsAppState.currentPath); - - // Update elements within your web application based on the new state of ThoughtSpot (adjust menu selections, etc.) - -}) ----- +== Customize list pages +A list page in ThoughtSpot refers to a page that displays a list of objects, such as Answers, Liveboards, and Liveboard schedules. The list pages include columns for sorting, filtering, tagging, and performing bulk actions such as marking favorites, sharing, or deleting objects. -== Navigate using a custom action -To add a custom action for in-app navigation, follow these steps: +To customize the columns in list pages such as *Liveboards* and *Answers*, use the xref:AppViewConfig.adoc#_hiddenlistcolumns[hiddenListColumns] attribute. Valid values that correspond to the column names on the list pages are: -. xref:custom-actions-callback.adoc[Add a custom action]. -. Define the navigation path +* `ListPageColumns.Author` to show or hide the *Author* column +* `ListPageColumns.Favourite` to show or hide the *Favourite* column +* `ListPageColumns.DateSort` to show or hide the *Last modified* column +* `ListPageColumns.Tags` to show or hide the *Tags* column +* `ListPageColumns.Share` to show or hide the *Share* links in the column -In this example, the **view-report ** action on a Liveboard page calls the `navigateTo` method to open a specific saved Answer page when a user clicks the **View report** button in the embedded app. +The following example hides specific columns using the `hiddenListColumns` array: -[source,JavaScript] ----- -appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => { - if (payload.payload.id === 'view-report') { - appEmbed.navigateToPage( - 'saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e' - ); - } -}) +[source,javascript] ---- +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + ListPageColumns // Enum for columns on list pages +} from '@thoughtspot/visual-embed-sdk'; -If you want to navigate to a specific application page without initiating a reload, you can set the `noReload` attribute to `true` as shown here: +const embed = new AppEmbed("#embed", { + // hide Author, Share, and Tags columns on Answers and Liveboards listing pages + hiddenListColumns: [ + ListPageColumns.Author, + ListPageColumns.Share + ], + //... other view config attributes -[source,javascript] ----- -appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => { - if (payload.payload.id === 'view-report') { - appEmbed.navigateToPage('saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e', true); - } -}) +}); ---- -== CSS customization and hiding page elements -xref:css-customization.adoc[CSS customization] allows overriding the default styles from the ThoughtSpot application, including the application pages. - -If there is an element of a page that you dislike and cannot hide with any combination of other options in ThoughtSpot, you can often use CSS customization to target the element and apply either `display: none;`, `visibility: hidden;` or `height: 0px;` and make it functionally disappear to the end user. +[NOTE] +==== +The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button above the list. To hide both the column and the *Share* (xref:Action.adoc#_share[Action.Share]) button above the list, use the `hiddenActions` or `visibleActions` array. +==== -Specifying a direct element using the direct CSS selectors vs. the ThoughtSpot provided variables. To discover the appropriate selector, use the *Inspect* functionality of your browser to bring up the *Elements* portion of the browser's Developer Tools, then look at the *Styles* information. +== Additional customization controls +xref:css-customization.adoc[CSS customization] allows overriding default styles in ThoughtSpot application pages. You can also use xref:theme-builder.adoc[Theme Builder] to explore the available CSS variables. -An example of using direct selectors in a file is available in the link:https://github.com/thoughtspot/custom-css-demo/blob/main/complete.css[complete.css, target=_blank]. +If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as `display: none`;, `visibility: hidden`;, or `height: 0px` to hide it from the UI. To find the appropriate selector, use your browser’s *Inspect* tool to examine the style element in the *Elements* section of the browser's Developer Tools. [source,css] ---- @@ -639,7 +399,10 @@ An example of using direct selectors in a file is available in the link:https:// } ---- -Direct selectors can also be declared using xref:css-customization.adoc#rules[rules] in the Visual Embed SDK code. This is useful for real-time testing, particularly in the Visual Embed SDK playground. Note the format for encoding CSS rules into the JavaScript object format used by for rules. +An example of using direct selectors in a file is available in the link:https://github.com/thoughtspot/custom-css-demo/blob/main/complete.css[complete.css sample, target=_blank] on the ThoughtSpot GitHub repository. + +You can also declare direct selectors using the xref:css-customization.adoc#_css_rules_using_selectors[rules] property in the Visual Embed SDK configuration. This is useful for real-time testing, especially in the Visual Embed SDK playground. Note the required format for encoding CSS rules as JavaScript objects. + == Additional resources diff --git a/modules/ROOT/pages/full-embed.adoc b/modules/ROOT/pages/full-embed.adoc index f9367b677..9bee3e046 100644 --- a/modules/ROOT/pages/full-embed.adoc +++ b/modules/ROOT/pages/full-embed.adoc @@ -6,29 +6,24 @@ :page-pageid: full-embed :page-description: You can embed full ThoughtSpot experience in your application and allow your users to create content for live analytics -The full app embedding allows you to embed the full ThoughtSpot application or the individual application pages in your app. +Full app embedding allows you to embed the entire ThoughtSpot application or individual application pages in your app. -Full app embedding gives you all the features of ThoughtSpot, with the ability to use additional features and customization from the Visual Embed SDK, such as custom actions and CSS styling rules. +Full app embedding provides access to all core ThoughtSpot features, along with additional customization options through the Visual Embed SDK, including custom actions and CSS styling rules. -The basic layout and feature set of the various pages of the ThoughtSpot application in full app embedding is relatively fixed, so if you need more control, use the xref:embed-search.adoc[SearchEmbed] and xref:embed-pinboard.adoc[LiveboardEmbed] components. You can xref:page-navigation.adoc[control/customize navigation] within your web application using the full app or other embed components. +The layout and feature set of the various pages in full app embedding are relatively fixed. If you require more granular control, use the embed components, such as xref:embed-pinboard.adoc[LiveboardEmbed], xref:embed-search.adoc[SearchEmbed], or xref:embed-spotter.adoc[SpotterEmbed] in the SDK. You can xref:page-navigation.adoc[control or customize navigation] within your web application using either full app or other embed components. [IMPORTANT] ==== -* We do not recommend mixing full app embedding with the xref:embed-search.adoc[SearchEmbed] and xref:embed-pinboard.adoc[LiveboardEmbed] components. +* ThoughtSpot does not recommend mixing full application embedding with xref:embed-search.adoc[SearchEmbed] and xref:embed-pinboard.adoc[LiveboardEmbed] components. * The *Develop* page and *Analyst Studio* option are not available in full application embed. * To enable Spotter in the full application embed, set the home page search bar mode to `aiAnswer`. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding]. ==== -== UI experience +== Before you embed +Before embedding the full ThoughtSpot application: -The ThoughtSpot UI and navigation experience is available in two modes: - -* Classic experience (default) -* New navigation and homepage experience [earlyAccess eaBackground]#Early Access# -+ -By default, the New navigation and homepage experience is turned off on ThoughtSpot embedding applications. To enable the new experience for your embedding application users, set `modularHomeExperience` to `true`. -+ -For more information about new navigation and homepage experience and customization controls for full application embedding, see xref:full-app-customize.adoc[full app customization]. +* Review ThoughtSpot UI, xref:full-app-customize.adoc[different experience modes and customization options] available in the SDK. +* Determine the xref:customize-nav-full-embed.adoc[navigation elements] and xref:customize-homepage-full-embed.adoc[modules] to enable or customize in the embed view == Import the AppEmbed package Import the AppEmbed SDK library to your application environment: @@ -57,7 +52,8 @@ from '@thoughtspot/visual-embed-sdk'; AuthType, init, prefetch, - EmbedEvent + EmbedEvent, + HostEvent } from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; ---- @@ -68,7 +64,7 @@ xref:getting-started.adoc#initSdk[Initialize the SDK] and define authentication == Create an instance of the AppEmbed object -Create an instance of the AppEmbed object and pass parameters to set a page view. +Create an instance of the `AppEmbed` object and specify the initial page to display when the embedded component loads in your app. [source,javascript] ---- @@ -115,13 +111,23 @@ https://{ThoughtSpot-Host}/?embedApp=true&primaryNavHidden=true&profileAndHelpIn ---- //// -The `AppEmbed` component allows you to embed a specific application page or the entire application experience. If you are embedding full application, you can xref:full-app-customize.adoc#_choose_the_page_to_load[choose to show a specific page when embedded content loads] using the `pageId` or `path` property. The `AppEmbed` component also provides several customization controls to customize full application experience in an embedded view. For more information, see the following pages: +The `AppEmbed` component allows you to embed a specific application page or the entire application experience. If you are embedding full experience, you can xref:set-default-page.adoc[set a specific application page as the default page when the embedded content loads] using the `pageId` or `path` property. -* xref:full-app-customize.adoc[Customize full application embedding] + -* xref:AppEmbed.adoc[AppEmbed] + -* xref:AppViewConfig.adoc[AppViewConfig] + -* xref:Action.adoc[Actions] +== Customize your embed view (Optional) +The `xref:AppViewConfig.adoc[AppViewConfig]` object in the `AppEmbed` component various attributes and properties to xref:css-customization.adoc[the look and feel of the embedded app], xref:embed-actions.adoc[control the visibility of menu actions] and features, and xref:embed-events.adoc[manage interactions between the host and embedded app]. + +By default, ThoughtSpot application loads in the classic (V1) experience mode. If the V3 navigation and modular home page feature is enabled on your instance, you can choose to enable this experience for your embedding application users and customize the UI experience as per your needs. + +For more information, see the following pages: + +* xref:full-app-customize.adoc[Customize full application embedding] +* xref:customize-homepage-full-embed.adoc[Customize home page experience] +* xref:customize-nav-full-embed.adoc[Customize navigation experience] +* xref:AppViewConfig.adoc[AppViewConfig] +* xref:Action.adoc[Actions] +* xref:EmbedEvent.adoc[Embed events] +* xref:HostEvent.adoc[Host events] //// @@ -273,7 +279,127 @@ For more information about events, see the following pages: * xref:EmbedEvent.adoc[EmbedEvent] * xref:embed-events.adoc[Events and app integration] -== Test your embedding +== Code sample + +The following example shows the minimal code required to embed full ThoughtSpot experience in an app. + +[source,JavaScript] +---- +import { + AppEmbed, + Page, + AuthType, + init +} from '@thoughtspot/visual-embed-sdk'; +// Alternatively, you can use the ES6 import from CDN as shown below: +// import { AppEmbed, AuthType, init } from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.es.js'; + +// Initialize th Visual Embed SDK with the host and authentication type +init({ + thoughtSpotHost: '', // Replace with your ThoughtSpot host + authType: AuthType.None, // Use 'None' if authentication is handled outside the SDK +}); + +// Create an AppEmbed instance to embed the full ThoughtSpot application +const appEmbed = new AppEmbed( + document.getElementById('ts-embed'), // The DOM element where the app will be embedded + { + frameParams: { + width: '100%', // Set the iframe width to 100% + height: '100%', // Set the iframe height to 100% + }, + pageId: Page.Liveboards, // Set the initial page to the Data page + } +); + +// Render the embedded ThoughtSpot application in the specified DOM element +appEmbed.render(); +---- + +For customizing specific components, you can include the xref:AppViewConfig.adoc[View configuration properties] available for full application embedding in the SDK. + +You may also want to import the xref:https://developers.thoughtspot.com/docs/Enumeration[Enumeration] objects and use the enums that represent values for the configuration properties in your code. For example, to show, hide, or disable specific menu actions, you may want to import the `Action` object and include the enumerated members representing specific menu actions in the `visibleActions`, `disabledActions`, or `hiddenActions` array. + +The following code sample shows how to initialize the SDK with a trusted authentication token and customize styles, menu actions, and interactions between the host and embedded app: + +[source,JavaScript] +---- +import { + AppEmbed, + Page, + AuthType, + init, + EmbedEvent, + Action, + HostEvent +} from '@thoughtspot/visual-embed-sdk'; + +// Initialize the SDK +init({ + thoughtSpotHost: '', // Replace with your ThoughtSpot instance URL + authType: AuthType.TrustedAuthTokenCookieless, // Cookieless trusted authentication + // getAuthToken should return a Promise that resolves to a valid trusted authentication token from your backend + getAuthToken: () => { + return fetch('https://your-backend.app/ts-token') // Replace with your backend token fetching endpoint + .then((response) => response.json()) + .then((data) => data.token); + } +}); + +// Create the AppEmbed instance for classic (V1) experience with customizations +const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { + pageId: Page.Home, // Set the initial page to Home + showPrimaryNavbar: true, // Show the top navigation bar + disableProfileAndHelp: true, // Hide profile and help icons + frameParams: { + width: '100%', + height: '100%' + }, // Set iframe size + // Basic style customization for layout, navbar, and buttons + customizations: { + customCSS: { + variables: { + "--ts-var-root-background": "#F5F5F5", + "--ts-var-root-color": "#47515F", + "--ts-var-button--primary-background": "#FFA97E", + "--ts-var-button--primary--hover-background": "#FFCCB3", + "--ts-var-button--primary--active-background": "#FF8142", + "--ts-var-button--primary-color": "#FFFFFF", + "--ts-var-button--secondary-background": "#ABC7F9", + "--ts-var-button--secondary--hover-background": "#71A1F4", + "--ts-var-button--secondary--active-background": "#ABC7F9", + "--ts-var-nav-background": "#2359B6", + "--ts-var-search-data-button-background": "#ABC7F9", + "--ts-var-search-data-button-font-color": "#FFFFFF" + }, + }, + // Hide actions from menus + hiddenActions: [Action.Present, Action.SyncToOtherApps], + // Disable action in menus + disabledActions: [Action.ShowUnderlyingData], + disabledActionReason: "Contact your administrator to enable this feature." + }); + + // Listen for route (page/path) changes in the embedded app + appEmbed.on(EmbedEvent.RouteChange, (response) => { + console.log('Route changed to:', response.data.currentPath); + }); + // Listen for dialog open events in the embedded app + appEmbed.on(EmbedEvent.DialogOpen, (payload) => { + console.log('Dialog opened:', payload); + }); + + // Listen for dialog close events in the embedded app + appEmbed.on(EmbedEvent.DialogClose, (payload) => { + console.log('Dialog closed:', payload); + }); + // Render the embedded ThoughtSpot app + appEmbed.render(); +---- + +For code samples and additional information about the configuration options available for different UI experience modes, see xref:full-app-customize.adoc[Customize full application embed]. + +== Test your embed . Load the embedded object in your app. If the embedding is successful, you will see the ThoughtSpot application page. + @@ -283,10 +409,15 @@ For more information about events, see the following pages: image::./images/appEmbed.png[Full application embed] + -*New home page experience* +*V3 experience* [.bordered] -image::./images/appEmbed_new.png[Full application embed] +[.widthAuto] +image::./images/new-nav3.png[New home page] ++ +*V2 experience* +[.bordered] +image::./images/appEmbed_new.png[Full application embed] . Explore the charts and tables, and verify if objects render and show the desired data. diff --git a/modules/ROOT/pages/get-started-tse.adoc b/modules/ROOT/pages/get-started-tse.adoc index 6ae6aa288..f807366c6 100644 --- a/modules/ROOT/pages/get-started-tse.adoc +++ b/modules/ROOT/pages/get-started-tse.adoc @@ -38,7 +38,6 @@ The following figure illustrates these options and the steps required to get sta image:./images/license-workflow.png[ThoughtSpot Embed getting started workflow,link="./doc-images/images/license-workflow.png", width=auto] //// - [#live-playground] == Try out the embedding workflows, SDK, and APIs diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc index 68af996cc..803f62516 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/getting-started.adoc @@ -14,9 +14,7 @@ Based on your embedding requirements and integration setup, you can use one of t ThoughtSpot Visual Embed SDK offers a JavaScript library that allows you to embed ThoughtSpot components in web pages. This section helps you get started with embedding a ThoughtSpot component in your app. * xref:embed-without-sdk.adoc[iFrame embedding without SDK] -The following sections describe how to embed a ThoughtSpot component using Visual Embed SDK. - -There is also a xref:tse-fundamentals-intro.adoc[hands-on embedding fundamentals tutorial] available. +The following sections describe how to embed a ThoughtSpot component using Visual Embed SDK. For additional guidance refer to the xref:tse-fundamentals-intro.adoc[Embedding fundamentals tutorial]. == Before you begin @@ -41,27 +39,31 @@ For more information, see xref:user-roles.adoc[Developer access]. The Visual Embed SDK is available for installation as a Node Package Manager (NPM) package. The latest version of the Visual Embed SDK is available at link:https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk[https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk, window=_blank]. +//// To get started with embedding, install the SDK: [source,console] ---- npm install @thoughtspot/visual-embed-sdk ---- +//// -=== Import embed package +=== Import the embed package +The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. Import one of the following modules into your app: * **LiveboardEmbed** + -Use the **LiveboardEmbed** component to xref:embed-a-viz.adoc[embed a single visualization] or a full Liveboard with multiple visualizations: +To xref:embed-a-viz.adoc[embed a single visualization] or a xref:embed-pinboard.adoc[full Liveboard with multiple visualizations]. -+ -++++ -Embed a Liveboard -++++ +* **SpotterEmbed** + +To embed xref:embed-ai-analytics.adoc[embed Spotter AI search and analytics]. + + +//// * **SageEmbed** + Use the `SageEmbed` package to embed Natural Language Search interface. @@ -69,29 +71,15 @@ Use the `SageEmbed` package to embed Natural Language Search interface. ++++ Embed Natural Language Search ++++ - +//// * **AppEmbed** + -Use the `AppEmbed` library to embed full ThoughtSpot application in your app. - -+ -++++ -Embed full ThoughtSpot application -++++ +To xref:full-embed.adoc[embed full ThoughtSpot application] experience or specific application pages. * **SearchEmbed** + -Use the `SearchEmbed` package to embed the ThoughtSpot search page with a pre-selected data source. -+ -++++ -Embed Search page -++++ +To xref:embed-search.adoc[embed ThoughtSpot Search page] with a pre-selected data source. * **SearchBarEmbed** + -Use the `SearchBarEmbed` component to embed only the ThoughtSpot Search bar and data panel. - -+ -++++ -Embed Search bar -++++ +To xref:embed-searchbar.adoc[embed only the ThoughtSpot Search bar] and data panel. ==== Example @@ -183,30 +171,38 @@ import { HostEvent } from '@thoughtspot/visual-embed-sdk'; +// Create a new LiveboardEmbed instance, targeting the DOM element with id 'container'. + const lb = new LiveboardEmbed('#container', { + // Set the frame size to 100% width and height frameParams: { width: '100%', height: '100%', }, - liveboardId: '<%=liveboardGUID%>', - runtimeFilters: [], + liveboardId: '<%=liveboardGUID%>', // ID of the Liveboard + runtimeFilters: [{ + columnName: 'Color', + operator: RuntimeFilterOp.EQ, + values: ['red'], + }, ], }); -// [Optional]: Register event listeners. + +// [Optional]: Register an event listener for the LiveboardRendered event. +// This allows you to execute custom logic when the Liveboard has finished rendering. lb.on(EmbedEvent.LiveboardRendered, (e) => { /* handler */ }); -// Do not forget to call render. +// Render the embedded Liveboard inside the specified container. +// This step is required to display the Liveboard in your application. lb.render(); -// [Optional]: Trigger events on the lb -lb.trigger(HostEvent.UpdateRuntimeFilters, [ - { - columnName: 'col1', - operator: RuntimeFilterOp.EQ, - values: ['val1'], - }, -]); +// Programmatically trigger a HostEvent to update runtime filters on the embedded Liveboard. +lb.trigger(HostEvent.UpdateRuntimeFilters, [{ + columnName: 'Color', + operator: RuntimeFilterOp.EQ, + values: ['amber'], +}, ]); ---- `#container` is a selector for the DOM node which the code assumes is already attached to DOM. The SDK will render the ThoughtSpot component inside this container element. @@ -216,24 +212,32 @@ ThoughtSpot provides React components for embedding Search, Liveboard, and the f [source,TypeScript] ---- +// Import the LiveboardEmbed React component from the ThoughtSpot Visual Embed SDK import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk/react'; const App = () => { + // Create a ref to interact with the embedded Liveboard instance const embedRef = useEmbedRef(); + + // Event handler called when the Liveboard has finished rendering const onLiveboardRendered = () => { + // Trigger a HostEvent to update runtime filters on the embedded Liveboard + // This filter sets the 'col1' column to only show rows where the value is 'val1' embedRef.current.trigger(HostEvent.UpdateRuntimeFilters, [ { - columnName: 'col1', + columnName: 'Color', operator: RuntimeFilterOp.EQ, - values: ['val1'], + values: ['amber'], }, ]); }; + + // Render the LiveboardEmbed component with the specified Liveboard ID and event handler return ( ); }; diff --git a/modules/ROOT/pages/lazy-loading-fullheight.adoc b/modules/ROOT/pages/lazy-loading-fullheight.adoc index c25954828..0d09fafb2 100644 --- a/modules/ROOT/pages/lazy-loading-fullheight.adoc +++ b/modules/ROOT/pages/lazy-loading-fullheight.adoc @@ -18,15 +18,17 @@ The height of the Liveboard container dynamically adjusts to match the height of Only the visualizations currently visible in the viewport are loaded initially. Additional visualizations are fetched incrementally as users scroll the page. This reduces initial load time, minimizes unnecessary data API calls, and provides a smoother, faster experience for large dashboards. By default, the `fullHeight` parameter is set to `false`. -=== Full height with default height setting -In addition to `fullHeight`, the SDK also provides the `defaultHeight` parameter. The value defined for the `defaultHeight` attribute is applied only when `fullHeight` is set to true. When `fullHeight` is true, the embedded container resizes to fit the Liveboard content, and `defaultHeight` sets the minimum height (in pixels) for this container. This ensures that even if the Liveboard is empty or has little content, the container maintains at least the specified minimum height. If `fullHeight` is set to `false`, the `defaultHeight` attribute has no effect. +=== Full height with minimum height setting +In addition to `fullHeight`, the SDK also provides the `minimumHeight` parameter. The value defined for the `minimumHeight` attribute is applied only when `fullHeight` is set to `true`. +If `fullHeight` is `true`, the embedded container resizes according to the Liveboard content . and `minimumHeight` sets the minimum height (in pixels) for this container. +This ensures that even if the Liveboard is empty or has little content, the container maintains at least the specified minimum height. If `fullHeight` is set to `false`, the `minimumHeight` attribute is not applied. [source,JavaScript] ---- const embed = new LiveboardEmbed('#embed', { // other liveboard view config fullHeight: true, - defaultHeight: 600, + minimumHeight: 600, }); ---- diff --git a/modules/ROOT/pages/mobile-embed-android.adoc b/modules/ROOT/pages/mobile-embed-android.adoc index 48737c4ad..153fbc0c3 100644 --- a/modules/ROOT/pages/mobile-embed-android.adoc +++ b/modules/ROOT/pages/mobile-embed-android.adoc @@ -22,7 +22,7 @@ To download the Android Embed SDK from Maven Central to your project and install [source,kotlin] ---- -implementation("io.github.thoughtspot:android-embed-sdk:0.0.1-beta") +implementation("io.github.thoughtspot:android-embed-sdk:1.0.0") ---- * `implementation` + @@ -32,7 +32,7 @@ GitHub reference ID * `android-embed-sdk` + The GitHub repository of the Android Embed SDK package. * `Tag` + -Indicates the version of the SDK to use. Replace this with a specific release tag from the GitHub repository. For example,0.0.1-beta. +Indicates the version of the SDK to use. Replace this with a specific release tag from the GitHub repository. For example,1.0.0. The SDK may require network access to communicate with your ThoughtSpot instance. Ensure your app’s `AndroidManifest.xml` includes the following: diff --git a/modules/ROOT/pages/mobile-embed.adoc b/modules/ROOT/pages/mobile-embed.adoc index fe1dba115..dfcdfa3b1 100644 --- a/modules/ROOT/pages/mobile-embed.adoc +++ b/modules/ROOT/pages/mobile-embed.adoc @@ -8,13 +8,13 @@ ThoughtSpot provides the following SDK libraries to help developers embed ThoughtSpot in their mobile apps: -* xref:mobilesdk-quick-start.adoc[React Native Mobile Embed SDK] [beta betaBackground]^Beta^ + +* xref:mobilesdk-quick-start.adoc[React Native Mobile Embed SDK] + Allows developers to embed ThoughtSpot content in *iOS* and *Android* mobile apps using React Native resources and a single codebase. -* xref:mobile-embed-qs-flutter.adoc[Flutter Embed SDK] [beta betaBackground]^Beta^ + +* xref:mobile-embed-qs-flutter.adoc[Flutter Embed SDK] + Allows embedding ThoughtSpot components in Flutter apps. -* xref:mobile-embed-qs-swift.adoc[Swift Embed SDK] [beta betaBackground]^Beta^ + +* xref:mobile-embed-qs-swift.adoc[Swift Embed SDK] + Allows developers to embed ThoughtSpot content in an iOS native app. -* xref:mobile-embed-android.adoc[Android Embed SDK] [beta betaBackground]^Beta^ + +* xref:mobile-embed-android.adoc[Android Embed SDK] + Allows developers to embed ThoughtSpot content in an Android native app. == Authentication and security settings diff --git a/modules/ROOT/pages/mobile-sdk-changelog.adoc b/modules/ROOT/pages/mobile-sdk-changelog.adoc index 85828986a..c6175c068 100644 --- a/modules/ROOT/pages/mobile-sdk-changelog.adoc +++ b/modules/ROOT/pages/mobile-sdk-changelog.adoc @@ -10,6 +10,10 @@ This changelog lists only the changes introduced in the Mobile Embed SDK. For in == React Native Embed SDK +=== Version 1.0.0, December 2025 + +React Native Embed SDK is Generally Available (GA) with version 1.0.0. + === Version 0.0.2, April 2025 The React Native Embed SDK v0.0.2 [beta betaBackground]^Beta^ provides client libraries to embed a ThoughtSpot Liveboard in native mobile apps for both Android and iOS, using JavaScript and React. @@ -20,6 +24,10 @@ For more information, see xref:mobilesdk-quick-start.adoc[Embed ThoughtSpot usin == Flutter Embed SDK +=== Version 1.0.0, December 2025 + +Flutter Embed SDK is Generally Available (GA) with version 1.0.0. + === Version 0.0.2, June 2025 The Flutter Embed SDK v0.0.1 [beta betaBackground]^Beta^ provides client libraries to embed a ThoughtSpot Liveboard in a Flutter app. @@ -28,6 +36,10 @@ For information about how to install and use the SDK, see xref:mobile-embed-qs-f == Swift Embed SDK +=== Version 1.0.0, December 2025 + +Swift Embed SDK is Generally Available (GA) with version 1.0.0. + === Version 0.0.1, June 2025 The Swift Embed SDK v0.0.1 [beta betaBackground]^Beta^ provides client libraries to embed a ThoughtSpot Liveboard in an iOS native app. @@ -36,6 +48,10 @@ For information about how to install and use the SDK, see xref:mobile-embed-qs-s == Android Embed SDK +=== Version 1.0.0, December 2025 + +Swift Embed SDK is Generally Available (GA) with version 1.0.0. + === Version 0.0.1, June 2025 The Android Embed SDK v0.0.1 [beta betaBackground]^Beta^ provides client libraries to embed a ThoughtSpot Liveboard in an Android native app. diff --git a/modules/ROOT/pages/mobilesdk-quick-start.adoc b/modules/ROOT/pages/mobilesdk-quick-start.adoc index 668d5aee1..68508c237 100644 --- a/modules/ROOT/pages/mobilesdk-quick-start.adoc +++ b/modules/ROOT/pages/mobilesdk-quick-start.adoc @@ -6,7 +6,7 @@ :page-pageid: embed-ts-mobile-react-native :page-description: THe React Native embed SDK allows you to embed ThoughtSpot in your Andriod and iOS mobile apps -ThoughtSpot's React Native Mobile Embed SDK [beta betaBackground]^Beta^ enables developers to embed ThoughtSpot Analytics in their mobile apps. This SDK is designed for the React Native framework to allow developers to build their mobile apps that operate on *iOS* and *Android* platforms, using native resources and a single codebase. +ThoughtSpot's React Native Mobile Embed SDK enables developers to embed ThoughtSpot Analytics in their mobile apps. This SDK is designed for the React Native framework to allow developers to build their mobile apps that operate on *iOS* and *Android* platforms, using native resources and a single codebase. In its initial release, the React Native Embed SDK supports embedding a Liveboard component and customizing the embed view within the mobile app. @@ -46,17 +46,6 @@ npm install @thoughtspot/react-native-embed-sdk After you import, you can define the ThoughtSpot host URL from which you want to embed a Liveboard, authentication type and attributes, and Liveboard ID. -==== File structure in the Expo go sandbox - -A mobile embed project in link:https://snack.expo.dev/@git/github.com/thoughtspot/developer-examples:mobile/react-native-embed-sdk[Expo code sandbox, window=_blank] typically includes the following files: - -* `Auth.ts` - Includes the code required to get authentication token from ThoughtSpot via REST API SDK. -* `App.tsx` - Includes the code for expo app setup. -* `Home.tsx` - Includes the code for the main screen and the form to populate embed view configuration, the `init` function with the `tsHost` and `username`, Liveboard ID, and custom style specification. -* `LiveboardView.tsx` - Defines the interface configuration properties and event interaction settings for the Liveboard embed view. - -You can use similar files in your project setup or an index file for the ThoughtSpot mobile embed code. - === Initialize the SDK and set up authentication Define the following parameters: @@ -69,9 +58,17 @@ Authentication type. In the current version, mobile embedding supports only the [source,TypeScript] ---- init({ - thoughtSpotHost: 'ts-host-url', // Replace with your ThoughtSpot host URL - authType: AuthType.TrustedAuthTokenCookieless, - getAuthToken: async () => "full-auth-token" + thoughtSpotHost: 'ts-host-url', // Replace with your ThoughtSpot host URL + authType: AuthType.TrustedAuthTokenCookieless, + // Callback to fetch a login token from your backend token service + getAuthToken: () => { + // Call your backend endpoint to get a ThoughtSpot login token + return fetch('https://my-backend.app/ts-token') // Replace with your backend token endpoint + .then((response) => response.json()) // Parse JSON response + .then((data) => data.token); // Return the token value + } + // You can also use this code for testing with a custom time token: + // getAuthToken: async () => "full-auth-token" // Replace "full-auth-token" with logic to fetch the token from your backend. For more information, see https://developers.thoughtspot.com/docs/trusted-auth-sdk#_code_examples }); ---- @@ -90,33 +87,14 @@ const TsApp = () => { }; ---- -=== Build your app and preview the embedded content - -* Build your app: -+ -[,bash] ----- -$ npm run build ----- - -* If you are using an Expo project: -+ -. Build your project locally -+ -[,bash] ----- -expo start ----- -. Scan the QR code with the *Expo Go* app to see the app with the embedded content. - -== Customize your embed +=== Customize your embed Just like the Visual Embed SDK for web application embed, the Mobile Embed SDK provides the following customization options: * Control the xref:mobilesdk-quick-start.adoc#_customize_menu_actions[visibility of menu actions in the embedded view] * xref:mobilesdk-quick-start.adoc#_customize_app_interactions[Customize app interactions and workflows] using events. * xref:mobilesdk-quick-start.adoc#_customize_styles[Customize the styles and UI layout] of the embedded view -=== Customize menu actions +==== Customize menu actions By default, the SDK includes a xref:mobile-embed.adoc#actionsMobileEmbed[set of menu actions] in the embedded Liveboard view. @@ -149,7 +127,7 @@ disabledActionReason: "Contact your administrator to enable this feature", //visibleActions: [], /* Do not use if `hiddenActions` is enabled */ ---- -=== Customize app interactions +==== Customize app interactions To customize app interactions and enable custom workflows with xref:embed-events.adoc[Embed and Host events]. The following code shows how to register the `authInit` and `load` embed event and handle response to these events: @@ -230,7 +208,7 @@ const LiveboardEmbedView = () => { }; ---- -=== Customize styles +==== Customize styles You can use ThoughtSpot's xref:css-customization.adoc[CSS customization framework] to customize the text strings, icons, styles and the UI layout of the embedded view. [source,TypeScript] @@ -268,8 +246,26 @@ init({ }); ---- -=== Code samples +=== Build your app and preview the embedded content + +Build your app: + +[,bash] +---- +$ npm run build +---- + +If you are using an Expo project: + +. Build your project locally ++ +[,bash] +---- +expo start +---- +. Scan the QR code with the *Expo Go* app to see the app with the embedded content. +=== Code samples The following example shows the minimum code required to embed a Liveboard successfully in a mobile app: [source,TypeScript] @@ -282,8 +278,8 @@ import { AuthType, init, LiveboardEmbed } from '@thoughtspot/react-native-embed- // Initialize the ThoughtSpot SDK init({ thoughtSpotHost: 'ts-host-url', // Replace with your ThoughtSpot host URL - authType: AuthType.TrustedAuthTokenCookieless, //Using cookieless trusted token authentication - getAuthToken: async () => "full-auth-token", //fetch a valid authentication token + authType: AuthType.TrustedAuthTokenCookieless, //Cookieless trusted token authentication + getAuthToken: async () => "full-auth-token", //fetch a valid authentication token. See }); // Add Liveboard component @@ -390,7 +386,8 @@ const styles = StyleSheet.create({ export default TsApp; ---- -== Test your app + +=== Test your app * Connect your device to the app, authenticate, and load the Liveboard in your mobile app. + @@ -413,10 +410,21 @@ Additionally, you can add a listener for `EmbedEvent.Error` and verify the logs. * In case of rendering issues, adjust the frame size constraints and rerun your app. * Check if your custom CSS specifications are applied correctly. + == Known limitations For information about supported features and known limitations, see xref:mobile-embed.adoc#_known_limitations[Mobile embed limitations]. +== Expo go sandbox +If you are using Expo Go to develop and test your mobile app, you can use the ThoughtSpot mobile embed project in link:https://snack.expo.dev/@git/github.com/thoughtspot/developer-examples:mobile/react-native-embed-sdk[Expo code sandbox, window=_blank]. This project includes the following files: + +* `Auth.ts` - Includes the code required to get authentication token from ThoughtSpot via REST API SDK. +* `App.tsx` - Includes the code for expo app setup. +* `Home.tsx` - Includes the code for the main screen and the form to populate embed view configuration, the `init` function with the `tsHost` and `username`, Liveboard ID, and custom style specification. +* `LiveboardView.tsx` - Defines the interface configuration properties and event interaction settings for the Liveboard embed view. + +You can use similar files in your project setup or an index file for the ThoughtSpot mobile embed code. + == Additional resources * link:https://github.com/thoughtspot/react-native-mobile-sdk[React Native Mobile Embed SDK GitHub Repository, window=_blank] diff --git a/modules/ROOT/pages/onboarding-guide.adoc b/modules/ROOT/pages/onboarding-guide.adoc index e350fab3a..42510ac4f 100644 --- a/modules/ROOT/pages/onboarding-guide.adoc +++ b/modules/ROOT/pages/onboarding-guide.adoc @@ -42,31 +42,42 @@ image::./images/lb-image.png[Liveboard] If you want to embed other ThoughtSpot components and explore the additional capabilities of the Visual Embed SDK, see the xref:getting-started.adoc[embedding components guide] or the resources listed in the xref:onboarding-guide.adoc#addResources[Explore more] section. -=== Step 1: Install the Visual Embed SDK +=== Step 1: Import the Visual Embed SDK The latest version of the Visual Embed SDK is available at link:https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk[https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk, window=_blank]. -[source,console] ----- -npm install @thoughtspot/visual-embed-sdk ----- - -=== Step 2: Import the SDK into your project +The Visual Embed SDK is available as both ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. -Import the SDK package into your application environment. Let's import the `LiveboardEmbed` SDK package to embed a Liveboard. +In this example, we'll import the `LiveboardEmbed` SDK package to embed a Liveboard. +**npm** [source,JavaScript] ---- import { LiveboardEmbed, AuthType, init, -} from '@thoughtspot/visual-embed-sdk'; + prefetch, + EmbedEvent +} +from '@thoughtspot/visual-embed-sdk'; ---- +**ES6** +[source,JavaScript] +---- +