diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 95e141cfb..3435deff8 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -263,11 +263,11 @@ The SDK includes the following new features and enhancements in Liveboard embedd `liveboardGutter` embed config property:: A new `liveboardGutter` property is available on `LiveboardViewConfig`. Use this property to set the gutter spacing between tiles on an embedded Liveboard. -For more information, see xref:embed-pinboard.adoc#liveboard-gutter[Set Liveboard tile gutter] +For more information, see xref:customize-liveboard-layout.adoc#liveboard-gutter[Set Liveboard tile gutter] 12-column layout for Liveboard tile positioning:: A new embed config property is available on `LiveboardViewConfig` to always use a 12-column grid layout for Liveboard tile positioning. When enabled, tile placement and sizing follow a fixed 12-column grid regardless of the Liveboard's default layout settings. -For more information, see xref:embed-pinboard.adoc#force-12col-layout[12-column layout in embedded Liveboards] +For more information, see xref:customize-liveboard-layout.adoc#force-12col-layout[12-column layout in embedded Liveboards] New host events for the Liveboard edit page:: * `HostEvent.OpenAddFilterModal` + @@ -316,7 +316,7 @@ Enables compact header layout in embedded Liveboards. * `coverAndFilterOptionInPDF` + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * `isLiveboardMasterpiecesEnabled` + -Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. +Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. * `isEnhancedFilterInteractivityEnabled` + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. @@ -387,7 +387,7 @@ Trigger a manual cache refresh from the host application. * `Action.RefreshLiveboardBrowserCache` + Action ID to show or hide the cache refresh button. -For more information, see xref:embed-pinboard.adoc#liveboard-data-cache[Enable Liveboard refresh]. +For more information, see xref:liveboard-data-downloads.adoc#liveboard-data-cache[Enable Liveboard refresh]. |[tag greenBackground]#NEW# a| [discrete] @@ -1731,7 +1731,7 @@ For more information, see xref:prefetch-and-cache.adoc[Prefetch static resources |[tag greenBackground]#NEW#| For embedded instances with the new Liveboard experience, the Visual Embed SDK provides the `activeTabId` attribute, using which you can set a Liveboard tab as an active tab. -For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. +For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]. |[tag greenBackground]#NEW# a|The new version of the SDK supports firing events for Liveboard menu actions from the host application. The SDK introduces the following host event enumeration members for Liveboard objects: diff --git a/modules/ROOT/pages/api-user-management.adoc b/modules/ROOT/pages/api-user-management.adoc index 15312afc7..acc6c4697 100644 --- a/modules/ROOT/pages/api-user-management.adoc +++ b/modules/ROOT/pages/api-user-management.adoc @@ -10,7 +10,7 @@ To provide access to ThoughtSpot content or define privileges, you must add user == User creation and update -You can create users and update user profiles using xref:rest-api-reference.adoc#_user_management[REST API v1] or xref:rest-api-v2-reference.adoc#_users[v2 endpoints]. +You can create users and update user profiles using the xref:rest-api-v2-reference.adoc#_users[REST API v2 user endpoints]. While you can delete users, it is preferable to deactivate a user, which maintains the user's references within the system. @@ -18,12 +18,35 @@ When configuring xref:configure-saml.adoc[SAML SSO] in ThoughtSpot UI, you can s By default, ThoughtSpot sends e-mail messages to a new user and enables onboarding workflows when they log in for the first time, even when you are embedding ThoughtSpot content. To alter this behavior at a system-wide level, you need to xref:customize-email-settings.adoc[Customize the onboarding settings]. The user update API also allows setting onboarding experience values for an individual user. If you need to modify the default behavior beyond the available UI options, contact your ThoughtSpot team. +To specify whether an activation email is sent to a new user, set the `trigger_activation_email` parameter in the `POST /api/rest/2.0/users/create` request. [NOTE] ==== ThoughtSpot supports local management of users. For initial development and testing purposes, you can create users in ThoughtSpot and manage their profiles locally. However, in large production environments, avoid creating local user profiles to reduce administration overhead. ==== +=== Required privileges +To create, edit, or delete users, assign users to groups, transfer objects from one user to another, or activate, deactivate, or log out users, you need administrator privileges (`ADMINISTRATION`). + +If Role-Based Access Control (RBAC) is enabled on your instance, the `USER_ADMINISTRATION` (*Can manage users*) privilege is required. On instances with Orgs, this privilege allows managing users only within the Org context of the API request. For more information, see xref:roles.adoc[Role-based access control]. + +=== User attributes +Note the following points about user attributes: + +* *Username*: The username must be unique. An API request to create a user with a username that already exists returns an error. +* *Account type*: The `account_type` attribute indicates how the user was created and how the user authenticates. Valid values are: +** `LOCAL_USER`: A user created and authenticated locally in ThoughtSpot. This is the default account type. +** `LDAP_USER`: A user imported from an LDAP server. +** `SAML_USER`: A user authenticated through SAML SSO. +** `OIDC_USER`: A user authenticated through OpenID Connect (OIDC). +** `REMOTE_USER`: A user authenticated by an external system. ++ +When users are imported from an external server, such as an LDAP server or an IdP, ThoughtSpot assigns the account type automatically. For example, a user imported from an LDAP server is added as `LDAP_USER`. +* *Visibility*: The `visibility` attribute determines whether other users can share objects with the user. By default, users are set to `SHARABLE`, which allows other users and groups to share objects with them. To prevent other users from finding the user and sharing objects with them, set `visibility` to `NON_SHARABLE`. In multi-tenant deployments, users are commonly set to `NON_SHARABLE`. + +=== Password reset +After you reset a user's password with the `POST /api/rest/2.0/users/reset-password` endpoint, you can log the user out of their active sessions by using the `POST /api/rest/2.0/users/force-logout` endpoint. The user must then log in again with the new password. + //// === User account status @@ -75,27 +98,22 @@ The common user state transitions include: To check the status of a user account, use one of the following API endpoints: * +++POST /api/rest/2.0/users/search+++ (REST API v2) -* xref:user-api.adoc[GET /tspublic/v1/user/] (REST API v1) To create a user in the `SUSPENDED` state, use one of the following API endpoints: * +++POST /api/rest/2.0/users/create+++ (Rest API v2) -* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1) To update user status from `ACTIVE` or `PENDING` to `SUSPENDED`, or reactivate a `SUSPENDED` user to the ACTIVE or PENDING state, use one of the following API endpoints: * +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) -* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) To deactivate an `ACTIVE` user, use one of these API endpoints: * +++POST /api/rest/2.0/users/deactivate+++ (Rest API v2) -* xref:user-api.adoc#deactivate-user[POST /tspublic/v1/user/inactivate] (Rest API v1) To activate an `INACTIVE` user account, use one of these API endpoints: * +++POST /api/rest/2.0/users/activate+++ (Rest API v2) -* xref:user-api.adoc#activate-user[POST /tspublic/v1/user/activate] (Rest API v1) //// @@ -112,19 +130,17 @@ ThoughtSpot is gradually migrating its users to link:https://docs.thoughtspot.co * The `email` attribute is mandatory when creating a user in ThoughtSpot Okta. ThoughtSpot recommends that users provide a valid email address during user creation. * You must set a password during user creation if you do not want to trigger an activation email. -* The default value for `usertype` will be `OIDC_USER`. +* The default value for `account_type` will be `OIDC_USER`. Administrators can manage the user account status for all users. For IAMv2 users, the API response for the following APIs will also include `SUSPENDED` as a user state: To create a user: -* +++POST /api/rest/2.0/users/create+++ (Rest API v2) -* xref:user-api.adoc#create-user[POST /tspublic/v1/user] (Rest API v1) +* +++POST /api/rest/2.0/users/create+++ To update user details: -* +++POST /api/rest/2.0/users/{user_identifier}/update+++ (Rest API v2) -* xref:user-api.adoc#update-user[PUT /tspublic/v1/user/{userid}] (Rest API v1) +* +++POST /api/rest/2.0/users/{user_identifier}/update+++ [NOTE] ==== @@ -172,28 +188,52 @@ For more information, see the following pages: == User group creation and update -Groups can be created via xref:rest-api-v2-reference.adoc#_groups[REST API v2] or xref:rest-api-reference.adoc#_groups_and_privileges[REST API v1] API endpoint. +Groups can be created via the xref:rest-api-v2-reference.adoc#_groups[REST API v2 group endpoints]. + +To create, edit, or delete groups, you need administrator privileges. If RBAC is enabled on your instance, the `GROUP_ADMINISTRATION` (*Can manage groups*) privilege is required. To assign Roles to a group or remove Roles from a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges. The xref:api-user-management.adoc#group-privileges[Group privileges] are set directly on groups, either during group creation or via a group update API call. -== User association to groups -You can add users to specific groups when creating a user or group via REST API endpoints. +=== Group hierarchy +ThoughtSpot supports hierarchical groups. You can create a parent group and add other groups to it as sub-groups. For example, you can create a parent group called `Site` and add your tenant groups to it. Sub-groups inherit the privileges of the parent group. -The REST API v1 xref:group-api.adoc#addMembers[group/addmemberships] endpoint allows adding multiple users to multiple groups in a single request. +To add sub-groups to a group or remove sub-groups from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint. Removing a sub-group from a group removes only the association; it does not delete the sub-group from ThoughtSpot. -To get a list of users assigned to a group, you can use the +++POST /api/rest/2.0/groups/search+++ v2 endpoint or the xref:group-api.adoc#get-usersInGroup[/tspublic/v1/group/{groupid}/users] v1 endpoint. +== User association to groups +You can add users to specific groups when creating a user or group via REST API endpoints. When you assign a user to a group, the user inherits the privileges and Roles assigned to that group. + +To add users to an existing group or remove users from it, use the +++POST /api/rest/2.0/groups/{group_identifier}/update+++ endpoint with the `user_identifiers` parameter and the `ADD`, `REMOVE`, or `REPLACE` operation. To update the groups of a single user, use the +++POST /api/rest/2.0/users/{user_identifier}/update+++ endpoint with the `group_identifiers` parameter. -To remove a user from a group, use the update group REST v2 endpoint, or the following REST API v1 endpoints: +Removing a user from a group removes only the group association; it does not delete the user from ThoughtSpot. To delete a user, use the +++POST /api/rest/2.0/users/{user_identifier}/delete+++ endpoint. -* xref:group-api.adoc#delete-user-assoc[POST /tspublic/v1/group/{groupid}/user/{userid}] + -removes a user from a specific group -* xref:group-api.adoc#removeMembers[POST /tspublic/v1/group/removememberships] + -removes a list of users from many groups at once. +To get a list of users assigned to a group, use the +++POST /api/rest/2.0/groups/search+++ endpoint. == Access control (sharing) Access to objects is determined by content *shared* directly to the user or the groups they belong to. It is easier to manage and audit sharing through groups rather than object sharing at the individual user level. -Users can share objects or modify sharing properties through the UI or via an API call to the `POST /api/rest/2.0/security/metadata/share` or xref:security-api.adoc#share-object[/tspublic/v1/security/share] endpoint. +Users can share objects or modify sharing properties through the UI or via an API call to the `POST /api/rest/2.0/security/metadata/share` endpoint. + +Note the following points about sharing objects via REST API: + +* You can share the following types of objects: Liveboards, visualizations, Answers, Models, Views, Connections, and Collections. +* To share an object, you must have edit access to the object. +* The `share_mode` attribute can be set to `READ_ONLY` (*Can view*), `MODIFY` (*Can edit*), or `NO_ACCESS`. Setting `share_mode` to `NO_ACCESS` removes any access previously granted to a user or group. +* To send a share notification to the users and groups with whom the object is shared, set `notify_on_share` to `true`. +* To make a shared Liveboard or Answer discoverable, set `has_lenient_discoverability` to `true`. + +To audit access, use the `POST /api/rest/2.0/security/metadata/fetch-permissions` endpoint to get the users and groups that have access to an object, or the `POST /api/rest/2.0/security/principals/fetch-permissions` endpoint to get the objects a user or group can access. + +For more information and examples, see xref:access-control-sharing.adoc[Access control and sharing]. + +=== Sharing a visualization +Note the following points about sharing a visualization: + +* Sharing a visualization implicitly shares the entire Liveboard with the recipient. +* The object permissions set for a shared visualization also apply to the Liveboard, unless they are overridden by another API request or in the UI. +* If email notifications for object sharing are enabled, the recipient receives a notification with a link to the shared visualization. Although this link opens the shared visualization, the recipient can also access other visualizations on the Liveboard. + +=== Sharing a Collection +Collections support separate permissions for the Collection and for the objects within it. For more information, see xref:collections.adoc#_share_a_collection[Share a Collection]. [#group-privileges] == Group privileges @@ -222,7 +262,7 @@ When creating or updating a group using the REST API v2 endpoints, use the `role [NOTE] ==== -Roles must be available before they can be assigned. Use the xref:roles-api.adoc[Roles API] to create roles programmatically before calling the group create or update endpoints. +Roles must be available before they can be assigned. Use the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fcreate-role[`POST /api/rest/2.0/roles/create`] endpoint to create roles programmatically before calling the group create or update endpoints. ==== For a complete list of available privileges and role categories, see xref:roles.adoc[Role-based access control]. diff --git a/modules/ROOT/pages/audit-logs.adoc b/modules/ROOT/pages/audit-logs.adoc index 8269969f2..bc907d6f5 100644 --- a/modules/ROOT/pages/audit-logs.adoc +++ b/modules/ROOT/pages/audit-logs.adoc @@ -43,10 +43,9 @@ Error Message: Cannot use first or last name in the password.","userId":"e3dc495 Org ID if your ThoughtSpot application instance has Orgs. == Fetch logs via API -To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. You can use any of the following APIs: +To fetch logs via REST API, you need `ADMINISTRATION` (*Can administer ThoughtSpot*) privilege. Use the following API endpoint: -* +++POST /api/rest/2.0/logs/fetch+++ (Recommended) -* xref:logs-api.adoc[GET /tspublic/v1/logs/topics/{topic}] (REST API v1) +* +++POST /api/rest/2.0/logs/fetch+++ On Orgs-enabled clusters, the API fetches security logs for the current Org text. However, the administrator of the primary Org (Org 0) can fetch logs not just for the primary Org, but also for all other Orgs if the `get_all_logs` parameter is set to `true` in the API request. diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 6e72126ab..c310b82e7 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -972,6 +972,17 @@ If the API request is successful, ThoughtSpot returns the following response: |**500**|Failed operation |=== //// +[#switch-org] +== Switching Org context +On ThoughtSpot instances with Orgs, only cluster administrators and users who belong to more than one Org can switch between Orgs. + +For REST API v2 requests, the Org context is determined by the session or token used in the request. To send API requests in a different Org: + +* For cookie-based authentication, log in again by sending a request to the `/api/rest/2.0/auth/session/login` endpoint with the ID or name of the Org in the `org_identifier` attribute. +* For token-based authentication, request a new token with the ID of the Org in the `org_id` attribute, or use a <>. + +To view the Org context of the current session and the Orgs available to the user, send a request to the `/api/rest/2.0/auth/session/user` endpoint and check the `current_org` and `orgs` properties in the API response. For more information, see <<_viewing_session_information,Viewing session information>>. + == Logging out of a session To log out of your current session, send a `POST` request to the `/api/rest/2.0/auth/session/logout` API endpoint. @@ -986,6 +997,8 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' ---- +If you send the logout request as an AJAX call from a browser with cookie-based authentication, include credentials in the request so that the session cookie is sent. For example, set `xhrFields: { withCredentials: true }` in a jQuery AJAX request, or `credentials: 'include'` in a Fetch API request. + === API response If the API request is successful, ThoughtSpot returns a 204 status code and ends the user session. diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index e19841f8a..e9ea19007 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -20,6 +20,9 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-spotter-agent[Embed Spotter without ThoughtSpot UI] * Embed charts and Liveboards ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +*** link:{{navprefix}}/customize-liveboard-layout[Customize Liveboard layout and UI] +*** link:{{navprefix}}/customize-liveboard-filters[Customize Liveboard filters] +*** link:{{navprefix}}/liveboard-data-downloads[Customize data refresh and download options] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index e2dfb49e3..86cc82b95 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -39,6 +39,9 @@ Embed ThoughtSpot in a web app ** link:{{navprefix}}/embed-spotter-agent[Embed Spotter AI without ThoughtSpot UI] * link:{{navprefix}}/embed-liveboard[Embed live analytics] ** link:{{navprefix}}/embed-liveboard[Embed a Liveboard] +*** link:{{navprefix}}/customize-liveboard-layout[Customize Liveboard layout and UI] +*** link:{{navprefix}}/customize-liveboard-filters[Customize Liveboard filters] +*** link:{{navprefix}}/liveboard-data-downloads[Customize data refresh and download options] ** link:{{navprefix}}/spotterViz-agent[SpotterViz AI agent in Liveboards] ** link:{{navprefix}}/embed-a-viz[Embed a visualization] * link:{{navprefix}}/full-embed[Embed full application] diff --git a/modules/ROOT/pages/connections.adoc b/modules/ROOT/pages/connections.adoc index bccbca98d..25b3f67cb 100644 --- a/modules/ROOT/pages/connections.adoc +++ b/modules/ROOT/pages/connections.adoc @@ -73,10 +73,7 @@ ThoughtSpot supports connecting to external data warehouses and using these as d This article describes the procedures for setting and managing data connections through the REST APIs. For information about how to set up a data connection, see link:https://docs.thoughtspot.com/cloud/latest/connections[Data Connections in ThoughtSpot, window=_blank]. == Data Connection APIs -The connection API endpoints allow you to create, edit, delete, export, and query data connections on a ThoughtSpot cluster. For more information about the API endpoints, see the following pages: - -* xref:connections-api.adoc[REST API v1, window=_blank] -* https://developers.thoughtspot.com/docs/rest-apiv2-reference#_connections[REST APIs v2, window=_blank] +The connection API endpoints allow you to create, edit, delete, export, and query data connections on a ThoughtSpot cluster. For more information about the API endpoints, see https://developers.thoughtspot.com/docs/rest-apiv2-reference#_connections[REST API v2 Connection endpoints, window=_blank]. === Required permissions @@ -588,8 +585,7 @@ To create or modify data connections through REST APIs, you need to provide a ma } ] } - ] -} + ], "validate": true } ---- @@ -610,13 +606,25 @@ To create or modify data connections through REST APIs, you need to provide a ma }, "externalDatabases":[ - ] -} + ], "validate": false } ---- +[#export-connection] +== Export a connection +To export a connection, export its TML by using the `POST /api/rest/2.0/metadata/tml/export` endpoint. To include the Tables of the connection in the export, set `export_dependent` to `true`. For more information, see xref:tml-export.adoc[Export TML]. + +[#delete-connection] +== Delete a connection +To delete a connection, use the `POST /api/rest/2.0/connections/{connection_identifier}/delete` endpoint. + +[IMPORTANT] +==== +A connection can be used by multiple Tables, Models, and visualizations. If a connection has dependent objects, remove the dependent objects or their associations before you delete the connection. +==== + == Integrate with dbt ThoughtSpot’s dbt sync allows you to easily provide your existing dbt models and automatically create ThoughtSpot Worksheets, which you can use to search your data. Integration with dbt is certified only for Amazon Redshift, Databricks, Google BigQuery, and Snowflake connections. @@ -634,10 +642,6 @@ To understand about the data catalog tools supported by ThoughtSpot, see the fol * https://docs.thoughtspot.com/cloud/latest/catalog-integration-atlan[Atlan, window=_blank] * https://docs.thoughtspot.com/cloud/latest/catalog-integration-collibra[Collibra, window=_blank] -To understand the metadata API endpoints, see the following pages: - -* https://developers.thoughtspot.com/docs/catalog-and-audit[REST APIs v1, window=_blank] -* https://developers.thoughtspot.com/docs/rest-apiv2-reference#_metadata[REST APIs v2, window=_blank] == Connection Configuration ThoughtSpot supports multiple configurations per data Connection. This feature allows data engineers to define and manage several distinct Connection configurations under a single data Connection object in ThoughtSpot. @@ -658,2361 +662,3 @@ Gets custom calendars for the connection ID specified in the API request. Deletes a custom calendar. * `POST /api/rest/2.0/calendars/{calendar_identifier}/update` + Updates a custom calendar. - - - -//// -[#cre-connection] -== Add a data connection for live query service - -ThoughtSpot supports connecting to external data warehouses and using these as data sources for analytics and visualizations. To create a connection to an external data source and set up a live query service, use the `/tspublic/v1/connection/create` API endpoint. - - -=== Resource URL ----- -POST /tspublic/v1/connection/create ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form parameter|Description -|`name` |__String__. Name of the connection. -|`description` |__String__ A short description of data connection. -|`type`|__String__. Type of the data connection. For example, `RDBMS_SNOWFLAKE`, `RDBMS_REDSHIFT`. - -Valid values for `type` map to the *name* property in the API response returned by the xref:connections-api.adoc#connection-types[/tspublic/v1/connection/types API endpoint]. -|`createEmpty`|__Boolean__. Allows creating a connection without tables. If you want to store only the configuration attributes and import tables later, you can set this attribute to `true`. The default value is `false`. -|`metadata` a|__String__. A JSON map of the connection metadata. The metadata must include xref:connections-api.adoc#connection-attr[configuration attributes], database, schema, and table objects. However, you can create a connection without tables by setting the `createEmpty` attribute to `true`. -|`state`|_Integer_. The GUID of the OAuth redirect URI. This attribute is automatically populated and cannot be set by users. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'name=Snowflake&description=Snowflake_connection&type=RDBMS_SNOWFLAKE&metadata=' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/create' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/create ----- - -==== Example metadata JSON without tables - -The following example shows the metadata JSON map for creating a Snowflake data connection without tables. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"TestConn123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - - ] -} ----- - - -==== Example metadata JSON with tables - -The following example shows the metadata JSON map for creating a Snowflake data connection. Note that the example shows the configuration attributes required to authenticate to the data source, and the object metadata (database, schema, and tables) to add to the connection. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"TestConn123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - { - "name":"AllDatatypes", - "isAutoCreated":false, - "schemas":[ - { - "name":"alldatatypes", - "tables":[ - { - "name":"allDatatypes", - "type":"TABLE", - "description":"", - "selected":true, - "linked":true, - "columns":[ - { - "name":"CNUMBER", - "type":"INT64", - "canImport":true, - "selected":true, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - }, - { - "name":"CDECIMAL", - "type":"INT64", - "canImport":true, - "selected":true, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - } - ] - } - ] - } - ] - } - ] -} ----- - -=== Example response - -If the connection creation is successful, the API returns a response body with the connection metadata header: - -[source,JSON] ----- -{ - "header": { - "id": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "indexVersion": 0, - "generationNum": 0, - "name": "TEST_conn_1", - "description": "TEST_conn_private_1", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531177, - "modified": 1632118531177, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "logicalTableList": [ - { - "columns": [ - { - "physicalColumnGUID": "61d10324-ac22-43e2-8623-fa96f503bab5", - "position": 0, - "header": { - "id": "fd718c83-5e9c-45ae-a4cd-1cb13b03db2f", - "indexVersion": 381, - "generationNum": 384, - "name": "CNUMBER", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "isDerived": false, - "dataType": "INT64", - "type": "MEASURE", - "defaultAggrType": "SUM", - "physicalColumnName": "CNUMBER", - "ownerName": "allDatatypes", - "ownerType": "ONE_TO_ONE_LOGICAL", - "entityCategory": "DEFAULT", - "columnMappingInfo": { - "columnName": "CNUMBER" - }, - "spotiqPreference": "DEFAULT", - "isAdditive": true, - "indexType": "DONT_INDEX", - "indexPriority": 1, - "sources": [], - "synonyms": [], - "customActionTags": [], - "injectedInlineValues": [], - "precision": -1, - "scale": 0, - "schemaVersion": "4", - "isPrimaryKey": false, - "isAttributionDimension": true - }, - { - "physicalColumnGUID": "86c34243-9637-4737-993f-6ed30d3e682c", - "position": 1, - "header": { - "id": "6eed0b58-d195-4236-a376-f135f9b24204", - "indexVersion": 381, - "generationNum": 384, - "name": "CDECIMAL", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "isDerived": false, - "dataType": "INT64", - "type": "MEASURE", - "defaultAggrType": "SUM", - "physicalColumnName": "CDECIMAL", - "ownerName": "allDatatypes", - "ownerType": "ONE_TO_ONE_LOGICAL", - "entityCategory": "DEFAULT", - "columnMappingInfo": { - "columnName": "CDECIMAL" - }, - "spotiqPreference": "DEFAULT", - "isAdditive": true, - "indexType": "DONT_INDEX", - "indexPriority": 1, - "sources": [], - "synonyms": [], - "customActionTags": [], - "injectedInlineValues": [], - "precision": -1, - "scale": 0, - "schemaVersion": "4", - "isPrimaryKey": false, - "isAttributionDimension": true - } - ], - "tableFilters": [], - "physicalTableVersion": 0, - "logicalTableContent": { - "joinType": "INNER", - "joinOverrides": {}, - "physicalTableName": "allDatatypes", - "worksheetType": "VIEW", - "isAggregatedWorksheet": false, - "bypassRLS": false, - "shardingInfo": { - "primaryKeyColumns": [], - "shardingKeyColumns": [], - "numberOfShards": 0 - }, - "tableMappingInfo": { - "databaseName": "AllDatatypes", - "schemaName": "alldatatypes", - "tableName": "allDatatypes", - "tableType": "TABLE", - "cachingInfo": { - "isCached": false, - "lastLoadTime": 0, - "type": "UNKNOWN" - } - }, - "isOptimized": false, - "schemaVersion": "4" - }, - "type": "ONE_TO_ONE_LOGICAL", - "generationType": "DEFAULT", - "physicalTableGUID": "14b7589b-8a98-4786-a0c5-0396e05b91ba", - "relationships": [], - "dataSourceId": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "dataSourceTypeEnum": "DEFAULT", - "header": { - "id": "b0248372-5e68-4815-8682-67715456efb2", - "indexVersion": 381, - "generationNum": 382, -## "name": "allDatatypes", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "su", - "authorDisplayName": "Administrator Super-User", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "type": "ONE_TO_ONE_LOGICAL", - "isExternal": true, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "destinationRelationships": [], - "relationshipsWithin": "", - "isCached": false - } - ], - "dataSourceContent": { - "statistics": {}, - "dataLoadInfo": { - "tableToTaskIdMap": {} - }, - "schemaVersion": "4", - "configuration": { - "password": "", - "role": "DEVELOPER", - "warehouse": "MEDIUM_WH", - "accountName": "thoughtspot_partner", - "user": "tsadmin" - } - } -} - ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful creation of the connection object - -| **401** -| Unauthorized or wrong credentials - -| **500** -| The connection could not be created -|=== - - -[#edit-connection] -== Edit an existing data connection - -To update or modify the connection attributes of a data connection, use the `/tspublic/v1/connection/update` API. - -=== Resource URL ----- -POST /tspublic/v1/connection/update ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form parameter|Description -|`name` |__String__. Name of the connection. -|`description` |__String__. The description of the data connection. -|`type`|__String__. Type of the data connection. For example, `RDBMS_SNOWFLAKE`, `RDBMS_REDSHIFT`. Valid values for `type` map to the *name* attribute from the in the response to the xref:connections-api.adoc#connection-types[/tspublic/v1/connection/types API endpoint]. -|`createEmpty`|__Boolean__. Allows updating a connection without importing tables. If you want to update only the configuration attributes, you can set this attribute to `true`. The default value is `false`. -|`metadata` a|__String__. A JSON map of the connection metadata. The metadata must include xref:connections-api.adoc#connection-attr[configuration attributes], database, schema, and table objects. However, if the `createEmpty` attribute to `true`, you can update the connection attributes without importing tables. -|`id`|__String__. The GUID of the data connection that you want to modify. -|`state`|_Integer_. The GUID of the OAuth redirect URI. This attribute is automatically populated and cannot be set by users. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'name=Snow_TEST&description=Test_connection&type=RDBMS_SNOWFLAKE&id=9114f105-fc9e-48c9-a8f1-57f2fda4f056&metadata=' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/update' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/update ----- - -==== Example metadata JSON without tables - -The following example shows the metadata JSON map for modifying a Snowflake connection without importing tables. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"Embrace123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - - ] -} ----- - - -==== Example metadata JSON with tables - -The following example shows the metadata JSON for modifying a Snowflake data connection. Note that the example shows the configuration attributes to authenticate to the data source, tables, and column data for connection modification. - -[source, JSON] ----- -{ - "configuration":{ - "accountName":"thoughtspot_partner", - "user":"tsadmin", - "password":"Embrace123", - "role":"sysadmin", - "warehouse":"MEDIUM_WH" - }, - "externalDatabases":[ - { - "name":"AllDatatypes", - "isAutoCreated":false, - "schemas":[ - { - "name":"alldatatypes", - "tables":[ - { - "name":"allDatatypes", - "type":"TABLE", - "description":"", - "selected":true, - "linked":true, - "columns":[ - { - "name":"CDECIMAL", - "type":"INT64", - "canImport":false, - "selected":true, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - }, - { - "name":"CBIGINT", - "type":"INT64", - "canImport":false, - "selected":false, - "isLinkedActive":true, - "isImported":false, - "tableName":"allDatatypes", - "schemaName":"alldatatypes", - "dbName":"AllDatatypes" - } - ] - } - ] - } - ] - } - ] -} ----- - -=== Example response - -If the connection modification is successful, the API returns a response body with the updated details: - -[source,JSON] ----- -{ - "dataSource": { - "header": { - "id": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "indexVersion": 385, - "generationNum": 385, - "name": "TEST_conn_1", - "description": "TEST_conn_private_1", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1632118531177, - "modified": 1632118751633, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "isDeleted": false, - "isHidden": false, - "isAutoCreated": false, - "statistics": { - "dataLoadStatistics": { - "scheduled": false, - "connectionType": "", - "connectionDisplayName": "", - "dataLoadStatusList": [], - "header": { - "id": "a2352b8c-e85e-4d58-8f6a-ac42c0252f2d", - "indexVersion": 385, - "generationNum": 385, - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "isDeleted": false, - "isHidden": false, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [] - } - }, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "logicalTableList": [ - { - "columns": [ - { - "physicalColumnGUID": "86c34243-9637-4737-993f-6ed30d3e682c", - "position": 1, - "header": { - "id": "6eed0b58-d195-4236-a376-f135f9b24204", - "indexVersion": 382, - "generationNum": 382, - "name": "CDECIMAL", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "isDerived": false, - "dataType": "INT64", - "type": "MEASURE", - "defaultAggrType": "SUM", - "physicalColumnName": "CDECIMAL", - "ownerName": "allDatatypes", - "ownerType": "ONE_TO_ONE_LOGICAL", - "entityCategory": "DEFAULT", - "columnMappingInfo": { - "columnName": "CDECIMAL" - }, - "spotiqPreference": "DEFAULT", - "isAdditive": true, - "indexType": "DONT_INDEX", - "indexPriority": 1, - "sources": [], - "synonyms": [], - "customActionTags": [], - "injectedInlineValues": [], - "precision": -1, - "scale": 0, - "isPrimaryKey": false, - "isAttributionDimension": true - } - ], - "tableFilters": [], - "physicalTableVersion": 0, - "logicalTableContent": { - "joinType": "INNER", - "joinOverrides": {}, - "physicalTableName": "allDatatypes", - "worksheetType": "VIEW", - "isAggregatedWorksheet": false, - "bypassRLS": false, - "shardingInfo": { - "primaryKeyColumns": [], - "shardingKeyColumns": [], - "numberOfShards": 0 - }, - "tableMappingInfo": { - "databaseName": "AllDatatypes", - "schemaName": "alldatatypes", - "tableName": "allDatatypes", - "tableType": "TABLE", - "cachingInfo": { - "isCached": false, - "lastLoadTime": 0, - "type": "UNKNOWN" - } - }, - "isOptimized": false - }, - "type": "ONE_TO_ONE_LOGICAL", - "generationType": "DEFAULT", - "physicalTableGUID": "14b7589b-8a98-4786-a0c5-0396e05b91ba", - "relationships": [], - "dataSourceId": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "dataSourceTypeEnum": "RDBMS_SNOWFLAKE", - "header": { - "id": "b0248372-5e68-4815-8682-67715456efb2", - "indexVersion": 384, - "generationNum": 384, - "name": "allDatatypes", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1632118531988, - "modified": 1632118532985, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "b0248372-5e68-4815-8682-67715456efb2", - "isDeleted": false, - "isHidden": false, - "schemaStripe": "AllDatatypes_alldatatypes_dMSAHvi", - "databaseStripe": "d19bec78-4e10-446a-b531-2a0e69c5e62f", - "tags": [], - "type": "ONE_TO_ONE_LOGICAL", - "isExternal": true, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [], - "destinationRelationships": [], - "relationshipsWithin": "", - "isCached": false - } - ], - "dataSourceContent": { - "statistics": {}, - "dataLoadInfo": { - "tableToTaskIdMap": {} - }, - "configuration": { - "password": "", - "role": "DEVELOPER", - "warehouse": "MEDIUM_WH", - "accountName": "thoughtspot_partner", - "user": "tsadmin" - } - } - }, - "deletedObjects": { - "deleteStatus": "SUCCESS", - "deleteFailTables": [], - "deleteFailColumns": {} - } -} - ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful update operation -| **401** -| Unauthorized or wrong credentials - -| **500** -| Invalid parameters -|=== - - -[#connection-types] -== Get a list of data connections -To get a list of data connections and their associated attributes, send a `GET` request to the `/tspublic/v1/connection/types` API endpoint. - -=== Resource URL ----- -GET /tspublic/v1/connection/types ----- - -=== Request parameters - -None - -=== Example request - -.cURL -[source,cURL] ----- -curl -X GET \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/types' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/types ----- - -=== Example response - -[source,JSON] ----- -[ - { - "name": "RDBMS_SNOWFLAKE", - "displayName": "Snowflake", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_REDSHIFT", - "displayName": "Amazon Redshift", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_GCP_BIGQUERY", - "displayName": "Google BigQuery", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_AZURE_SQL_DATAWAREHOUSE", - "displayName": "Azure Synapse", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_PRESTO", - "displayName": "Starburst", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_ORACLE_ADW", - "displayName": "Oracle ADW", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - }, - { - "name": "RDBMS_DATABRICKS", - "displayName": "Databricks", - "description": "", - "mode": "PRODUCTION", - "beta": false, - "enabled": true - } -] ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful retrieval of connection types - -| **401** -| Unauthorized or wrong credentials - -| **500** -| No data connections set up on the cluster -|=== - -[#live-query-connections] -== Get a list of live query connections - -To get a list of data connections that are set up as data sources for live query, send a `GET` request to the `GET /tspublic/v1/connection/list` API endpoint. - -=== Resource URL ----- -GET /tspublic/v1/connection/list ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Query parameter|Description -|`category` __Optional__ a|__String__. Type of the live query object. Valid values are: - -* `All` -+ -Gets all live query objects set up on the cluster - -* `MY` -+ -Gets a list of live query objects that are set up on your cluster. - -|`sort` __Optional__ a|__String__. Sort order for the headers. Valid values are: - -* `DEFAULT` to use the default sort order in the response. -* `NAME` to sort headers by the connection name. -* `DISPLAY_NAME` to sort headers by the display name of the connections. -* `AUTHOR` to sort the headers by the author who set up the live query connection. -* `CREATED` to sort headers by the timestamp at which live query connections were set up. -* `MODIFIED` to sort headers by the timestamp at which the live query connections were modified. -| `sortascending` + a|__Boolean__. A flag to specify the sort order. A null value defines the default order. -* To set an ascending order, specify `true`. -* To set a descending order, specify `false`. -|`offset` __Optional__|__Integer__. Batch offset to value to fetch page headers. The default value is `-1`, which implies first page. -|`batchsize` __Optional__ |__Integer__. Number of batches in which you want to fetch page headers in a single query. The default value is `-1`, which implies no pagination. -|`tagname` __Optional__ |__Array of strings__. A JSON array of tag names to filter response headers by tags. A tag is a label applied to a ThoughtSpot object. -|`pattern` __Optional__ |__String__. A pattern to match the name of the object. This parameter supports matching case-insensitive strings. For a wildcard match, use `%`. -|==== - -=== Example request - -.cURL - -[source,curl] ----- -curl -X GET \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/list' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/list ----- - -=== Example response - -[source,JSON] ----- -{ - "headers": [ - { - "id": "c1f17251-b2b1-4230-b10b-c81254d5189f", - "indexVersion": 149, - "generationNum": 149, - "name": "test", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1625126133409, - "modified": 1625126133410, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "c1f17251-b2b1-4230-b10b-c81254d5189f", - "isDeleted": false, - "isHidden": false, - "statistics": { - "dataLoadStatistics": { - "scheduled": false, - "connectionType": "", - "connectionDisplayName": "", - "dataLoadStatusList": [], - "header": { - "id": "c4831f2f-c0a2-498b-9ac5-98b8bd222058", - "indexVersion": 149, - "generationNum": 149, - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "c1f17251-b2b1-4230-b10b-c81254d5189f", - "isDeleted": false, - "isHidden": false, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [] - } - }, - "tags": [], - "type": "RDBMS_SNOWFLAKE", - "isExternal": false, - "isDeprecated": false - }, - { - "id": "55bf4728-bea1-4e89-ae29-822413660daf", - "indexVersion": 328, - "generationNum": 328, - "name": "testsnow", - "description": "", - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "authorName": "tsadmin", - "authorDisplayName": "Administrator", - "created": 1625139996582, - "modified": 1625139996583, - "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "55bf4728-bea1-4e89-ae29-822413660daf", - "isDeleted": false, - "isHidden": false, - "statistics": { - "dataLoadStatistics": { - "scheduled": false, - "connectionType": "", - "connectionDisplayName": "", - "dataLoadStatusList": [], - "header": { - "id": "179697ab-5212-4da8-9508-e0550b7b2327", - "indexVersion": 328, - "generationNum": 328, - "author": "59481331-ee53-42be-a548-bd87be6ddd4a", - "owner": "55bf4728-bea1-4e89-ae29-822413660daf", - "isDeleted": false, - "isHidden": false, - "tags": [], - "isExternal": false, - "isDeprecated": false - }, - "complete": true, - "incompleteDetail": [] - } - }, - "tags": [], - "type": "RDBMS_SNOWFLAKE", - "isExternal": false, - "isDeprecated": false - } - ], - "isLastBatch": true, - "debugInfo": {} -} ----- - - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful retrieval of live query connections list - -| **401** -| Unauthorized or wrong credentials - -| **500** -| No live query connections on the cluster -|=== - -[#connMetadata] -== Get details of a specific connection - -To get details of a specific data connection and its associated columns, send a `POST` request to the `/tspublic/v1/connection/fetchConnection` endpoint. - - -=== Resource URL - ----- -POST /tspublic/v1/connection/fetchConnection ----- - -=== Request parameters - -[width="100%" cols="2,6"] -[options='header'] -|==== -|Form Data Parameter|Description -|`id` + a|__String__. GUID of the data connection. -|`includeColumns` + a|__Boolean__. A flag to include or exclude column metadata in the API response. By default, the API returns data for all columns in the response. -|`config` + -__Optional__ a|__String__. Configuration attributes to override the connection metadata details in the API response. Use this attribute to query data from a specific database. For example, if your connection has a database named `PROD`, and you want to fetch details with the database name as `DEVELOPMENT`, you can define the `config` string as `{"database":"DEVELOPMENT"}`. - -[NOTE] -==== -Note that the `config` attribute does not update the connection metadata in the ThoughtSpot system. It only allows you to modify the metadata in the API response. To update a connection, you must use the `/tspublic/v1/connection/update` endpoint. -==== -|`authentication_type` + a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + - -* `SERVICE_ACCOUNT` + -For data connections that require service account credentials to authenticate to the Cloud Data Warehouse and fetch data. - -* `OAUTH` + -For data connections that require OAuth credentials to authenticate to the Cloud Data Warehouse and fetch data. + -ThoughtSpot data connections to Teradata, Oracle, and Presto Cloud Data Warehouse do not support the `OAuth` authentication type. - -* `IAM` + -For data connections that have the IAM OAuth set up. This authentication type is supported on Amazon Redshift connections only. - -* `EXTOAUTH` + -For data connections that have external OAuth set up. ThoughtSpot supports external OAuth with Microsoft Azure Active Directory (AD) and Okta for Snowflake data connections. For more information, see link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-okta-oauth[Configure Okta OAuth for a Snowflake connection, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-azure-ad-oauth[Configure Azure AD external OAuth for a Snowflake connection, window=_blank]. -|==== - -=== Example request - -.cURL - -[source,CURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'id=abb64e33-1f06-4994-9af7-f6ea8729c9f1&includeColumns=false&config={"database":"RETAILAPPAREL-DEV"}' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchConnection' ----- - -.Request URL - ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchConnection ----- - -=== Example response - -.Sample response with column data -[%collapsible] -==== -[source,JSON] ----- -{ - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "externalDatabases": [ - { - "name": "RETAILAPPAREL", - "isAutoCreated": false, - "schemas": [ - { - "name": "INFORMATION_SCHEMA", - "tables": [ - { - "name": "APPLICABLE_ROLES", - "type": "VIEW", - "description": "The roles that can be applied to the current user.", - "selected": false, - "linked": true, - "columns": [ - { - "name": "SCHEMA_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FILE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_LOAD_TIME", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STATUS", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROW_COUNT", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROW_PARSED", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_MESSAGE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_LINE_NUMBER", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_CHARACTER_POSITION", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "FIRST_ERROR_COL_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ERROR_COUNT", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ERROR_LIMIT", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "relationships": [] - }, - { - "name": "SCHEMATA", - "type": "VIEW", - "description": "The schemas defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [ - { - "name": "CATALOG_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SCHEMA_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SCHEMA_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_TRANSIENT", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_MANAGED_ACCESS", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "RETENTION_TIME", - "type": "INT64", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DEFAULT_CHARACTER_SET_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DEFAULT_CHARACTER_SET_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DEFAULT_CHARACTER_SET_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SQL_PATH", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "COMMENT", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "relationships": [] - }, - { - "name": "FACT_RETAPP_SALES", - "type": "TABLE", - "description": "", - "selected": true, - "linked": true, - "columns": [ - { - "name": "SALESID", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "PRODUCTID", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "STOREID", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "QUANTITYPURCHASED", - "type": "INT64", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "ITEMPRICE", - "type": "DOUBLE", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "SALES", - "type": "DOUBLE", - "canImport": true, - "selected": true, - "isLinkedActive": true - }, - { - "name": "RECORDDATE", - "type": "DATE", - "canImport": true, - "selected": true, - "isLinkedActive": true - } - ], - "relationships": [] - } - ] - } - ] - } - ], - "tables": [], - "selectedTables": [], - "selectedColumns": [], - "configuration": { - "password": "", - "database": "RETAILAPPAREL-DEV", - "role": "PUBLIC", - "accountName": "coa41300.us-east-1", - "warehouse": "DEMO_WH", - "user": "tsuser" - } -} ----- -==== - -.Sample response without column data -[%collapsible] -==== -[source,JSON] ----- -{ - "type": "RDBMS_SNOWFLAKE", - "authenticationType": "SERVICE_ACCOUNT", - "externalDatabases": [ - { - "name": "RETAILAPPAREL", - "isAutoCreated": false, - "schemas": [ - { - "name": "INFORMATION_SCHEMA", - "tables": [ - { - "name": "APPLICABLE_ROLES", - "type": "VIEW", - "description": "The roles that can be applied to the current user.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "COLUMNS", - "type": "VIEW", - "description": "The columns of tables defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "DATABASES", - "type": "VIEW", - "description": "The databases that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "ENABLED_ROLES", - "type": "VIEW", - "description": "The roles that are enabled to the current user.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "EXTERNAL_TABLES", - "type": "VIEW", - "description": "The external tables defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "FILE_FORMATS", - "type": "VIEW", - "description": "The file formats defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "FUNCTIONS", - "type": "VIEW", - "description": "The user-defined functions defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "INFORMATION_SCHEMA_CATALOG_NAME", - "type": "VIEW", - "description": "Identifies the database (or catalog, in SQL terminology) that contains the information_schema", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "LOAD_HISTORY", - "type": "VIEW", - "description": "The loading information of the copy command", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - }, - { - "name": "SCHEMATA", - "type": "VIEW", - "description": "The schemas defined in this database that are accessible to the current user's role.", - "selected": false, - "linked": true, - "columns": [], - "relationships": [] - } - ] - }, - { - "name": "PUBLIC", - "tables": [ - { - "name": "FACT_RETAPP_SALES", - "type": "TABLE", - "description": "", - "selected": true, - "linked": true, - "columns": [], - "relationships": [] - } - ] - } - ] - } - ], - "tables": [], - "selectedTables": [], - "selectedColumns": [], - "configuration": { - "password": "", - "database": "RETAILAPPAREL-DEV", - "role": "PUBLIC", - "accountName": "coa41300.us-east-1", - "warehouse": "DEMO_WH", - "user": "tsuser" - } -} ----- -==== - -=== Response codes - -[width="100%" cols="1,4"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful operation -| **400** -| Invalid parameter values -| **500** -| Invalid connection object ID -|=== - -[#fetchLiveColums] -== Get column data for connections with external tables - -To get column data for a connection with external tables, send a `POST` request to the `/tspublic/v1/connection/fetchLiveColumns` endpoint. - -=== Resource URL - ----- -POST /tspublic/v1/connection/fetchLiveColumns ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form Data Parameter|Description -|`connection_id` + a|__String__. GUID of the data connection. -|`tables` + a|__String__. The external tables to include in the output. The `tables` string allows you to fetch one or several tables from multiple external databases. - -* To get column data for a specific table, specify the string as shown here: + -`[{"tableName":"PIPES"}]` -* To get column data for multiple tables, specify the string as shown here: + -`[{"tableName":"PIPES"},{"tableName":"STAGES"},{"tableName":"SEQUENCES"}]` -* To get column data for tables with a specific schema, specify the string as shown here: + -`[{"databaseName":"RETAILAPPAREL","schemaName":"INFORMATION_SCHEMA"}]` -* To get column data for a specific table from a specific database, specify the string as shown here: + -`[{"databaseName":"RETAILAPPAREL","tableName":"PIPES"}]` -* To get column data for a specific table in an external database with a schema, specify the string as shown here: + -`[{"databaseName":"RETAILAPPAREL","schemaName":"INFORMATION_SCHEMA","tableName":"PIPES"}]` -* To get column data for multiple tables in a specific database, you can specify the string as shown here: + -`[{"databaseName": "RETAILAPPAREL"},{"tableName": "PIPES"},{"tableName":"STAGES"},{"tableName": "SEQUENCES"}]` -* To get column data for specific tables from multiple databases, you can specify the `tables` string as shown here: + -`[{"databaseName": "RETAILAPPAREL","tableName": "PIPES"},{"databaseName": "RETAILAPPAREL-DEV","tableName": "STAGES"}]` - -|`config` + -__Optional__ a|__String__. Configuration attributes to override the metadata details in the API response. Use this attribute to query data from a specific database. For example, if your connection has a database named `PROD`, and you want to fetch details with the database name as `DEVELOPMENT`, you can define the `config` string as `{"database":"DEVELOPMENT"}`. - -[IMPORTANT] -==== -Note that the `config` attribute does not update the connection metadata in the ThoughtSpot system. It only allows you to modify the metadata in the API response. To update the connection metadata, you must use the `/tspublic/v1/connection/update` endpoint. -==== -|`authentication_type` + a|__String__. Type of authentication to use when fetching data from the Cloud Data Warehouse. Valid values are: + - -* `SERVICE_ACCOUNT` __Default__ + -For data connections that require service account credentials to authenticate to the Cloud Data Warehouse and fetch data. - -* `OAUTH` + -For data connections that require OAuth credentials to authenticate to the Cloud Data Warehouse and fetch data. + -ThoughtSpot data connections to Teradata, Oracle, and Presto Cloud Data Warehouse do not support the `OAuth` authentication type. - -* `IAM` + -For data connections that have the IAM OAuth set up. This authentication type is supported on Amazon Redshift connections only. - -* `EXTOAUTH` + -For data connections that have external OAuth set up. ThoughtSpot supports external OAuth with Microsoft Azure Active Directory (AD) and Okta for Snowflake data connections. For more information, see link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-okta-oauth[Configure Okta OAuth for a Snowflake connection, window=_blank] and link:https://docs.thoughtspot.com/cloud/latest/connections-snowflake-azure-ad-oauth[Configure Azure AD external OAuth for a Snowflake connection, window=_blank]. -|==== - -=== Example request - -.cURL - -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'connection_id=2aa36dbd-dda6-4497-a6db-bc47e128862e&tables=[{"tableName":"PIPES"},{"tableName":"STAGES"},{"tableName":"SEQUENCES"}]&config={"database":"DEVELOPMENT"}' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchLiveColumns' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/fetchLiveColumns ----- - -=== Example response - -.Sample response with a single table - -[%collapsible] -==== -[source,JSON] ----- -{ - "..PIPES": [ - { - "name": "PIPE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ] -} ----- -==== - -.Sample response with multiple tables -[%collapsible] -==== -[source,JSON] ----- -{ - "..STAGES": [ - { - "name": "STAGE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_URL", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_REGION", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "..PIPES": [ - { - "name": "PIPE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "PIPE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ], - "..SEQUENCES": [ - { - "name": "SEQUENCE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATA_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ] -} ----- -==== - -.Sample response with tables associated to a specific schema -[%collapsible] -==== -[source,JSON] ----- -{ - "RETAILAPPAREL.INFORMATION_SCHEMA.": [ - { - "name": "GRANTEE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROLE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "ROLE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_GRANTABLE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "TABLE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "TABLE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "TABLE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "COLUMN_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATA_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DOMAIN_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DOMAIN_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DOMAIN_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATABASE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "DATABASE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "IS_TRANSIENT", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "SEQUENCE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_URL", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_REGION", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } - ] -} ----- -==== - -.Sample response with a single table from a specific database -[%collapsible] -==== -[source,JSON] ----- -{ -"RETAILAPPAREL..PIPES": [ -{ -"name": "PIPE_CATALOG", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_SCHEMA", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_NAME", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_OWNER", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "DEFINITION", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "CREATED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "LAST_ALTERED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -} -] -} ----- -==== - -.Sample response with multiple tables from one or more external databases - -[%collapsible] -==== -[source,JSON] ----- -{ -"RETAIL.INFORMATION_SCHEMA.PIPES": [ -{ -"name": "PIPE_CATALOG", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_SCHEMA", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_NAME", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PIPE_OWNER", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "DEFINITION", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "CREATED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "LAST_ALTERED", -"type": "DATE_TIME", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "COMMENT", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -}, -{ -"name": "PATTERN", -"type": "VARCHAR", -"canImport": true, -"selected": false, -"isLinkedActive": true -} -], -"RETAILCLOUD.INFORMATION_SCHEMA.STAGES": [ - { - "name": "STAGE_CATALOG", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_SCHEMA", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_NAME", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_URL", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_REGION", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_TYPE", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "STAGE_OWNER", - "type": "VARCHAR", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "CREATED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - }, - { - "name": "LAST_ALTERED", - "type": "DATE_TIME", - "canImport": true, - "selected": false, - "isLinkedActive": true - } -] -} ----- -==== - -=== Response codes -[width="100%" cols="1,4"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful operation -| **400** -| Invalid connection ID -| **500** -| Invalid string format -|=== - - -[#export-connections] -== Export a connection map - -To export the metadata of an active connection map, send a `GET` request to the `/tspublic/v1/connection/export` API. - -=== Resource URL ----- -GET /tspublic/v1/connection/export ----- - -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Query parameter|Description -|`id` + a|__String__. The GUID of the data connection you want to export. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X GET ---header 'Accept: text/yaml' ---header 'X-Requested-By: ThoughtSpot' -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/export?id=627c35cb-768d-45c7-b41d-346a2220cd82' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/export?id=627c35cb-768d-45c7-b41d-346a2220cd82 ----- -=== Example response - -If the specified GUID is valid and points to an existing data connection on your cluster, the API returns a YAML file containing the connection mapping data. - -Click the link in the `Response body` to download the YAML file. - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **200** -| Successful export of the connection object -| **401** -| Unauthorized request or wrong credentials - -| **500** -| Invalid connection ID -|=== - -[#del-connection] -== Delete a data connection - -To delete a data connection, send a `POST` request to the `/tspublic/v1/connection/delete` API. - -[IMPORTANT] -==== -A connection can be used in multiple data sources or visualizations. If a data connection has dependent objects, make sure you remove its associations before running the delete operation. -==== - -=== Resource URL ----- -POST /tspublic/v1/connection/delete ----- -=== Request parameters - -[width="100%" cols="1,4"] -[options='header'] -|==== -|Form parameter|Description -|`ids` + a|__Array of Strings__. A JSON array of data connection GUIDs to delete. -|==== - -=== Example request - -.cURL -[source,cURL] ----- -curl -X POST \ ---header 'Content-Type: application/x-www-form-urlencoded' \ ---header 'Accept: application/json' \ ---header 'X-Requested-By: ThoughtSpot' \ --d 'ids=%5B%229114f105-fc9e-48c9-a8f1-57f2fda4f056%22%5D' \ -'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/delete' ----- - -.Request URL ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/connection/delete ----- - -=== Example response - -If the connection deletion is successful, the following response code is returned: - ----- -Response Code -204 ----- - -=== Response codes - -[width="100%" cols="1,3"] -[options='header'] -|=== -|HTTP status code | Description - -| **204** -|Successful deletion of the connection object - -| **401** -| Unauthorized request or wrong credentials - -| **500** -| The connection could not be deleted due to table dependencies -|=== - diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc new file mode 100644 index 000000000..c695e2606 --- /dev/null +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -0,0 +1,134 @@ += Customize Liveboard filters +:toc: true +:toclevels: 2 + +:page-title: Customize Liveboard filters +:page-pageid: customize-liveboard-filters +:page-description: Use the Visual Embed SDK to control filter visibility, apply filters at load time, scope filters to tabs and groups, and update filters on an embedded Liveboard. + +To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. The Visual Embed SDK provides properties and host events to control which filter chips are visible, apply filters at load time, scope filters to specific tabs or groups, and update filters programmatically. + +Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component. + +[#filter-visibility] +== Customizing filter visibility +To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. For more information, see xref:customize-liveboard-layout.adoc#show-hide-ui-elements[Show/hide large UI elements]. + +If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, + hideIrrelevantChipsInLiveboardTabs: true, +}); +---- + +When `hideIrrelevantChipsInLiveboardTabs` is `true`: + +* Filter chips backed by data sources that are *not used by any visualization on the active tab* are hidden automatically when the user switches tabs. +* A *Show irrelevant filters* toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips. +* When the user clicks *Show irrelevant filters*, a complementary *Hide irrelevant filters* button appears to restore the filtered view. + +For more information about the compact header, see xref:customize-liveboard-layout.adoc#compact-header[Enable compact Liveboard header]. + +[#masked-filter-chips] +=== Masked filter chips +If a Liveboard includes filters on columns that a user cannot access because of column-level security, the filter values are masked for that user. Use the `showMaskedFilterChip` property to control whether these masked filter chips are visible: + +* `true`: the filter chips for inaccessible columns are displayed as masked. +* `false`: the filter chips for inaccessible columns are hidden. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + showMaskedFilterChip: true, +}); +---- + +The `showMaskedFilterChip` property is also available in full application embedding. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards]. + +[#filters-at-load] +== Apply filters at load time +By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. + +[IMPORTANT] +==== +Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced +limit are silently dropped without an error or warning. For more information, see +xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. +==== + +[#contextual-liveboard-filtering] +== Contextual filtering in Liveboards [earlyAccess eaBackground]#Early Access# +Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parameters can be scoped at three levels: + +* *Liveboard*: applies to all visualizations on the Liveboard. +* *Tab*: applies only to visualizations on a specific tab. +* *Group*: applies only to visualizations in a specific group on a tab. + +With contextual filtering, you can add the same filter at more than one level on a Liveboard, but not at a level directly below it in the same hierarchy. For example: + +* If a `Region` filter is set at the Liveboard level, it cannot be added again on any tab or group on that Liveboard. +* If a `City` filter is set on Tab 1, it cannot be added to a group on Tab 1. However, it can be added to a group on another tab, such as Tab 2, because that group is not in the Tab 1 hierarchy. + +[NOTE] +==== +Contextual filtering in Liveboards is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, set `isScopedLiveboardFilteringEnabled` to `true`. +==== + + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", + isScopedLiveboardFilteringEnabled: true, +}); +---- + +The `isScopedLiveboardFilteringEnabled` property is also available in `AppViewConfig` for full application embedding. + +To get the groups on a Liveboard, use `HostEvent.GetGroups`. To scope a filter or parameter update to a specific tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`: + +[source,javascript] +---- +liveboardEmbed.trigger(HostEvent.UpdateFilters, { + filters: [ + { + column: 'Region', + oper: 'IN', + values: ['West'], + applicability: { + level: 'GROUP', + targetId: '{group-id}', + }, + }, + ], +}); +---- + +To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and `EmbedEvent.ParameterChanged`. Starting with SDK 1.53.0, both events include an optional `applicability` field in their response payload that indicates the scope of the change. + +For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. + +[#update-filters] +== Updating filters +Use the following host events in the Visual Embed SDK to update filters: + +* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatefilters[`HostEvent.UpdateFilters`] to update Liveboard filters +* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateruntimefilters[`HostEvent.UpdateRuntimeFilters`] to update runtime filters +* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatecrossfilter[`HostEvent.UpdateCrossFilter`] + +For more information and examples, see xref:filters_overview.adoc[Filter types and application layers]. + +== Related information +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI] +* xref:liveboard-data-downloads.adoc[Customize data refresh and download options] +* xref:runtime-filters.adoc[Runtime filters] +* xref:runtime-parameters.adoc[Runtime Parameter overrides] diff --git a/modules/ROOT/pages/customize-liveboard-layout.adoc b/modules/ROOT/pages/customize-liveboard-layout.adoc new file mode 100644 index 000000000..046ee4f14 --- /dev/null +++ b/modules/ROOT/pages/customize-liveboard-layout.adoc @@ -0,0 +1,246 @@ += Customize Liveboard layout and UI +:toc: true +:toclevels: 2 + +:page-title: Customize Liveboard layout and UI +:page-pageid: customize-liveboard-layout +:page-description: Use the LiveboardViewConfig properties in the Visual Embed SDK to customize the header, tabs, tiles, and layout of an embedded Liveboard. + +The xref:LiveboardViewConfig.adoc[LiveboardViewConfig] object includes several properties that control the look and layout of an embedded Liveboard, such as the header, tabs, tile spacing, responsive layout, and grouping and styling of tiles. + +Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component. + +[#show-hide-ui-elements] +== Show/hide large UI elements +Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderSticky`, `showLiveboardTitle`, and `showLiveboardDescription` control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether `true` enables or disables the particular feature. + +//Along with xref:Action.adoc[Actions], there is very fine-grained control of the display of the `LiveboardEmbed` component, which can vary for each user or content object displayed depending on the desires of the app development team. + +[.widthAuto] +image::./images/liveboard_view_config_callouts_2.png[LiveboardViewConfig parameters] + +The `hideLiveboardHeader` property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only" use cases or for rebuilding your own menus and buttons using xref:embed-events.adoc[HostEvents]. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed', { + ... // other liveboard view config + hideLiveboardHeader:true, +}); +---- + +When the header is hidden, you can trigger filter interactions programmatically using host events. For more information, see xref:customize-liveboard-filters.adoc#update-filters[Updating filters]. + +The following constructor disables the __sticky header__ and shows the Liveboard title, which is hidden by default: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + isLiveboardHeaderSticky : false, + showLiveboardTitle: true, + liveboardId: '<%=liveboardGUID%>', +}); +---- + +[NOTE] +==== +When `fullHeight` is set to `true`, the SDK ignores the `isLiveboardHeaderSticky:true` setting, and the Liveboard header is not sticky. +==== + +[#compact-header] +== Enable compact Liveboard header +By default, embedded Liveboards display a full-height header bar that contains the Liveboard title, description, filter chips, tab navigation, and action menu. You can switch to a more space-efficient layout by enabling the compact header. + +The compact header reduces the vertical footprint of the header area, integrates tabs and filter chips into a single condensed row, and moves the *Edit* button into the header's overflow action menu. + +To enable the compact header, set `isLiveboardCompactHeaderEnabled` to `true` in the `LiveboardViewConfig` object. Note that the `isLiveboardCompactHeaderEnabled` attribute is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, +}); +---- + +When `isLiveboardCompactHeaderEnabled` is `true`, the following UI changes apply compared to the standard header: + +[width="100%",cols="2,4",options="header"] +|==== +|Area |Change +|Header height |The header renders in a condensed, shorter height to maximize the visible content area. +|Edit button |The *Edit* button is removed from the top-level header and is accessible from the header overflow (*...*) menu. +|Filter chips |Filter chips are rendered inside the compact header's integrated filter row, replacing the separate floating filter panel. +|Tabs |The tab bar is incorporated into the compact header row, rather than appearing as a separate element below the header. +|Sticky scroll behavior |The scroll threshold at which the sticky header attaches to the top of the viewport is recalculated for the compact header's shorter height. This may affect the scroll position at which the header becomes sticky compared to the standard header. +|| +|==== + +=== Hiding the Liveboard title in compact header +In the compact header, you can hide the Liveboard title by setting `showLiveboardTitle` to `false` in the `LiveboardViewConfig` object: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + //... other embed config properties + isLiveboardCompactHeaderEnabled: true, + showLiveboardTitle: false, +}); +---- + +To hide filter chips that are not relevant to the active tab in the compact header, see xref:customize-liveboard-filters.adoc#filter-visibility[Customizing filter visibility]. + +[#liveboard-tabs] +== Customize Liveboard tabs +By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the `activeTabId` property in the Visual Embed SDK as shown in the example here: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", + activeTabId: "05406350-44ce-488e-abc5-5e8cdd65cf3c", +}); +---- + +[NOTE] +==== +The `activeTabId` property is available only in the `LiveboardEmbed` package and is not supported in the full application embed mode. +==== + +[#visible-tabs-vizs] +== Reduce visible tabs and visualizations +`visibleVizs` and `visibleTabs` allow you to limit the experience for certain users on a Liveboard with many more elements. + +For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). + +[#noteTiles] +== Add Note tiles +You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. + +* Only users with edit access to a Liveboard can add a Note tile. +* Users require `Can upload data` privilege to upload an image to the note tile. +* If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. + +[#liveboard-grouping-styling] +== Liveboard grouping and styling + +You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. +To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. +Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. + +* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. +* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. +* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. ++ +[.bordered] +[.widthAuto] +-- +image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] +-- ++ +To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. + +For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. + +For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. + +[#liveboard-gutter] +== Set Liveboard tile gutter + +The `liveboardGutter` property lets you control the spacing between Liveboard tiles and groups, and the grid's outer layout padding, directly from your embed configuration. The value you set overrides the Liveboard's saved styling setting. + +Use this property when you need to enforce consistent tile spacing across embedded Liveboards, regardless of how individual Liveboards are styled in ThoughtSpot. + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '<%=liveboardGUID%>', + liveboardGutter: 16, +}); +liveboardEmbed.render(); +---- + +The following rules apply to the `liveboardGutter` value: + +* Accepts non-negative integers (0 or greater). +* A value of `0` removes all gutter space between tiles and the grid's outer layout padding. +* Negative numbers, decimal values, and non-numeric strings are ignored. The Liveboard falls back to its saved styling value. + +[NOTE] +==== +`liveboardGutter` controls the spacing between tiles and groups, not the spacing within a group. + +The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#_liveboard[Liveboard CSS variables]. +==== + +[#liveboard-breakpoints] +== Redefine Liveboard breakpoint widths +The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. +The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards. + +These breakpoint widths are customizable for the embedded customers. Contact ThoughtSpot support for assistance with customization. + +[#force-12col-layout] +== 12-column layout in embedded Liveboards +By default, embedded Liveboards use a responsive layout that collapses from 12 columns to +2 columns at container widths of 1024px or less, and to a single column at 630px or less. + +Use the `isLiveboardAlwaysOn12ColLayout` property in the SDK to prevent this collapse and keep the +12-column layout at all container widths. + +To force the 12-column layout, set `isLiveboardAlwaysOn12ColLayout` to `true` in the +`LiveboardViewConfig` object: + +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '<%=liveboardGUID%>', + isLiveboardAlwaysOn12ColLayout: true, +}); +---- + +The property is also supported on `AppEmbed` via `AppViewConfig`: + +[source,JavaScript] +---- +const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { + frameParams: { + width: '100%', + height: '100%', + }, + isLiveboardAlwaysOn12ColLayout: true, +}); +---- + +[NOTE] +==== +The CSS variables `--ts-var-liveboard-dual-column-breakpoint` and +`--ts-var-liveboard-single-column-breakpoint` control the pixel thresholds at which the +responsive layout collapses. +Use `isLiveboardAlwaysOn12ColLayout: true` when you want to prevent layout collapse +entirely, rather than adjust the breakpoint thresholds. +For more information about the CSS layout variables available for Liveboard layout control, +see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. +==== + +== Related information +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +* xref:liveboard-data-downloads.adoc[Customize data refresh and download options] +* xref:LiveboardViewConfig.adoc[LiveboardViewConfig] diff --git a/modules/ROOT/pages/data-apis-v2.adoc b/modules/ROOT/pages/data-apis-v2.adoc index bf259489d..372019d89 100644 --- a/modules/ROOT/pages/data-apis-v2.adoc +++ b/modules/ROOT/pages/data-apis-v2.adoc @@ -82,6 +82,8 @@ curl -X POST \ }' ---- +To verify your query string, run an equivalent search in the ThoughtSpot UI search bar and check whether it returns the same data. Note that the search syntax in the UI differs slightly from the query string syntax. + //// === Using tokens generated from Spotter APIs as raw data @@ -113,7 +115,7 @@ If the API request is successful, ThoughtSpot returns the Answer data for the qu == Fetch Liveboard Data API To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. If `visualization_identifiers` is not specified, the API returns data for all visualizations on the Liveboard. === Liveboard data request example [source,cURL] diff --git a/modules/ROOT/pages/data-security.adoc b/modules/ROOT/pages/data-security.adoc index e8f25e89b..d9662010a 100644 --- a/modules/ROOT/pages/data-security.adoc +++ b/modules/ROOT/pages/data-security.adoc @@ -34,6 +34,6 @@ Starting with ThoughtSpot Cloud 26.10.0.cl, Liveboards that include columns rest * Filter chips from columns that the user cannot access are masked instead of blocking the Liveboard. Only one masked filter chip is shown, at the end of the filter bar, to indicate that one or more filters are inaccessible. For example, if five filters are inaccessible, the Liveboard still shows a single masked filter chip. * Scheduled Liveboard deliveries apply CSR separately for each recipient. -To control whether masked filter chips are visible in an embedded Liveboard, use the `showMaskedFilterChip` SDK property. For more information, see xref:embed-pinboard.adoc#masked-filter-chips[Masked filter chips]. +To control whether masked filter chips are visible in an embedded Liveboard, use the `showMaskedFilterChip` SDK property. For more information, see xref:customize-liveboard-filters.adoc#masked-filter-chips[Masked filter chips]. For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-data-object#csr-liveboard[Column security rules on Liveboards, window=_blank]. diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index bfe4aabb6..2664f383a 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -67,7 +67,7 @@ For more information about the Liveboard embed object, classes, methods, interfa The `LiveboardEmbed` component includes the `xref:LiveboardViewConfig.adoc[LiveboardViewConfig]` object. This object provides various attributes and properties to xref:css-customization.adoc[customize the 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 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 <>. == Register, handle, and trigger events @@ -106,505 +106,24 @@ image::./images/embed-lb.png[Liveboard embed] == Common customization options The *xref:LiveboardViewConfig.adoc[LiveboardViewConfig]* object includes several properties and attributes that allow fine-grained control of the embedded experience. You can specify settings that enable or disable a specific feature, control visible or disabled menu elements and actions, set tabs and layout preferences, manage filters, hide the header, and more. -=== Show/hide large UI elements -Parameters such as `hideLiveboardHeader`, `hideTabPanel`, `isLiveboardHeaderSticky`, `showLiveboardTitle`, and `showLiveboardDescription` control various aspects of the standard embedded Liveboard experience. Note the phrasing of the property name and the description in the documentation to understand whether `true` enables or disables the particular feature. - -//Along with xref:Action.adoc[Actions], there is very fine-grained control of the display of the `LiveboardEmbed` component, which can vary for each user or content object displayed depending on the desires of the app development team. - -[.widthAuto] -image::./images/liveboard_view_config_callouts_2.png[LiveboardViewConfig parameters] - -The `hideLiveboardHeader` property removes the entire header area above the Liveboard, including filters and the overall Liveboard menu, which is a common pattern for "read-only" use cases or for rebuilding your own menus and buttons using xref:embed-events.adoc[HostEvents]. - -The following constructor disables the __sticky header__ and shows the Liveboard title, which is hidden by default: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - isLiveboardHeaderSticky : false, - showLiveboardTitle: true, - liveboardId: '<%=liveboardGUID%>', -}); ----- - -[NOTE] -==== -When `fullHeight` is set to `true`, the SDK ignores the `isLiveboardHeaderSticky:true` setting, and the Liveboard header is not sticky. -==== - -[#compact-header] -=== Enable compact Liveboard header -By default, embedded Liveboards display a full-height header bar that contains the Liveboard title, description, filter chips, tab navigation, and action menu. You can switch to a more space-efficient layout by enabling the compact header. - -The compact header reduces the vertical footprint of the header area, integrates tabs and filter chips into a single condensed row, and moves the *Edit* button into the header's overflow action menu. - -To enable the compact header, set `isLiveboardCompactHeaderEnabled` to `true` in the `LiveboardViewConfig` object. Note that the `isLiveboardCompactHeaderEnabled` attribute is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - isLiveboardCompactHeaderEnabled: true, -}); ----- - -When `isLiveboardCompactHeaderEnabled` is `true`, the following UI changes apply compared to the standard header: +The customization options are grouped into the following pages: [width="100%",cols="2,4",options="header"] |==== -|Area |Change -|Header height |The header renders in a condensed, shorter height to maximize the visible content area. -|Edit button |The *Edit* button is removed from the top-level header and is accessible from the header overflow (*...*) menu. -|Filter chips |Filter chips are rendered inside the compact header's integrated filter row, replacing the separate floating filter panel. -|Tabs |The tab bar is incorporated into the compact header row, rather than appearing as a separate element below the header. -|Sticky scroll behavior |The scroll threshold at which the sticky header attaches to the top of the viewport is recalculated for the compact header's shorter height. This may affect the scroll position at which the header becomes sticky compared to the standard header. -|| -|==== - -==== Hiding the Liveboard title in compact header -In the compact header, you can hide the Liveboard title by setting `showLiveboardTitle` to `false` in the `LiveboardViewConfig` object: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - isLiveboardCompactHeaderEnabled: true, - showLiveboardTitle: false, -}); ----- - - -[#liveboard-gutter] -=== Set Liveboard tile gutter - -The `liveboardGutter` property lets you control the spacing between Liveboard tiles and groups, and the grid's outer layout padding, directly from your embed configuration. The value you set overrides the Liveboard's saved styling setting. - -Use this property when you need to enforce consistent tile spacing across embedded Liveboards, regardless of how individual Liveboards are styled in ThoughtSpot. - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '<%=liveboardGUID%>', - liveboardGutter: 16, -}); -liveboardEmbed.render(); ----- - -The following rules apply to the `liveboardGutter` value: - -* Accepts non-negative integers (0 or greater). -* A value of `0` removes all gutter space between tiles and the grid's outer layout padding. -* Negative numbers, decimal values, and non-numeric strings are ignored. The Liveboard falls back to its saved styling value. - -[NOTE] -==== -`liveboardGutter` controls the spacing between tiles and groups, not the spacing within a group. - -The Liveboard header's horizontal margin is controlled separately by the `--ts-var-liveboard-header-horizontal-margin` CSS variable. To align the Liveboard header and tab/filter section with the tile grid, set both `liveboardGutter` and `--ts-var-liveboard-header-horizontal-margin` to matching values. For more information, see xref:customize-css-styles.adoc#lb-header-margin[Liveboard CSS variables]. -==== - -=== Customize Liveboard tabs -By default, the first tab created on a Liveboard is set as the home tab. You can set any tab as an active tab using the `activeTabId` property in the Visual Embed SDK as shown in the example here: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", - activeTabId: "05406350-44ce-488e-abc5-5e8cdd65cf3c", -}); ----- - -[NOTE] -==== -The `activeTabId` property is available only in the `LiveboardEmbed` package and is not supported in the full application embed mode. -==== - -=== Reduce visible tabs and visualizations -`visibleVizs` and `visibleTabs` allow you to limit the experience for certain users on a Liveboard with many more elements. - -For example, a template Liveboard with many different key performance indicators (KPIs) could be reduced to a smaller set by giving a user an interface to select the particular visualizations to show, storing their selections, and using that saved set of visualization globally unique identifiers (GUIDs) as the array for `visibleVizs` on page load (there is an equivalent xref:embed-events.adoc[HostEvent] called `SetVisibleVizs` to make an update after the Liveboard has loaded). - -=== Customizing filter visibility -To hide the entire header area, including filters and the Liveboard menu, set `hideLiveboardHeader` to `true`. You can then trigger filter interactions programmatically using host events. - -[source,JavaScript] ----- -const embed = new LiveboardEmbed('#embed', { - ... // other liveboard view config - hideLiveboardHeader:true, -}); ----- - -If the Liveboard has multiple tabs and the compact header is enabled, you can set `hideIrrelevantChipsInLiveboardTabs` to `true` to hide filters that are not relevant to the current tab in an embedded Liveboard. Note that `hideIrrelevantChipsInLiveboardTabs` is set to `true` by default on all ThoughtSpot embedded instances using Visual Embed SDK v1.51.0 or later. - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - isLiveboardCompactHeaderEnabled: true, - hideIrrelevantChipsInLiveboardTabs: true, -}); ----- - -When `hideIrrelevantChipsInLiveboardTabs` is `true`: - -* Filter chips backed by data sources that are *not used by any visualization on the active tab* are hidden automatically when the user switches tabs. -* A *Show irrelevant filters* toggle button appears in the filter row when at least one chip is hidden, allowing users to temporarily reveal all chips. -* When the user clicks *Show irrelevant filters*, a complementary *Hide irrelevant filters* button appears to restore the filtered view. - -[#masked-filter-chips] -==== #Masked filter chips# -#If a Liveboard includes filters on columns that a user cannot access because of column-level security, the filter values are masked for that user. Use the `showMaskedFilterChip` property to control whether these masked filter chips are visible:# - -* #`true`: the filter chips for inaccessible columns are displayed as masked.# -* #`false`: the filter chips for inaccessible columns are hidden.# - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - showMaskedFilterChip: true, -}); ----- - -#The `showMaskedFilterChip` property is also available in full application embedding. For more information, see xref:data-security.adoc#csr-liveboards[Column security rules on Liveboards].# - -[#noteTiles] -=== Add Note tiles -You can add a link:https://docs.thoughtspot.com/cloud/latest/liveboard-notes[Liveboard Note tile, window=_blank] with custom text, images, and links on an embedded Liveboard. - -* Only users with edit access to a Liveboard can add a Note tile. -* Users require `Can upload data` privilege to upload an image to the note tile. -* If you are adding links and images from an external site, or embedding multimedia or a web page in an iFrame, make sure the URLs are added to CORS and CSP allowlists. For more information, see xref:security-settings.adoc[Security settings]. - -=== Redefine Liveboard breakpoint widths -The `enable2ColumnLayout` property, when enabled, allows you to customize the Liveboard breakpoint width for embedded users. -The current 12 column layout changes to 2 columns per row at 1024px, and to 1 column per row layout at 630px in the new Liveboard experience. Once enabled, these breakpoints apply to all Liveboards in the ThoughtSpot instance, and cannot be set only for individual Liveboards. - -These breakpoint widths are customizable for the embedded customers. Contact ThoughtSpot support for assistance with customization. - -[#force-12col-layout] -=== 12-column layout in embedded Liveboards -By default, embedded Liveboards use a responsive layout that collapses from 12 columns to -2 columns at container widths of 1024px or less, and to a single column at 630px or less. - -Use the `isLiveboardAlwaysOn12ColLayout` property in the SDK to prevent this collapse and keep the -12-column layout at all container widths. - -To force the 12-column layout, set `isLiveboardAlwaysOn12ColLayout` to `true` in the -`LiveboardViewConfig` object: - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '<%=liveboardGUID%>', - isLiveboardAlwaysOn12ColLayout: true, -}); ----- - -The property is also supported on `AppEmbed` via `AppViewConfig`: - -[source,JavaScript] ----- -const appEmbed = new AppEmbed(document.getElementById('ts-embed'), { - frameParams: { - width: '100%', - height: '100%', - }, - isLiveboardAlwaysOn12ColLayout: true, -}); ----- - -[NOTE] -==== -The CSS variables `--ts-var-liveboard-dual-column-breakpoint` and -`--ts-var-liveboard-single-column-breakpoint` control the pixel thresholds at which the -responsive layout collapses. -Use `isLiveboardAlwaysOn12ColLayout: true` when you want to prevent layout collapse -entirely, rather than adjust the breakpoint thresholds. -For more information about the CSS layout variables available for Liveboard layout control, -see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. -==== - -[#liveboard-data-cache] -=== Liveboard browser cache and refresh -ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. - -[NOTE] -==== -The CSS variables `--ts-var-liveboard-dual-column-breakpoint` and -`--ts-var-liveboard-single-column-breakpoint` control the pixel thresholds at which the -responsive layout collapses. -Use `isLiveboardAlwaysOn12ColLayout: true` when you want to prevent layout collapse -entirely, rather than adjust the breakpoint thresholds. -For more information about the CSS layout variables available for Liveboard layout control, -see xref:customize-css-styles.adoc#liveboard-layout-vars[Liveboard layout CSS variables]. -==== - -[#liveboard-data-cache] -=== Liveboard browser cache and refresh -ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. - -To enable Liveboard data caching, set `enableLiveboardDataCache` to `true`. - -[source,javascript] ----- -const liveboardEmbed = new LiveboardEmbed('#embed-container', { - frameParams: { - width: '100%', - height: '100%', - }, - liveboardId: '', // - enableLiveboardDataCache: true, // -}); ----- - -When data caching is enabled, the refresh icon appears in the Liveboard header. Users can click this button to clear the browser cache and fetch fresh data. - -[.bordered] -[.widthAuto] --- -image::./images/liveboard-refresh.png[Liveboard refresh] --- - -The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow. - -[width="100%",cols="2,4"] -|==== -|ID | Description - -|xref:Action.adoc#_refreshliveboardbrowsercache[Action.RefreshLiveboardBrowserCache] -|Action ID to show, hide, or disable the *Refresh* button in the Liveboard header. - -|xref:EmbedEvent.adoc#_refreshliveboardbrowsercache[EmbedEvent.RefreshLiveboardBrowserCache] -|Emitted when a user clicks the *Refresh* button in the Liveboard header. - -|xref:HostEvent.adoc#_refreshliveboardbrowsercache[HostEvent.RefreshLiveboardBrowserCache] -|Triggers a browser cache refresh programmatically for all visualization containers on the embedded Liveboard. +|Page |Customization impact +|xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI] +|Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling. +|xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +|Filter chip visibility, masked filter chips, filters at load time, contextual filtering at the Liveboard, tab, and group levels, and updating filters with host events. +|xref:liveboard-data-downloads.adoc[Customize data refresh and download options] +|Browser data cache and refresh, PDF, XLSX, and CSV downloads, download action IDs and host events, and scheduled exports. |==== -=== Customize filters -To view specific data across the tables and charts on an embedded Liveboard, users can use Liveboard filter options. By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. - [IMPORTANT] ==== -Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. -When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced -limit are silently dropped without an error or warning. For more information, see -xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. +If a Liveboard is saved with Groups in the ThoughtSpot interface, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embed configuration. Otherwise, the embedded Liveboard fails to load. For more information, see xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard grouping and styling]. ==== -[#contextual-liveboard-filtering] -==== Contextual filtering in Liveboards [earlyAccess eaBackground]#Early Access# -Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parameters can be scoped at three levels: - -* *Liveboard*: applies to all visualizations on the Liveboard. -* *Tab*: applies only to visualizations on a specific tab. -* *Group*: applies only to visualizations in a specific group on a tab. - -With contextual filtering, you can add the same filter at more than one level on a Liveboard, but not at a level directly below it in the same hierarchy. For example: - -* If a `Region` filter is set at the Liveboard level, it cannot be added again on any tab or group on that Liveboard. -* If a `City` filter is set on Tab 1, it cannot be added to a group on Tab 1. However, it can be added to a group on another tab, such as Tab 2, because that group is not in the Tab 1 hierarchy. - -[NOTE] -==== -Contextual filtering in Liveboards is an Early Access feature and is disabled by default on ThoughtSpot instances. To enable this feature on your instance, set `isScopedLiveboardFilteringEnabled` to `true`. -==== - - -[source,JavaScript] ----- -const liveboardEmbed = new LiveboardEmbed(document.getElementById('ts-embed'), { - //... other embed config properties - liveboardId: "d7a5a08e-a1f7-4850-aeb7-0764692855b8", - isScopedLiveboardFilteringEnabled: true, -}); ----- - -The `isScopedLiveboardFilteringEnabled` property is also available in `AppViewConfig` for full application embedding. - -To get the groups on a Liveboard, use `HostEvent.GetGroups`. To scope a filter or parameter update to a specific tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`: - -[source,javascript] ----- -liveboardEmbed.trigger(HostEvent.UpdateFilters, { - filters: [ - { - column: 'Region', - oper: 'IN', - values: ['West'], - applicability: { - level: 'GROUP', - targetId: '{group-id}', - }, - }, - ], -}); ----- - -To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and `EmbedEvent.ParameterChanged`. Starting with SDK 1.53.0, both events include an optional `applicability` field in their response payload that indicates the scope of the change. - -For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. - -==== Updating filters -Use the following host events in the Visual Embed SDK to update filters: - -* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatefilters[`HostEvent.UpdateFilters`] to update Liveboard filters -* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateruntimefilters[`HostEvent.UpdateRuntimeFilters`] to update runtime filters -* link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatecrossfilter[`HostEvent.UpdateCrossFilter`] - -For more information and examples, see xref:filters_overview.adoc[Filter types and application layers]. - -=== Liveboard download options - -Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view. - -[NOTE] -==== -Starting with ThoughtSpot Cloud version 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. -==== - -==== XLSX and CSV in Liveboard scheduled exports -To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` is set to `true`. - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - //... - isGranularXLSXCSVSchedulesEnabled: true, // enable scope selection for XLSX and CSV Liveboard scheduled jobs. -}); ----- - -==== Download actions and behavior - -[width=100%, cols="2,2,4"] -[options="header"] -|===== -| Download actions -| SDK parameter -| Action ID for show/hide control -| **Download** menu action -| Enabled by default. -a| Use the `Action.DownloadLiveboard` to show, hide, or disable the Download action in the menu. -| Continuous PDF -|`isContinuousLiveboardPDFEnabled` + -Enables or disables the continuous PDF option in Liveboard downloads -a| Use the `Action.DownloadLiveboardAsContinuousPDF` action ID to show or hide the **PDF (Continuous)** option in the **Download** modal. - -| XLSX download -| `isLiveboardXLSXCSVDownloadEnabled` + -Enables the XLSX and CSV download options in the Download modal. -a|`Action.DownloadLiveboardAsXlsx` - action ID to show or hide the XLSX option in the **Download** modal. - -| CSV download -a| `isLiveboardXLSXCSVDownloadEnabled` + -Enables the XLSX and CSV download options in the Download modal. -a|`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV option in the **Download** modal. - -| PDF cover and filter pages -| None. UI options in PDF modal only. -a| Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog. -|===== - -==== Example - -The following example enables the **PDF (Continuous)**, **XLSX**, and **CSV** options in the Liveboard **Download** modal. - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - isContinuousLiveboardPDFEnabled: true, - isLiveboardXLSXCSVDownloadEnabled: true, -}); ----- - -To hide or disable the download options, specify the following action IDs: - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - //... - hiddenActions: [ - Action.DownloadLiveboard, // Hides the Download parent action from the more options menu - Action.DownloadLiveboardAsContinuousPDF, // Hides the Continuous PDF download option from the Download modal - Action.DownloadLiveboardAsCsv, // Hides the CSV download option from the Download modal - Action.DownloadLiveboardAsXlsx // Hides the XLSX download option from the Download modal - ], - // Use either `hiddenActions` or visibleActions, not both, to avoid errors - //visibleActions: [ - //Action.DownloadLiveboard, // Shows the Download parent action in the more options menu - //Action.DownloadLiveboardAsContinuousPDF, // Shows the Continuous PDF download option - //Action.DownloadLiveboardAsCsv, // Shows the CSV download option - //Action.DownloadLiveboardAsXlsx // Shows the XLSX download option - //] -}); ----- - -[source,javascript] ----- -const embed = new LiveboardEmbed('#tsEmbed', { - //... - disabledActions: [ - Action.DownloadLiveboard,// Disables the Download parent action in the more options menu - Action.DownloadLiveboardAsContinuousPDF, // Disables the Continuous PDF download option in the Download modal - Action.DownloadLiveboardAsCsv, // Disables the CSV download option in the Download modal - Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal - ], -}); ----- - -==== HostEvent workflow for the download actions -Use the HostEvent IDs to trigger download actions on an embedded Liveboard. - -* `HostEvent.DownloadLiveboardAsContinuousPDF` + -To open the **Download** modal with the continuous PDF download option selected. -* `HostEvent.DownloadAsPdf` + -To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of the visualization in the `vizId` key. -* `HostEvent.DownloadAsXlsx` + -To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view. -* `HostEvent.DownloadAsCsv` + -To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view. - -=== Liveboard grouping and styling - -You can now create a visual group of Answers and note tiles together in the Liveboard. You can select multiple Answers and notes in the Liveboard editor. You can also style parts of the Liveboard, groups and Answers with the new styling panel. -To enable this feature, set `isLiveboardMasterpiecesEnabled` to `true`. -Note the following changes that occur in the Liveboard UI and layout when this feature is enabled. - -* All tiles on the Liveboard now have a default border and an increased border-radius, resulting in more pronounced curved corners. This is part of the broader visualization tile customization options to enhance the visual appearance of charts and tables. -* For Note tiles, the default scrollbar is now hidden for long content. Users must scroll within the tile area itself, and if the tile is not sized appropriately for its content, it may appear clipped due to the new container styles. This change emphasizes the importance of sizing Note tiles correctly to avoid content being visually cut off. -* If a Liveboard is saved with Groups in the ThoughtSpot interface, but the embedding code does not have the grouping and styling feature enabled, the Liveboard fails to load and returns an error. -+ -[.bordered] -[.widthAuto] --- -image::./images/lb-grp-styling-error.png[Liveboard with groups styling error] --- -+ -To embed a Liveboard that uses Groups, you must set `isLiveboardMasterpiecesEnabled` to `true` in your embedding configuration. This is required for compatibility with the new grouping and styling features; otherwise, the embedded Liveboard does not render correctly. - -For more information, see link:https://docs.thoughtspot.com/cloud/latest/liveboard-grouping-styling[Liveboard grouping and styling, window=_blank]. - -For information about the CSS variables for this feature, see xref:customize-css-styles.adoc#grp-style[CSS variables reference]. - == Additional resources * For information about runtime overrides, see xref:runtime-filters.adoc[Runtime filters] and xref:runtime-parameters.adoc[Runtime Parameter overrides]. * For code examples, see link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/liveboard[Developer examples^]. diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index 98d1a6ea3..7936588de 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -36,7 +36,7 @@ xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more i ==== 4. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filters, window=_blank] + -Liveboard filters are visible as UI components at the top of a Liveboard page. #By default, a Liveboard filter applies to all visualizations on the Liveboard. Starting with ThoughtSpot Cloud 26.10.0.cl, a filter can also be scoped to a specific tab or group. For more information, see <>.# When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + +Liveboard filters are visible as UI components at the top of a Liveboard page. By default, a Liveboard filter applies to all visualizations on the Liveboard. Starting with ThoughtSpot Cloud 26.10.0.cl, a filter can also be scoped to a specific tab or group. For more information, see <>. When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using `HostEvent.UpdateFilters`. 5. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters-cross[Liveboard cross filters, window=_blank] + @@ -230,7 +230,7 @@ Starting with ThoughtSpot Cloud 26.10.0.cl release, Liveboard filters and parame * *Tab*: applies only to visualizations on a specific tab. * *Group*: applies only to visualizations in a specific group on a tab. -To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:embed-pinboard.adoc#scoped-liveboard-filtering[Scoped Liveboard filtering]. +To enable group-level scoping in an embedded Liveboard, set `isScopedLiveboardFilteringEnabled` to `true` in the embed configuration. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]. To scope an update to a tab or group, pass the `applicability` attribute with `HostEvent.UpdateFilters` or `HostEvent.UpdateParameters`. Set `level` to `TAB` or `GROUP`, and set `targetId` to the ID of the tab or group. To get the group IDs on a Liveboard, use `HostEvent.GetGroups`. diff --git a/modules/ROOT/pages/liveboard-data-downloads.adoc b/modules/ROOT/pages/liveboard-data-downloads.adoc new file mode 100644 index 000000000..6b02d6e71 --- /dev/null +++ b/modules/ROOT/pages/liveboard-data-downloads.adoc @@ -0,0 +1,172 @@ += Customize data refresh and download options +:toc: true +:toclevels: 2 + +:page-title: Customize data refresh and download options +:page-pageid: liveboard-data-downloads +:page-description: Use the Visual Embed SDK to enable browser data caching and refresh, and to configure PDF, XLSX, and CSV downloads and scheduled exports on an embedded Liveboard. + +The Visual Embed SDK provides properties, action IDs, and events to control how users refresh Liveboard data and download or export Liveboards from the embedded view. + +Before you begin, make sure you have xref:embed-pinboard.adoc[embedded a Liveboard] using the `LiveboardEmbed` component. + +[#liveboard-data-cache] +== Liveboard browser cache and refresh +ThoughtSpot supports browser-side data caching for Liveboards to improve load performance for users who revisit the same Liveboard within a session. Users can clear cache by clicking the refresh icon in the Liveboard header. + +To enable Liveboard data caching, set `enableLiveboardDataCache` to `true`. + +[source,javascript] +---- +const liveboardEmbed = new LiveboardEmbed('#embed-container', { + frameParams: { + width: '100%', + height: '100%', + }, + liveboardId: '', // + enableLiveboardDataCache: true, // +}); +---- + +When data caching is enabled, the refresh icon appears in the Liveboard header. Users can click this button to clear the browser cache and fetch fresh data. + +[.bordered] +[.widthAuto] +-- +image::./images/liveboard-refresh.png[Liveboard refresh] +-- + +The Visual Embed SDK also provides the following action IDs and events to customize the cache refresh visibility and workflow. + +[width="100%",cols="3,4"] +|==== +|ID | Description + +|xref:Action.adoc#_refreshliveboardbrowsercache[Action.RefreshLiveboardBrowserCache] +|Action ID to show, hide, or disable the *Refresh* button in the Liveboard header. + +|xref:EmbedEvent.adoc#_refreshliveboardbrowsercache[EmbedEvent.RefreshLiveboardBrowserCache] +|Emitted when a user clicks the *Refresh* button in the Liveboard header. + +|xref:HostEvent.adoc#_refreshliveboardbrowsercache[HostEvent.RefreshLiveboardBrowserCache] +|Triggers a browser cache refresh programmatically for all visualization containers on the embedded Liveboard. +|==== + +[#liveboard-download-options] +== Liveboard download options + +Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view. + +[NOTE] +==== +Starting with ThoughtSpot Cloud version 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. +==== + +=== Download actions and behavior + +[width=100%, cols="2,2,4"] +[options="header"] +|===== +| Download actions +| SDK parameter +| Action ID for show/hide control +| **Download** menu action +| Enabled by default. +a| Use the `Action.DownloadLiveboard` to show, hide, or disable the Download action in the menu. +| Continuous PDF +|`isContinuousLiveboardPDFEnabled` + +Enables or disables the continuous PDF option in Liveboard downloads +a| Use the `Action.DownloadLiveboardAsContinuousPDF` action ID to show or hide the **PDF (Continuous)** option in the **Download** modal. + +| XLSX download +| `isLiveboardXLSXCSVDownloadEnabled` + +Enables the XLSX and CSV download options in the Download modal. +a|`Action.DownloadLiveboardAsXlsx` - action ID to show or hide the XLSX option in the **Download** modal. + +| CSV download +a| `isLiveboardXLSXCSVDownloadEnabled` + +Enables the XLSX and CSV download options in the Download modal. +a|`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV option in the **Download** modal. + +| PDF cover and filter pages +| None. UI options in PDF modal only. +a| Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog. +|===== + +=== Example + +The following example enables the **PDF (Continuous)**, **XLSX**, and **CSV** options in the Liveboard **Download** modal. + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + isContinuousLiveboardPDFEnabled: true, + isLiveboardXLSXCSVDownloadEnabled: true, +}); +---- + +To hide or disable the download options, specify the following action IDs: + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + hiddenActions: [ + Action.DownloadLiveboard, // Hides the Download parent action from the more options menu + Action.DownloadLiveboardAsContinuousPDF, // Hides the Continuous PDF download option from the Download modal + Action.DownloadLiveboardAsCsv, // Hides the CSV download option from the Download modal + Action.DownloadLiveboardAsXlsx // Hides the XLSX download option from the Download modal + ], + // Use either `hiddenActions` or visibleActions, not both, to avoid errors + //visibleActions: [ + //Action.DownloadLiveboard, // Shows the Download parent action in the more options menu + //Action.DownloadLiveboardAsContinuousPDF, // Shows the Continuous PDF download option + //Action.DownloadLiveboardAsCsv, // Shows the CSV download option + //Action.DownloadLiveboardAsXlsx // Shows the XLSX download option + //] +}); +---- + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + disabledActions: [ + Action.DownloadLiveboard,// Disables the Download parent action in the more options menu + Action.DownloadLiveboardAsContinuousPDF, // Disables the Continuous PDF download option in the Download modal + Action.DownloadLiveboardAsCsv, // Disables the CSV download option in the Download modal + Action.DownloadLiveboardAsXlsx, // Disables the XLSX download option in the Download modal + ], +}); +---- + +=== HostEvent workflow for the download actions +Use the HostEvent IDs to trigger download actions on an embedded Liveboard. + +* `HostEvent.DownloadLiveboardAsContinuousPDF` + +To open the **Download** modal with the continuous PDF download option selected. +* `HostEvent.DownloadAsPdf` + +To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of the visualization in the `vizId` key. +* `HostEvent.DownloadAsXlsx` + +To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view. +* `HostEvent.DownloadAsCsv` + +To open the **Download** modal with the CSV option selected when `isLiveboardXLSXCSVDownloadEnabled` parameter is enabled in the embed view. + +[#scheduled-exports] +== XLSX and CSV in Liveboard scheduled exports +To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` is set to `true`. + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + isGranularXLSXCSVSchedulesEnabled: true, // enable scope selection for XLSX and CSV Liveboard scheduled jobs. +}); +---- + +== Related information +* xref:embed-pinboard.adoc[Embed a Liveboard] +* xref:customize-liveboard-layout.adoc[Customize Liveboard layout and UI] +* xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +* xref:Action.adoc[Actions] +* xref:HostEvent.adoc[HostEvent] diff --git a/modules/ROOT/pages/onboarding-guide.adoc b/modules/ROOT/pages/onboarding-guide.adoc index 73d3fa9b9..bf000736f 100644 --- a/modules/ROOT/pages/onboarding-guide.adoc +++ b/modules/ROOT/pages/onboarding-guide.adoc @@ -32,7 +32,7 @@ If you’re using the Free Trial instance, note that it is already connected to To learn more about data connections, data models and objects, and how to search data and create Liveboards, see link:https://docs.thoughtspot.com/cloud/latest/ts-cloud-getting-started[ThoughtSpot product documentation, window=_blank]. -== Embed ThoughtSpotcontent +== Embed ThoughtSpot content This section provides a set of steps to quickly embed a xref:faqs.adoc#lbDef[Liveboard] from the link:https://www.thoughtspot.com/trial?tsiref=web-devsite[Free Trial, window=_blank] or your own ThoughtSpot application instance. The following figure shows a sample Liveboard with charts and a table: diff --git a/modules/ROOT/pages/org-manage-api.adoc b/modules/ROOT/pages/org-manage-api.adoc index efea5a898..304732c25 100644 --- a/modules/ROOT/pages/org-manage-api.adoc +++ b/modules/ROOT/pages/org-manage-api.adoc @@ -17,9 +17,9 @@ include::{path}/rest-apiv1-deprecation-note.adoc[] If you do not see the Orgs feature enabled on your instance, contact ThoughtSpot Support. . Log in to your application instance as an administrator. -. Create Orgs in the *Admin* page of the UI or via xref:org-api.adoc#createOrg[REST API]. +. Create Orgs in the *Admin* page of the UI or via the link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Forgs%2Fcreate-org[`POST /api/rest/2.0/orgs/create`] endpoint. + -To create and manage Orgs, you must set the Org context to `All`. To do this, you can switch to the *All Orgs* tab in the Admin page of UI or pass the Org scope `ALL` in your API requests to Orgs API endpoints. For more information, see xref:org-api.adoc[Org API]. +To create and manage Orgs, you must set the Org context to `All`. To do this, you can switch to the *All Orgs* tab in the Admin page of UI or pass the Org scope `ALL` in your API requests to Orgs API endpoints. For more information, see <<_create_and_manage_orgs,Org management operations>>. . Create users and map the users to Orgs. + You can create an administrator profile for each Org and let these Org administrators manage users, groups, and role privileges in their respective Orgs. @@ -35,29 +35,26 @@ To create an Org on a multi-tenant ThoughtSpot instance, you need cluster admini === REST API v2.0 endpoints -For Orgs CRUD operations, you can also use the following REST API v2.0 Org endpoints: +For Orgs CRUD operations, use the following REST API v2.0 Org endpoints: * +++/api/rest/2.0/orgs/create+++ * +++ /api/rest/2.0/orgs/search+++ * +++/api/rest/2.0/orgs/{org_identifier}/update +++ -* +++ /api/rest/2.0/orgs/{org_identifier}/delete+++ +* +++ /api/rest/2.0/orgs/{org_identifier}/delete+++ -//// -=== REST API v1 endpoints +Note the following points about Org names and descriptions: -For Orgs CRUD operations, use the xref:org-api.adoc[`/tspublic/v1/org/`] endpoints. To access Org API endpoints, you must log in to ThoughtSpot as a cluster administrator: +* The Org name must be unique and must not exceed 48 characters. The name can contain only letters (a-z, A-Z), digits (0-9), and hyphens (-). Spaces and other special characters are not supported. +* The Org description must not exceed 124 characters. -Note that for all Org operations, you must set the org scope to `ALL` in your API request and pass it as a query parameter in the request URL. - -* To create an Org, send a xref:org-api.adoc#createOrg[`POST` request to the `/tspublic/v1/org/` endpoint] with the Org name and description text in the request body. -+ -If the API operation is successful, ThoughtSpot creates an Org and assigns a system-generated number as Org ID. -* To view the Orgs configured on a ThoughtSpot instance, use the xref:org-api.adoc#getOrgs[`/tspublic/v1/org/search`] or xref:org-api.adoc#getOrg[`GET /tspublic/v1/org/`] API endpoint. -* To edit the properties of an Org object, use the xref:org-api.adoc#editOrg[`PUT /tspublic/v1/org/`] endpoint. -+ -The `PUT` request allows modifying the name and description properties of an Org object. -* To delete an Org object, send a `DELETE` request to the xref:org-api.adoc#deleteOrg[`/tspublic/v1/org/` endpoint] with Org ID or name in the request body. -//// +=== Deleting an Org +[NOTE] +==== +* ThoughtSpot does not allow deleting the Primary Org (Org 0). +* When an Org is deleted, the Org and its objects become inaccessible immediately. However, the objects remain in the ThoughtSpot system for seven days from the deletion date. +* To restore a deleted Org, contact ThoughtSpot Support within seven days of deletion. +* To remove the objects of a deleted Org before the seven-day period ends, or to reuse a deleted Org name or object names immediately after deletion, contact ThoughtSpot Support. +==== == Manage users and groups @@ -65,25 +62,15 @@ On a multi-tenant instance, the cluster and Org administrators can create users [NOTE] ==== -The xref:session-api.adoc#orgSwitch[`/tspublic/v1/session/orgs`] REST API v1 endpoint allows administrators to switch between Org contexts. For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests. +For REST API v2 operations, the Org context is determined based on the authentication token used by the user in their API requests. Users must log in to the appropriate Org context from which they want to send API requests. ==== -[width="100%" cols="5,8,7"] +[width="100%" cols="5,15"] [options='header'] |===== -|Operation type|REST API v1 endpoints|REST API v2 endpoints - -|Authentication a| -**Basic authentication** + -To log in to a specific Org context with basic authentication, specify the Org ID in the xref:session-api.adoc#session-login[`/tspublic/v1/session/login`] API request. +|Operation type|REST API v2 endpoints -**Token-based authentication** + -For xref:trusted-authentication.adoc[trusted authentication], use the xref:session-api.adoc#session-authToken[`/tspublic/v1/session/auth/token`] API endpoint. If a user is mapped to a specific org, you can pass the `orgid` in the API request to obtain an authentication token to log in the user to the relevant Org context. + -You can also create a user just-in-time and assign Orgs, groups, and privileges in this API call. - -For more information, see xref:api-auth-session.adoc[REST API v1 authentication]. - -a| **Basic authentication** + +|Authentication a| **Basic authentication** + To log in to a specific Org context with basic authentication, specify the Org ID in the +++ /api/rest/2.0/auth/session/login +++ API request. **Token-based authentication** + @@ -94,22 +81,13 @@ Use the following API endpoints: These above endpoints also support just-in-time provisioning of users to Orgs and groups. For more information, see xref:authentication.adoc[REST API v2 authentication]. -|User provisioning a|To create users, use the xref:user-api.adoc#create-user[`POST /tspublic/v1/user/`] API endpoint. This endpoint also allows assigning a user to Orgs. + - -To add multiple users to an Org in bulk, use the xref:user-api.adoc#addOrg[`/tspublic/v1/user/addtoorg`] API endpoint. + - -To remove a user from an Org, use the xref:user-api.adoc#delete-user[`DELETE /tspublic/v1/user/{userid}`] endpoint. If a user belongs only to the Org specified in the `DELETE` request, the user will be deleted from the Org and ThoughtSpot system. If the user belongs to more than one Org, the `DELETE` operation removes the user from only the Org specified in the API request. To remove the user from the ThoughtSpot system and all Orgs, you must set the `orgid` to `-1` in your API request. -|To create users and assign users to one or several Orgs, use the +++ /api/rest/2.0/users/create +++ API endpoint. + +|User provisioning a|To create users and assign users to one or several Orgs, use the +++ /api/rest/2.0/users/create +++ API endpoint. + To assign an existing user to new Orgs or remove a user from an Org, use the +++ /api/rest/2.0/users/{user_identifier}/update +++ API endpoint. -|Group provisioning a|To create a group in an Org, log in to the Org context or xref:session-api.adoc#orgSwitch[switch to the Org context] and send an API request to the xref:group-api.adoc#create-group[`/tspublic/v1/group/`] endpoint. -a|To create a group in an Org, use the +++ /api/rest/2.0/groups/create +++ API endpoint. - -|Fetching Orgs a| * To get a list of Orgs for the currently logged-in user, use the xref:session-api.adoc#getOrgs[/tspublic/v1/session/orgs] API endpoint. + +|Group provisioning a|To create a group in an Org, use the +++ /api/rest/2.0/groups/create +++ API endpoint. -* To get Orgs for a specific user, use the xref:session-api.adoc#getOrgsForUser[/tspublic/v1/session/orgs/users/{userid}] endpoint. Set the Org scope to `ALL` to get all Orgs for a given user. -a| The REST API v2 endpoints allow you to perform query operations to get Org details: +|Fetching Orgs a| The REST API v2 endpoints allow you to perform query operations to get Org details: * To get a list of all Orgs on the cluster, use +++/api/rest/2.0/orgs/search +++ (Requires cluster administrator privileges) diff --git a/modules/ROOT/pages/report-apis-v2.adoc b/modules/ROOT/pages/report-apis-v2.adoc index a6f42fe91..0d8764a8e 100644 --- a/modules/ROOT/pages/report-apis-v2.adoc +++ b/modules/ROOT/pages/report-apis-v2.adoc @@ -95,6 +95,15 @@ curl -X POST \ For *PDF* downloads, you can specify additional parameters to customize the page orientation and include or exclude the cover page, logo, footer text, and page numbers. +The following `pdf_options` attributes determine the content of the PDF: + +* `include_cover_page`: Adds a cover page with the Liveboard title. +* `include_filter_page`: Adds a page that lists the filters applied to the Liveboard. +* `include_custom_logo`: Adds the custom wide logo, if one is configured for your instance, to the footer of each page. +* `page_footer_text`: Adds the specified text to the footer of each page. +* `include_page_number`: Adds the page number to the footer of each page. +* `truncate_table`: Includes only the first page of each table visualization in the PDF. + You can now also download continuous pdfs which matches the full length of your Liveboard, without breaking them into multiple A4 pages. * `page_size = CONTINUOUS` Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. @@ -232,22 +241,28 @@ include::{path}/transient-lb-content.adoc[] [source,JavaScript] ---- -< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe> -< script src = "/path/to/liveboard.js" > < /script> -< script > - const embed = new LiveboardEmbed("#embed", { - frameParams: {}, - }); - async function liveboardData() { +const embed = new LiveboardEmbed("#embed", { + frameParams: {}, + liveboardId: "", +}); + +async function downloadLiveboardReport() { const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard); - const liveboardDataResponse = await fetch("https://ts_host:port/api/rest/2.0/report/liveboard", { + const payload = { + metadata_identifier: "", + file_format: "PDF", + transient_content: JSON.stringify(transientPinboardContent.data), + }; + const response = await fetch("https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard", { method: "POST", - body: createFormDataObjectWith({ - "transient_content": transientPinboardContent, - }), + headers: { + Authorization: "Bearer {access-token}", + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), }); - } -< /script> + const file = await response.blob(); +} ---- See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index a7620633d..40ee5ec97 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -6,7 +6,7 @@ :page-pageid: rest-apiv2-metadata-search :page-description: Many use cases are possible with the V2.0 metadata/search endpoint -The `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fsearch-metadata[/metadata/search, target=_blank]` endpoint is the most versatile of all metadata endpoints. It can be used to search for lists or to retrieve very detailed information about specific objects. This endpoint replaces `metadata/list`, `metadata/listobjectheaders`, `metadata/details`, and `metadata/listvizheaders` from REST API v1. +The `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fsearch-metadata[/metadata/search, target=_blank]` endpoint is the most versatile of all metadata endpoints. It can be used to search for lists or to retrieve very detailed information about specific objects. == Overview @@ -94,7 +94,7 @@ The response from any call to `metadata/search` returns an array of link:https:/ You'll notice a number of other keys with a `null` value. Various request parameters cause those sections of the response to be filled in with additional details. -The `metadata_header` key is always returned with values, regardless of the request. This section resembles the V1 REST API response from the xref:metadata-api.adoc#metadata-list[`metadata/list`] and xref:metadata-api.adoc#object-header[`metadata/listobjectheaders`] endpoints. +The `metadata_header` key is always returned with values, regardless of the request. The value of `metadata_header` is a complex object with the most important set of attributes of the item. Note that `author` is the creator or current user who has been assigned the __ownership__ of the object, while `owner` describes a hierarchical relationship between ThoughtSpot objects (for example, this Liveboard has an `owner` property identical to its own `id` property): @@ -3574,7 +3574,12 @@ If you need multiple levels of sorting, you'll have to parse the response progra === permissions You can filter responses based on who can access the object, that is, who the content has been shared to, using the `permissions` parameter. -While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint for a full listing, which replaces the individual `security` endpoints in the v1 REST API, such as the xref:security-api.adoc#obj-permission-all[get object permission details for a specific object type] endpoint. +While the `permissions` parameter filters the response set of `metadata/search`, the objects in the response do not list the full set of assigned permissions. Please use the `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Ffetch-permissions-on-metadata[/security/metadata/fetch-permissions/`, target=_blank]` endpoint for a full listing. + +The `/security/metadata/fetch-permissions` endpoint supports the following permission types in the `permission_type` attribute: + +* `DEFINED`: Returns the access granted to users and groups through object sharing. +* `EFFECTIVE`: Returns the access that users have, including the access granted through the privileges of the groups to which they belong. The `permissions` object takes an array of objects that define a `principal` and a `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fenumerations%2Fshare-mode[share_mode, target=_blank]`. `principal` is an object with a `type` of `USER` or `USER_GROUP` and an `identifier`, either the name or the GUID of the principal: @@ -3695,12 +3700,10 @@ The `exclude_objects` parameter takes an array of objects that can exclude items ---- == Additional response details -There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to answer questions that require multiple API calls in the v1 REST API. +There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to return related details in a single API call. === include_visualization_headers -The v1 REST API endpoint xref:metadata-api.adoc#viz-header[`metadata/listvizheaders`] retrieves the header details of all individual visualizations on a Liveboard. - -In v2, the `include_visualization_headers` parameter adds the visualization headers to the response. +The `include_visualization_headers` parameter adds the header details of all individual visualizations on a Liveboard to the response. [source,JSON] ---- @@ -3719,9 +3722,7 @@ Note from above that the response to **every** request has the `visualization_he The `include_visualization_headers` adds the array of visualization headers for every element in the response, so you can request a list of all Liveboards and all the visualizations on those Liveboards all at once. === include_details -The v1 REST API has an endpoint called `metadata/details` for retrieving a very large and complex object containing as much detail as possible about the requested object and its relationships with other objects within ThoughtSpot. - -The `include_details` parameter in the `metadata/search` API request adds the equivalent details object to each element retrieved by `metadata/search` to the response under the `metadata_detail` key. +The `include_details` parameter in the `metadata/search` API request adds a detailed object, with as much detail as possible about each requested object and its relationships with other objects within ThoughtSpot, to each element retrieved by `metadata/search` to the response under the `metadata_detail` key. [source,JSON] ---- @@ -3830,9 +3831,11 @@ Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects* An object can only be deleted if all of its dependent objects are deleted first. -The v1 REST API had an entire set of xref:dependency-apis.adoc[dependent objects APIs] for retrieving these relationships. +A dependency is a relationship between a referenced object and the objects that reference it. For example, consider a Model (`Model1`) with a formula column (`Column1`) that refers to a base column (`Column2`). In this example, `Model1` is a referencing object and `Column2` is a referenced object. You cannot delete `Column2` until you delete or modify `Column1` and `Model1`. + +Before you delete a data object such as a Table, Model, or column by using the `POST /api/rest/2.0/metadata/delete` endpoint, check whether the object has dependent objects, and remove the dependent objects or their references first. -The equivalent information is retrieved from `metadata/search` by setting the `include_dependent_objects` parameter to `true`: +To retrieve these relationships from `metadata/search`, set the `include_dependent_objects` parameter to `true`: [source,JSON] ---- diff --git a/modules/ROOT/pages/rest-api-v2-search.adoc b/modules/ROOT/pages/rest-api-v2-search.adoc index 208d16cfd..33293e1d4 100644 --- a/modules/ROOT/pages/rest-api-v2-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-search.adoc @@ -8,7 +8,7 @@ The REST API v2 endpoints that end in `/search` have very flexible request formats that solve a number of use cases. -Some capabilities that have separate endpoints in the V1 REST API are done using the correct request on the smaller subset of `/search` endpoints in v2.0. +A small set of `/search` endpoints covers many capabilities, depending on the request parameters you send. Note that many parameters in the requests are *optional*, and leaving the parameter name out entirely has a different effect from including the parameter and specific values. @@ -25,7 +25,7 @@ Assume every request you see has the following parameters in addition to what is ---- == Search metadata -The `/metadata/search` endpoint in the V2 REST API replaces a large set of distinct endpoints in REST API V1. +The `/metadata/search` endpoint retrieves metadata objects and their details, such as headers, permissions, and dependent objects. For more information about this API, xref:rest-api-v2-metadata-search.adoc[Search metadata]. diff --git a/modules/ROOT/pages/rest-api-v2-users-search.adoc b/modules/ROOT/pages/rest-api-v2-users-search.adoc index 1d7ebcb58..563415154 100644 --- a/modules/ROOT/pages/rest-api-v2-users-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-users-search.adoc @@ -144,8 +144,6 @@ If you need multiple levels of sorting, you'll have to parse the response progra === group_identifiers You can filter responses based on which groups the user belongs to. -This replaces some of the individual group endpoints in the V1 REST API, such as the xref:group-api.adoc#get-users-group[`/tspublic/v1/group/listuser/{groupid}`] endpoint. - The `group_identifiers` parameter takes an array of strings of either **group name** or **group GUID**. Note that groups have a `display_name` property which is different from **group_name** and cannot be used in the `group_identifiers` array. [source,JSON] @@ -254,7 +252,7 @@ The `notify_on_share`, `show_onboarding_experience`, and `onboarding_experience_ Note that the *absence* of the parameter is how you remove the filtering. If the parameter value is present as a key, the value must be set to `true` or `false`, so that the response can be filtered to get only those users that match the condition. == Additional response details -There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to answer questions that require multiple API calls in the V1 REST API. +There are a number of parameters that add new data to the response, allowing the `metadata/search` endpoint to return related details in a single API call. === include_favorite_metadata The `user` object in the response always includes a `favorite_metadata` key, but it will always be an empty array unless the `include_favorite_metadata` parameter is added to the request set to `true`: diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index 4ee8fb39d..992e60f1c 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -196,37 +196,9 @@ UI: **Can download Data**| Allows users to download data from objects such as Li == How to create and assign Roles -You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the REST API v1 and v2 endpoints. +You can create and assign Roles to a group on the link:https://docs.thoughtspot.com/cloud/latest/rbac[Admin page of the UI, window=_blank] or by using the REST API v2 endpoints. -=== REST API v1 endpoints for Role administration and assignment - -[width="100%" cols="2,4"] -[options='header'] -|=== -|Operation type|API endpoints -|CRUD operations -a| To create, edit, and manage Role objects, use the following endpoints: - -* xref:roles-api.adoc#createRole[`POST /tspublic/v1/role`] + -Create a Role -* xref:roles-api.adoc#editRole[`PUT /tspublic/v1/role/{role_identifier}`] + -Edit properties of a Role object. -* xref:roles-api.adoc#searchRole[`POST /tspublic/v1/role/search`] + -Get a list of Role objects -* xref:roles-api.adoc#deleteRole[`DELETE /tspublic/v1/role/{role_identifier}`] + -Delete a Role object -|Role assignment to groups a| * xref:group-api.adoc#addRole[`POST /tspublic/v1/group/addrole`] + -Allows group administrators to assign a specific Role to a group -* xref:group-api.adoc#create-group[`/tspublic/v1/group/`] + -Allows group administrators to assign one or several Roles to a group -* xref:group-api.adoc#removeRole[`POST /tspublic/v1/group/removerole`] + -Removes the Roles assigned to a group -* xref:group-api.adoc#update-group[`PUT /tspublic/v1/group/{groupid}`] + -Edit Role associations of a group object -|Object query|To get the details of Roles assigned to a group object, use the following API endpoint: -* xref:group-api.adoc#get-users-group[`GET /tspublic/v1/group/`] + -Note that the API response shows the assigned Roles and privileges in the `assignedRoles` and `granularPrivileges` arrays. -|=== +To create and manage Roles, you need the `ROLE_ADMINISTRATION` (*Can manage roles*) privilege. To assign Roles to a group, you need both the `GROUP_ADMINISTRATION` and `ROLE_ADMINISTRATION` privileges. === REST API v2 endpoints for Role administration and assignment @@ -250,8 +222,8 @@ Delete a Role object * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fupdate-user-group[`POST /api/rest/2.0/groups/{group_identifier}/update`] |Object query a| * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Froles%2Fsearch-roles[`POST /api/rest/2.0/roles/search`] + -To get Roles assigned to specific groups, specify the name or GUID of the Role in the `group_identifiers` attribute. + -Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. +To get Roles assigned to specific groups, specify the name or GUID of the group in the `group_identifiers` attribute. + +Similarly, to search for Roles configured in an Org, specify the name or the GUID of the Org in the `org_identifiers` attribute. If `org_identifiers` is not specified, the API returns the Roles for the Org context from which the API request is sent. * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fgroups%2Fsearch-user-groups[`POST /api/rest/2.0/groups/search`] + To filter group objects assigned to a particular Role, specify the name or GUID of the Role in the `role_identifiers` attribute. * link:{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fusers%2Fsearch-users[`POST /api/rest/2.0/users/search`] + diff --git a/modules/ROOT/pages/runtime-sort.adoc b/modules/ROOT/pages/runtime-sort.adoc index 136026a8c..ac8033a58 100644 --- a/modules/ROOT/pages/runtime-sort.adoc +++ b/modules/ROOT/pages/runtime-sort.adoc @@ -161,25 +161,3 @@ curl -X POST \ } } ---- - -=== REST API v1 (Legacy endpoints) - -If you are using REST API v1 endpoints, runtime sorts can be applied when fetching a Liveboard or Answer object from ThoughtSpot. - -To sort columns when fetching data from a Liveboard object, add sort properties to the Liveboard data API request URL as shown in the example here: - ----- -http://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false ----- ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false&sortCol2=Tea ----- - -To sort columns of an Answer object, add the sort attributes to the search data API request URL as shown in the following examples: ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false ----- - ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&sortCol1=Sales&asc1=false&sortCol2=Tea ----- diff --git a/modules/ROOT/pages/tml-export.adoc b/modules/ROOT/pages/tml-export.adoc index 7bfd58583..51aa94772 100644 --- a/modules/ROOT/pages/tml-export.adoc +++ b/modules/ROOT/pages/tml-export.adoc @@ -34,7 +34,7 @@ When set to `true`, exports the associated objects for the `export_ids` specifie * `export_dependent` + Specifies if the Tables of the referenced Connection object must be included in the export. * `export_connection_as_dependent` + -Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. +Specifies if a Connection object must be included as a dependent object when exporting a Table, Model, Answer, or Liveboard TML. This attribute works only when `export_associated` is set to `true`. == Export FQNs diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc index ea1ae5f5e..ceec8f09e 100644 --- a/modules/ROOT/pages/tml-import.adoc +++ b/modules/ROOT/pages/tml-import.adoc @@ -27,8 +27,8 @@ To import TML representation of the metadata objects into ThoughtSpot, use the f There are multiple kinds of imports possible: -* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully. -* `ALL_OR_NONE` imports the objects that validate successfully. +* `PARTIAL` imports all objects that validate successfully, and ignores objects that do not validate successfully and the objects that depend on them. +* `ALL_OR_NONE` imports all objects only if all objects validate successfully. If the import fails for one object, no objects are imported. * `VALIDATE_ONLY` validates the objects but does not import them. * `PARTIAL_OBJECT` imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. @@ -279,8 +279,8 @@ You can import TML objects asynchronously by scheduling TML import tasks via `PO |Form parameter|Description| Default |`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ |`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` -|`all_orgs_context` + +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. When set to `true`, a `guid` in the imported TML that is already used by another object is replaced with a new GUID. If the `guid` in the imported TML is not used by any other object, ThoughtSpot creates the new object with that `guid`. | `false` +|`all_orgs_override` + __Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. __Requires Org administration privileges to access TML objects across all Orgs.__| `false` @@ -324,7 +324,7 @@ curl -X POST \ "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" ], "create_new": true, - "all_orgs_context": false, + "all_orgs_override": false, }' ---- @@ -537,7 +537,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- . Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the other TML. @@ -550,7 +550,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- + diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index aba737cd2..1f20c1543 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -89,7 +89,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- . Remove the text in the `metadata_tmls` array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the otehr TML. @@ -102,7 +102,7 @@ In the JSON preview, you'll see the following code: ], "import_policy": "PARTIAL", "create_new": false, - "all_orgs_context": false + "all_orgs_override": false } ---- + diff --git a/modules/ROOT/pages/whats-new-prev-history.adoc b/modules/ROOT/pages/whats-new-prev-history.adoc index 0de0de67b..6cf22e9a4 100644 --- a/modules/ROOT/pages/whats-new-prev-history.adoc +++ b/modules/ROOT/pages/whats-new-prev-history.adoc @@ -736,7 +736,7 @@ For more information, see xref:selective-user-access.adoc[User access to non-emb ==== You can now customize the width of the Liveboard breakpoint on an embedded instance. To enable it, you must set the `enable2ColumnLayout` property to `true`. -For more information, see xref:embed-pinboard.adoc#_redefine_liveboard_breakpoint_widths[Redefine Liveboard breakpoint widths]. +For more information, see xref:customize-liveboard-layout.adoc#liveboard-breakpoints[Redefine Liveboard breakpoint widths]. ==== .Visual Embed SDK @@ -1389,7 +1389,7 @@ We recommend using a development environment to test your customizations before ==== In the new Liveboard experience mode, you can now add Note tiles with custom text, images, and links. This feature is turned off by default and can be enabled by ThoughtSpot administrators. -For more information, see xref:embed-pinboard.adoc#noteTiles[Note tiles]. +For more information, see xref:customize-liveboard-layout.adoc#noteTiles[Note tiles]. ==== .Visual Embed SDK [%collapsible] @@ -1407,7 +1407,7 @@ For information about REST API enhancements, see xref:rest-apiv1-changelog.adoc[ .New Liveboard experience [%collapsible] ==== -The xref:embed-pinboard.adoc#lbv2[new Liveboard experience] is now Generally Available (GA) on embedded instances and is enabled by default. +The xref:embed-pinboard.adoc[new Liveboard experience] is now Generally Available (GA) on embedded instances and is enabled by default. ==== .New CSS variables for custom styling @@ -1605,7 +1605,7 @@ For more information, see xref:fixed-issues.adoc[Fixed issues]. ==== The new Liveboard experience[beta betaBackground]^Beta^ now supports organizing visualizations in tabs. Users with edit access to a Liveboard can add, edit, and move visualizations to tabs on a Liveboard. On embedded ThoughtSpot instances, developers can set a specific tab as an active tab using the Visual Embed SDK. -This feature is available only on deployments that have the new Liveboard experience enabled. For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liveboard tabs]. +This feature is available only on deployments that have the new Liveboard experience enabled. For more information, see xref:customize-liveboard-layout.adoc#liveboard-tabs[Customize Liveboard tabs]. [IMPORTANT] The new Liveboard experience is in BETA on embedded ThoughtSpot instances. This feature is turned off by default on embedded ThoughtSpot instances. @@ -1665,7 +1665,7 @@ The new Liveboard experience is currently available in BETA on embedded ThoughtS In ThoughtSpot Cloud 8.6.0.cl:: -The new Liveboard experience is turned off by default on embedded ThoughtSpot instances. If you are using the Visual Embed SDK to embed ThoughtSpot, you can xref:embed-pinboard.adoc#lbv2[set the `liveboardV2` parameter] in the SDK package to `true` and enable the new experience globally for all users on your instance. + +The new Liveboard experience is turned off by default on embedded ThoughtSpot instances. If you are using the Visual Embed SDK to embed ThoughtSpot, you can xref:embed-pinboard.adoc[set the `liveboardV2` parameter] in the SDK package to `true` and enable the new experience globally for all users on your instance. + + ThoughtSpot users with administrator privileges can also link:https://docs.thoughtspot.com/cloud/latest/liveboard-experience-new[turn on the new Liveboard experience, window=_blank] at the cluster level. diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index e71d52f10..9628f34b3 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -64,7 +64,7 @@ ThoughtSpot now supports programmatic feature management with new REST API v2 en ==== Liveboard enhancements * *Contextual filtering in Liveboards* [earlyAccess eaBackground]#Early Access# + -Liveboard filters now have a three-tier hierarchy: Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:embed-pinboard.adoc#contextual-liveboard-filtering[Embed a Liveboard]. +Liveboard filters now have a three-tier filter hierarchy : Liveboard level, tab level, and group level. You can enable this feature in embedded Liveboards using the `isScopedLiveboardFilteringEnabled` parameter in the SDK. For more information, see xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[Contextual filtering in Liveboards]. * *Host Events* + @@ -227,13 +227,13 @@ Embedded Spotter interface supports onboarding starter prompts to guide first-ti The following features, previously in Early Access, are now generally available and enabled by default on ThoughtSpot Embedded instances: * Hide irrelevant filters (`hideIrrelevantChipsInLiveboardTabs`) + -xref:embed-pinboard.adoc#_customizing_filter_visibility[Hides filters] that are not relevant to the displayed visualization in a tab. +xref:customize-liveboard-filters.adoc#filter-visibility[Hides filters] that are not relevant to the displayed visualization in a tab. * Compact header (`isLiveboardCompactHeaderEnabled`) + -Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:embed-pinboard.adoc#compact-header[compact Liveboard header]. +Enables in compact header in embedded Liveboards. For information about breaking changes and the affected elements, see xref:customize-liveboard-layout.adoc#compact-header[compact Liveboard header]. * Cover page filtering options (`coverAndFilterOptionInPDF`) + Enables the *Include cover page* and *Include filter page(s)* checkboxes in the Liveboard download modal. * Liveboard styling and grouping (isLiveboardMasterpiecesEnabled) + -Enables the xref:embed-pinboard.adoc#_liveboard_grouping_and_styling[Liveboard styling and grouping] feature. +Enables the xref:customize-liveboard-layout.adoc#liveboard-grouping-styling[Liveboard styling and grouping] feature. * Filter interactivity (`isEnhancedFilterInteractivityEnabled`) + Enables interactive filter chips that allow users to add, update, or remove filters in an embedded Liveboard. @@ -500,7 +500,7 @@ Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. Excel exports for pivot tables:: Pivot table visualizations can now be exported to Excel format. -For more information, see xref:embed-pinboard.adoc#_liveboard_download_options[Liveboard download options]. +For more information, see xref:liveboard-data-downloads.adoc#liveboard-download-options[Liveboard download options]. --- diff --git a/src/components/FloatingAssistant/index.tsx b/src/components/FloatingAssistant/index.tsx index 658f36daa..a3d6b683f 100644 --- a/src/components/FloatingAssistant/index.tsx +++ b/src/components/FloatingAssistant/index.tsx @@ -50,6 +50,14 @@ const FloatingAssistant: React.FC = () => { const [isTutorialsPage, setIsTutorialsPage] = useState( () => typeof window !== 'undefined' && isTutorialsPath(window.location.pathname), ); + // Older-version wrapper pages (e.g. /docs/26.9.0.cl) load the frozen version's site in a + // nested iframe (VersionIframe, src carries ?_iframe=1). The wrapper already mounts its own + // assistant, so the nested copy must not render a second one. Read once at load: the flag + // is on the iframe's initial URL, and in-page navigation inside it may drop the param. + const [isNestedIframe] = useState( + () => typeof window !== 'undefined' + && new URLSearchParams(window.location.search).get('_iframe') === '1', + ); // The 404 page has no fixed pathname to match against (it renders for // whatever bogus URL the user hit), so detect it via document.title // instead. NOTE: a DOM marker (id) doesn't work here — in production, @@ -495,6 +503,7 @@ const FloatingAssistant: React.FC = () => { if (pageId === CUSTOM_PAGE_ID.API_PLAYGROUND) return null; if (isTutorialsPage) return null; if (isNotFoundPage) return null; + if (isNestedIframe) return null; return ( <> diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index d6fa1f9f7..cb02ca339 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -50,39 +50,9 @@ module.exports = { { label: '26.10.0.cl', link: ' ', - subLabel: 'Cloud (Latest)', + subLabel: 'Cloud', iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', }, - { - label: '26.9.0.cl', - link: '26.9.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', - }, - { - label: '26.8.0.cl', - link: '26.8.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/', - }, - { - label: '26.3.0.sw', - link: '26.3.0.sw', - subLabel: 'Software (Latest)', - iframeUrl: 'https://visual-embed-sdk-26-3.vercel.app/docs/', - }, - { - label: '10.10.0.sw', - link: '10.10.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-10.vercel.app/docs/', - }, - { - label: '10.1.0.sw', - link: '10.1.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', - }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', @@ -114,6 +84,7 @@ module.exports = { 'getting-started', 'VisualEmbedSdk', 'embed-spotter', 'embed-spotter-agent', 'embed-ai-search-analytics', 'search-embed', 'embed-searchbar', 'embed-a-viz', 'embed-liveboard', + 'customize-liveboard-layout', 'customize-liveboard-filters', 'liveboard-data-downloads', 'full-embed', 'full-app-customize', 'react-app-embed', 'embed-without-sdk', 'mobile-embed', 'embed-ts-mobile-react-native', 'embed-ts-flutter', 'embed-ts-swift', 'embed-ts-android',