diff --git a/modules/ROOT/pages/abac-user-parameters.adoc b/modules/ROOT/pages/abac-user-parameters.adoc index 8502b9c07..059271ba6 100644 --- a/modules/ROOT/pages/abac-user-parameters.adoc +++ b/modules/ROOT/pages/abac-user-parameters.adoc @@ -16,7 +16,7 @@ The ABAC feature is disabled by default on ThoughtSpot instances. To enable this ==== -// * The `user_parameters` property in `auth/token/full` and `auth/token/object` APIs used for the beta implementation of ABAC is deprecated in 10.4.0.cl. +// * The `user_parameters` property in `auth/token/full` and `auth/token/object` APIs used for the beta implementation of ABAC is deprecated in 10.4.0.cl. // * Starting with 10.4.0.cl, security attributes for ABAC will not be stored in the `user` > `user_parameters` object. All ABAC-related security rules and filters applied via token generated using the `/api/rest/2.0/auth/token/custom` API endpoint are stored in the `user` > `access_control_properties` object. // * The +++Custom access token +++ REST API endpoint. @@ -183,7 +183,8 @@ a|All persisted rules and attributes of the user object are replaced with the se [NOTE] ==== -* By default, the `RESET` option resets all attributes. In 10.6.0.cl and later versions, you can specify the attributes to reset in the `reset_option` attribute. The `reset_option` allows resetting only filter rules, Parameters, or group properties in the token API request. +* By default, the `RESET` option resets all attributes. +//* In 10.6.0.cl and later versions, you can specify the attributes to reset in the `reset_option` attribute. The `reset_option` allows resetting only filter rules, Parameters, or group properties in the token API request. * In 10.4.0.cl, the `REPLACE` behavior can be achieved by making a `RESET` request followed by an `APPEND` request, then passing only the `APPEND` request token to the browser. ==== |===== @@ -223,9 +224,9 @@ To fully remove all persisted `filter_rules` or `parameter_values` from a user o The requested token can still be used for ABAC if you included `filter_rules` or `parameter_values` in the request. === Token request test page -A downloadable, customizable web page for testing all of the ABAC and trusted authentication capabilities is link:https://github.com/thoughtspot/ts_everywhere_resources/tree/master/examples/abac_with_token_auth[available on GitHub^]. +A downloadable, customizable web page for testing all of the ABAC and trusted authentication capabilities is link:https://github.com/thoughtspot/ts_everywhere_resources/tree/master/examples/abac_with_token_auth[available on GitHub^]. -The username specified in the test page must have Administrator privilege or you can supply the *secret_key* for the ThoughtSpot instance to request a token for any user along with setting their ABAC properties. +The username specified in the test page must have Administrator privilege or you can supply the *secret_key* for the ThoughtSpot instance to request a token for any user along with setting their ABAC properties. See the xref:trusted-authentication.adoc[trusted authentication] documentation for full details on proper setup to allow trusted authentication. @@ -237,7 +238,7 @@ Starting in ThoughtSpot 10.4.0.cl, you can add `is_mandatory_token_filter: true` ThoughtSpot checks to see if the logged-in user has any `filter_rules` defined for a column marked with `is_mandatory_filter: true`, and denies access to any data if a filter rule for the matching column is not found. -=== Show All +=== Show All The way to show all values for a column protected by `is_mandatory_token_filter: true` is to pass the special keyword `["TS_WILDCARD_ALL"]` as the value for the column in the `filter_rules`. Columns without `is_mandatory_token_filter: true` will show all values if there is no `filter_rule` for that column. @@ -260,7 +261,7 @@ You can retrieve the attribute names and values from any source: the embedding a ==== Translate entitlements into filter rules -Filter rules *match on the name property of a column* as defined in ThoughtSpot, not the column's name in the underlying database table. +Filter rules *match on the name property of a column* as defined in ThoughtSpot, not the column's name in the underlying database table. The xref:trusted-auth-token-request-service.adoc[token request service] *MUST* know the ThoughtSpot column names that will be used for each of the attributes, so you'll need to coordinate between ThoughtSpot Worksheet designers and the xref:trusted-auth-token-request-service.adoc[token request service] to make sure the matching column names and values are being sent. @@ -308,7 +309,7 @@ The following is a request where a different user can see all `Region`, but stil [source,javascript] ---- "filter_rules": [ - { + { "column_name" : "Customer ID", "operator": "EQ", "values": ["TS_WILDCARD_ALL"] @@ -399,7 +400,7 @@ The basic form of the SQL Pass-through function is: `sql_passthrough_function("", , ,...)` -The proper pass-through function to use in most cases is `sql_bool_op`, which can be used in a filter set to `true` as xref:#worksheet-filter[shown above]. +The proper pass-through function to use in most cases is `sql_bool_op`, which can be used in a filter set to `true` as xref:#worksheet-filter[shown above]. The list of variables after are substituted into the SQL statement using curly braces in the order listed, starting at 0: @@ -460,7 +461,7 @@ For indexing recommendations, see xref:abac-user-parameters.adoc#_configuration_ //// * Several features within ThoughtSpot, such as autocompletion in Search on values within columns or the suggestions in *Explore* mode, use ThoughtSpot indexing. Due to the runtime nature of ABAC via tokens, ThoughtSpot indexing will not be restricted by the values supplied in a token. -+ ++ You must turn off indexing for any field that needs to be restricted by RLS when using ABAC via tokens for RLS, or also include an RLS Rule on fields that must also be filtered for the Indexing system. diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 3e7d2d262..4ae9e49f9 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,30 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 1.39.0, July 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + +The following Spotter embed components are now deprecated and replaced with new components in the SDK and Visual Embed Playground: + +* `ConversationEmbed` + +Replaced with `SpotterEmbed` +* `ConversationViewConfig` + +Replaced with `SpotterEmbedViewConfig` +* `BodylessConversation` + +Replaced with `SpotterAgentEmbed` +* `BodylessConversationViewConfig` + +Replaced with `SpotterAgentEmbedViewConfig` + +The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. For code samples with new component names, see xref:embed-spotter.adoc[Spotter embed documentation]. +|[tag greenBackground]#NEW FEATURE# a| *Action ID of Spotter coaching* + +For ThoughtSpot instances that have the new Spotter feedback and coaching workflow enabled, SDK provides the action ID `Acion.InCoversationTraining` to manage the visibility of the *Add to coaching* button on Answer generated from Spotter prompts. + +[NOTE] +The new Spotter feedback and coaching workflow is a beta feature and is turned off by default. +|==== + == Version 1.38.0, June 2025 [width="100%" cols="1,4"] @@ -37,21 +61,6 @@ In full app embedding, you can now hide the following columns on the *Liveboards `hiddenListColumns: [ListPageColumns.Share]` + For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Customize full application embed]. - -|[tag greenBackground]#NEW FEATURE# a| *Spotter embed components with new names* + -The following Spotter embed components are now deprecated and replaced with new components: - -* `ConversationEmbed` + -Replaced with `SpotterEmbed` -* `ConversationViewConfig` + -Replaced with `SpotterEmbedViewConfig` -* `BodylessConversation` + -Replaced with `SpotterAgentEmbed` -* `BodylessConversationViewConfig` + -Replaced with `SpotterAgentEmbedViewConfig` - -The deprecated components with old names in the existing Spotter embed implementations will continue to function until further notice. -For more information, see xref:whats-new.adoc#_spotter_embed_components[What's new] and xref:embed-spotter.adoc[Spotter embed documentation]. |==== == Version 1.37.0, April 2025 diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index c9ac295b2..10d27cf10 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -589,18 +589,9 @@ Does not update the existing user properties. The attributes defined in the API Available from 10.5.0.cl. Replaces existing user properties of the user with the new attributes assigned to the token in the API request. * `RESET` + -Resets the existing user properties upon token generation and adds the new attributes defined in the request. By default, `"persist_option": "RESET"` resets all attributes, unless a specific `reset_option` is defined. +Resets the existing user properties upon token generation and adds the new attributes defined in the request. By default, `"persist_option": "RESET"` resets all attributes -|`reset_option` a|__Array of strings__. Allows you to define the type of attributes to reset upon token generation. The following options are available: - -* `FILTER_RULES` + -Resets filter attributes. -* `PARAMETERS` -Resets only Parameters. - -* `GROUPS` -Resets group assignments |`filter_rules` a|__Array of filter rules__. An array of runtime filter conditions to pass via token. Each rule in the array must include the following information: @@ -671,6 +662,22 @@ __Optional__|__Boolean__. Available from 10.5.0.cl. Creates a user if the specif __Optional__|__Array of Strings__. GUIDs or names of the groups to assign the user to. This attribute can be used in conjunction with `auto_create` to dynamically assign groups and privileges to a user. |===== + + +//unless a specific `reset_option` is defined. +//// +|`reset_option` a|__Array of strings__. Allows you to define the type of attributes to reset upon token generation. The following options are available: + +* `FILTER_RULES` + +Resets filter attributes. + +* `PARAMETERS` +Resets only Parameters. + +* `GROUPS` +Resets group assignments +//// + ==== Example request [source,cURL] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 8a14e8230..396200e61 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -108,6 +108,7 @@ *** link:{{navprefix}}/set-locale[Customize locale] *** link:{{navprefix}}/custom-domain-config[Custom domain configuration] *** link:{{navprefix}}/customize-emails[Customize onboarding settings] +*** link:{{navprefix}}/customize-email-apis[Customize email template] *** link:{{navprefix}}/in-app-navigation[Create dynamic menus and navigation] ** link:{{navprefix}}/VisualEmbedSdk[Visual Embed SDK Reference] include::generated/typedoc/CustomSideNav.adoc[] @@ -209,13 +210,18 @@ include::generated/typedoc/CustomSideNav.adoc[] * link:{{navprefix}}/development-and-deployment[Deployment and integration] ** link:{{navprefix}}/development-and-deployment[Development and deployment] +*** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects overview] *** link:{{navprefix}}/git-integration[Deploy with Git] **** link:{{navprefix}}/git-configuration[Configure Git integration] **** link:{{navprefix}}/git-api[Version Control REST APIs] **** link:{{navprefix}}/guid-mapping[GUID mapping] *** link:{{navprefix}}/deploy-with-tml-apis[Deploy with TML APIs] -*** link:{{navprefix}}/thoughtspot-objects[ThoughtSpot objects] -*** link:{{navprefix}}/modify-tml[TML modification] +**** link:{{navprefix}}/modify-tml[TML modification] +*** link:{{navprefix}}/publish-data-overview[Publish content to Orgs ^Beta^] +**** link:{{navprefix}}/variables[Define variables ^Beta^] +**** link:{{navprefix}}/parameterze-metdata[Parameterize metadata ^Beta^] +**** link:{{navprefix}}/publish-to-orgs[Publish objects to Orgs ^Beta^] + ** link:{{navprefix}}/multi-tenancy[Multi-tenancy] *** link:{{navprefix}}/orgs[Multi-tenancy with Orgs] *** link:{{navprefix}}/multitenancy-within-an-org[Multi-tenancy within an Org] diff --git a/modules/ROOT/pages/customize-email-apis.adoc b/modules/ROOT/pages/customize-email-apis.adoc new file mode 100644 index 000000000..7242aa5ea --- /dev/null +++ b/modules/ROOT/pages/customize-email-apis.adoc @@ -0,0 +1,129 @@ += Customize email template [beta betaBackground]^Beta^ + +:page-title: Customize notification email settings per Org +:page-pageid: customize-email-apis +:page-description: You can rebrand system-generated notifications and customize notification emails + + + +ThoughtSpot now provides REST APIs that enable developers and administrators to customize the branding, content, and visibility of components in notification emails. ThoughtSpot embedded users receive notification emails for several events, including: + +* ThoughtSpot welcome emails +* Sharing of Liveboards, visualizations, or saved answers +* SpotIQ analysis results +* KPI chart alerts + +These APIs support customizations of the following parameters of the email template at the Org level: + +* Style customization, including font and email colour palette, allows you to set the look and feel, including fonts and colours, for a seamless product experience. +* Custom vocabulary for notification emails. This allows you to replace ThoughtSpot specific terms like “ThoughtSpot,” “Liveboard,” “Answer,” and "SpotIQ," with your product terminology. +* Customizing the company logo and the company contact details in the email footer. +* Customizing the visibility of actions like unsubscribe and mobile app nudge. +* Customizing the visibility of the *Privacy Policy* and *Manage Notification Preferences* components. + +[NOTE] +==== +These APIs are in beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot support. +==== + +== Before you begin + +* For REST API v2 operations, the Org context is determined based on the authentication token used in your API requests. Ensure you log in to the appropriate Org context from which you want to send API requests. +* Ensure that you have developer or administrator privileges for the Org. + +[NOTE] +==== +For overlapping components, customized configuration through these APIs overrides the email configuration through the *Admin* > *Onboarding* page of your ThoughtSpot instance. +==== + + + +//To try the API endpoints for the email customizations, see xref:rest-api-v2-reference.adoc[REST APIs v2]. + +== Create an email customization +To customize the notification emails for your Org, send a `POST` request to the +++ /api/rest/2.0/customization/email +++ API endpoint, with the following parameters in the request body. + +At any given time, only one customized configuration can be set for the notification emails of the Org. The most recently set configuration will be the active one. +[NOTE] +==== +The customized configuration set for the Org overrides the configuration set for the ThoughtSpot instance. However, any Org with no specific configuration will reflect the same configuration as for the ThoughtSpot instance. +==== + + + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description + +|template_properties a|__String__. Required. A JSON map of customizable elements of the email. +|===== + +==== Example request +[source,CURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/customization/email' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "template_properties": { + "ctaButtonBgColor": "", + "ctaTextFontColor": "", + "primaryBgColor": "", + "hideMobileAppNudge": false, + "fontFamily" : "", + "hideProductName" : false, + "hideFooterPhone" : false, + "hideFooterAddress" : false, + "hidePrivacyPolicy" : false, + "hideManageNotification" : false, + "hideTsVocabularyDefinitions": false, + "hideNotificationStatus" : false, + "textTransform": "", + "replacementValueForLiveboard": "LB dashboard", + "replacementValueForAnswer": "Answer dashboard", + "replacementValueForSpotIQ": "SpotIQ dashboard", + "hideErrorMessage": false, + "hideUnsubscribeLink" : false, + "hideModifyAlert": false, + "productName":"ThoughtSpot", + "footerPhone":"(800) 508-7008", + "footerAddress":"444 Castro St, Suite 1000 Mountain View, CA 94041" + } +}' +---- + + +[.widthAuto] +[.bordered] +image:./images/email-template.png[JSON actions explained] + + +== Validate the email customization +To validate your email customization configuration in ThoughtSpot, send a `POST` request to the +++ /api/rest/2.0/customization/email/validate +++ API endpoint. +This triggers a test email that reflects all the customizations you have configured. It allows you to confirm that customizations are applied as expected. You can adjust your configuration if needed and repeat the validation until done. + +For users with developer privileges, the email will be sent to their email id. For users with admin privileges, the email will be delivered to the address associated with the ThoughtSpot account. + +[NOTE] +==== +Validation email delivery requires the mail service to be enabled for the Org. If email configuration is missing, emails will not be sent or received, regardless of the API response. +==== + + +== Search an email customization +To search the email customization configuration set for the Org send a `POST` request to the +++ /api/rest/2.0/customization/email/search +++ API endpoint. + + +== Delete an email customization +To remove an existing customization configuration for notification emails in your Org, send a `POST` request to the +++ /api/rest/2.0/customization/email/{template_identifier}/delete +++ API endpoint, with the `template_identifier` passed as a path parameter in the request URL . + +== Additional references + +* xref:customize-email-settings.adoc[Customize onboarding settings] +* xref:custom-domain-configuration.adoc[Custom domain configuration] diff --git a/modules/ROOT/pages/customize-email-settings.adoc b/modules/ROOT/pages/customize-email-settings.adoc index 9bef3b8b3..1cc592be2 100644 --- a/modules/ROOT/pages/customize-email-settings.adoc +++ b/modules/ROOT/pages/customize-email-settings.adoc @@ -68,4 +68,4 @@ Enter the URL that you want to use as a sign-up button link. + . Click *Save changes*. -. To reset the email and onboarding settings to the application default, click *Reset configuration*. \ No newline at end of file +. To reset the email and onboarding settings to the application default, click *Reset configuration*. diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 42cbb14b7..2de5227f9 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -206,12 +206,24 @@ To download a personalized view of the Liveboard, specify the view name in the ` * Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. ==== -The default `file_format` is PDF. 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. -You can also download the report in PNG format. For PNG downloads, you can include cover page, filters, and define +==== File Format -* `image_resolution` -* `image_scale` -* `include_header` +The default `file_format` is PDF. 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. You can also download the report in PNG format. + +For PNG downloads, you can now define + +* `image_resolution` [earlyAccess eaBackground]#Early Access# +* `image_scale` [earlyAccess eaBackground]#Early Access# +* `include_header` [earlyAccess eaBackground]#Early Access# + +Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance. + +[IMPORTANT] +==== +* If the above settings are enabled on your instance or you are using a ThoughtSpot release 10.9.0.cl or later, you will no longer be able to use the `include_cover_page`,`include_filter_page` within the `png_options`. +* Due to UI limitations in the REST API Playground, you'll notice that some parameters are automatically included in the PNG options JSON. This may cause your API request to fail. As a workaround, click *View JSON* next to the `png_options`, review the parameters, remove additional parameters, and then click *Try it out*. + +==== ==== Example [source,cURL] diff --git a/modules/ROOT/pages/development-and-deployment.adoc b/modules/ROOT/pages/development-and-deployment.adoc index 74ea2ad00..b201c8e94 100644 --- a/modules/ROOT/pages/development-and-deployment.adoc +++ b/modules/ROOT/pages/development-and-deployment.adoc @@ -13,7 +13,7 @@ ThoughtSpot instances act as a constantly running service, so xref:development-a ThoughtSpot provides numerous tools for building a structured deployment process, built around the link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] format for representing the xref:intro-thoughtspot-objects.adoc[objects within ThoughtSpot]. == Best practices -The primary tool for structured development and deployment in ThoughtSpot is called xref:orgs.adoc[Orgs] +The primary tool for structured development and deployment in ThoughtSpot is called xref:orgs.adoc[Orgs]. Each Org in ThoughtSpot can be xref:version_control.adoc[paired] to a link:https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches[branch, target=_blank] in a link:https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories[Git repository, target=_blank] as a single *environment*. @@ -43,7 +43,6 @@ If the production end customer data models are xref:single-tenant-data-models.ad image::./images/single-tenant_prod_per_customer.png[Single-tenant final deployment model] - === Additional "typical" Orgs - *Test*, *UAT*: Additional steps in the publishing process between Dev and Prod, for verification before changes are deployed into Prod @@ -69,5 +68,10 @@ Everything done via the /vcs/git/ REST APIs can also be done within your own cod You will need a xref:guid-mapping.adoc[GUID Mapping file] that records the `originalGuid` of the source object and the `mappedGuid` of the object in the destination Org, at the time it is first created. == Multi-tenancy and data security -The exact deployment pattern chosen will depend on the design of your data warehouse. Please see the xref:multi-tenancy-intro.adoc[full documentation on multi-tenancy within ThoughtSpot] to determine which deployment pattern best fits your needs. +The exact deployment pattern chosen will depend on the design of your data warehouse. Please see the xref:multi-tenancy-intro.adoc[full documentation on multi-tenancy within ThoughtSpot] to determine which deployment pattern best fits your needs. + +== Publishing content to Orgs within a ThoughtSpot instance + +Starting with the 10.10.0.cl release, ThoughtSpot provides the ability to parameterize object properties using variables for each Org and publish objects directly from the Primary Org to other Orgs on a multi-tenant instance. The publishing feature [beta betaBackground]^Beta^ enables administrators to create a single main object in the Primary Org and distribute it to other Orgs within the instance. +For more information, see xref:publishing-overview.adoc[Publishing content to Orgs]. \ No newline at end of file diff --git a/modules/ROOT/pages/metadata-parameterization.adoc b/modules/ROOT/pages/metadata-parameterization.adoc new file mode 100644 index 000000000..293bbacca --- /dev/null +++ b/modules/ROOT/pages/metadata-parameterization.adoc @@ -0,0 +1,151 @@ += Parameterize metadata objects +:toc: true +:toclevels: 2 + +:page-title: parameterize metadata objects +:page-pageid: parameterze-metdata +:page-description: Use the metadata parameterization APIs to assign dynamic values via variables to connection or table properties + +In ThoughtSpot, metadata parameterization refers to the process of assigning variables to certain properties and fields within metadata objects such as Connections and Tables. These variables can have different values assigned for each Org context, which are applied dynamically at runtime, rather than relying on hardcoded static values. + +Metadata parameterization with variables allows administrators to reuse and propagate the same metadata object across various Orgs and environments within a ThoughtSpot instance while maintaining a consistent data structure of objects across Orgs. + +== Before you begin + +* Ensure that that xref:variables.adoc[variables are available] on your instance. You can use the xref:variables.adoc#_get_details_of_variables[variable search API] to get a list of variables. +* Ensure that you have edit access to the Connections and Tables to which you want to assign variables. + +== How to parameterize objects +You can update the properties of a Connection or Table to parameterize or remove parameterization by using one of the following options: + +* Use REST APIs + +To parameterize the properties of a metadata object, send an xref:metadata-parameterization.adoc#_remove_parameterization_using_rest_api[API request to the `/api/rest/2.0/metadata/parameterize` endpoint]. + +To remove parameterization, use the xref:metadata-parameterization.adoc#_remove_parameterization_using_rest_api[the `/api/rest/2.0/metadata/parameterize` API endpoint]. +* Edit the TML representation of the object + +You can edit the TML object directly and assign variables. + +For example, to parameterize the properties of a Table, open the TML of the Table object in the edit mode and assign the variables to the properties as shown here: ++ +[source,YAML] +---- +table: + name: Sales + db: "${DATABASE}" + schema: "${SCHEMA_VAR}" + db_table: "${TABLE_VAR}" +---- + +== Parameterize object properties using REST API +To parameterize properties of a metadata object, send a `POST` request to the +++/api/rest/2.0/metadata/parameterize+++ API endpoint, with the following attributes in the request body. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter|Description +|`metadata_type` __Optional__ a| __String__. Type of the metadata object. Valid values are: + +* `LOGICAL_TABLE` + +Use this option for Tables +* `CONNECTION` + +Use this option for data connection objects. + +Note that this attribute is __optional__ if a GUID is specified as `metadata_identifier` in the request. If you have specified the object name instead of the GUID, and multiple objects in your Org share that name, make sure to specify the metadata type. + +|`metadata_identifier` a| __String__. ID or name of the metadata object. + +|`field_type` a|__String__. Type of object property. Valid values are: + +* `ATTRIBUTE` for Tables +* `CONNECTION_PROPERTY` for Connections +|`field_name` a|__String__. The name of the field to parameterize. + +For tables, use one of the following names, depending on the property that you want to parameterize: + +* `databaseName` +* `schemaName` +* `tableName` + +For connection objects, specify the exact name of the field or property to parameterize. For example, `accountName`, `role`, and `warehouse`. + +|`variable_identifier` a| __String__. ID or name of the variable. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/parameterize' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_identifier": "eefd754f-7146-432d-9ad6-2c730264ecc8", + "field_type": "ATTRIBUTE", + "field_name": "schemaName", + "variable_identifier": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "metadata_type": "LOGICAL_TABLE" +}' +---- + +If the API request is successful, ThoughtSpot returns a 204 response indicating that the variable has been successfully assigned to the specified object. + +== Remove parameterization using REST API +To remove the variables assigned to a Connection or Table and restore static values, send a `POST` request to the +++/api/rest/2.0/metadata/unparameterize+++ API endpoint, with the following attributes in the request body. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`metadata_type` __Optional__ a| __String__. Type of the metadata object. Valid values are: + +* `LOGICAL_TABLE` + +Use this option for Tables +* `CONNECTION` + +Use this option for data connection objects + +Note that this attribute is __optional__ if a GUID is specified as `metadata_identifier` in the request. If you have specified the object name instead of the GUID, and multiple objects in your Org share that name, make sure to specify the metadata type. + +|`metadata_identifier` a| __String__. ID or name of the metadata object. + +|`field_type` a|__String__. Type of object property. Valid values are: + +* `ATTRIBUTE` for Tables + +* `CONNECTION_PROPERTY` for Connections + +|`field_name` a|__String__. The name of the field to parameterize. + +For Table attributes, use one of the following options: + +* `databaseName` +* `schemaName` +* `tableName` + +For connection objects, specify the name of the field or property for which you want to restore a static value. +|`value` a| __String__. Value to assign to the object property. This will assign a static value and remove the variable from the object property. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/unparameterize' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_identifier": "metadata_identifier2", + "field_type": "ATTRIBUTE", + "field_name": "field_name0", + "value": "sales", + "metadata_type": "LOGICAL_TABLE" +}' +---- + +If the API request is successful, ThoughtSpot returns a 204 response indicating that the variable has been successfully removed from the specified object. diff --git a/modules/ROOT/pages/prerender.adoc b/modules/ROOT/pages/prerender.adoc index 25e7c4c0a..1243faa23 100644 --- a/modules/ROOT/pages/prerender.adoc +++ b/modules/ROOT/pages/prerender.adoc @@ -1,4 +1,4 @@ -= Prerender components += Prerender embed components :toc: true :toclevels: 3 @@ -6,18 +6,161 @@ :page-pageid: prerender :page-description: Prerender components to optimize user experience of your embedding application -To optimize your user's experience when ThoughtSpot is embedded into your application, we recommend using the prerender method. +ThoughtSpot supports the following rendering options for the embed components: -== Prerender +* Normal render + +Normal render is the default behavior of the ThoughtSpot SDK. It loads the ThoughtSpot app when the component is rendered. +* Pre-Render + +Pre-renders the embed as soon as the component code is rendered. With this, the amount of ThoughtSpot assets left to load when the user accesses the embedded content is reduced. +* On-demand pre-rendering + +Pre-renders after the embed component is rendered at least once. + +== Overview +Pre-rendering allows application to load ThoughtSpot embed components in the background. You can use pre-rendering for performance optimization, reducing iframe initialization delays, and for seamless transition between the embed views and application pages. -You can load ThoughtSpot components that are not specific to the user's session before your application user accesses the embedded content. With this, the amount of ThoughtSpot assets left to load when the user accesses the embedded content is reduced. +The prerender feature creates a placeholder element for the ThoughtSpot component. To preload it effectively, place the element in a section of your app that users see before accessing the component. For example, analytics applications often have custom landing pages that direct users to embedded content. Preloading the component on this page ensures it is ready to render when users click on a link. -=== When to use prerender +The following figure illustrates the benefits of the pre-render method: + +image::./images/prerender.png[prerender] + +=== When to use pre-render Use prerender in the following cases: -* if you have applications that do not have ThoughtSpot on the landing page. -* if you are embedding ThoughtSpot Liveboards in your applications. +* If you want to preload an embed component, such as a Liveboard, Spotter interface, or full application, before it's shown to the user. +* Your application has a tabbed interface with multiple embed views or your embed involves switching between pages, and you want to show the components on the next page instantly. + +== How to pre-render components +To pre-render a component: + +. Add pre-render options to your embed code. + +In this example, let's add a pre-render ID to the Liveboard embed instance. ++ +[source,JavaScript] +---- +const liveboardEmbed = new LiveboardEmbed('#embed', { + liveboardId: '', + preRenderId: 'my-prerender-id', // Unique ID for this pre-render instance + // Optionally, disable dynamic size tracking: + // doNotTrackPreRenderSize: true, +}); +---- +You can also pre-render a generic instance in the background using the `prerenderGeneric` method. This preloads a generic instance of the component (without a specific path) in the background and applies flags. The `liveboardId` is passed when your embed is rendered. This is a generic pre-render where only the basic assets needed for rendering the app are loaded. +This method might not be as fast as pre-rendering with `liveboardId` but it is faster than normal rendering. + ++ +[source,JavaScript] +---- +await liveboardEmbed.prerenderGeneric(); +---- +. Create a placeholder shell. + +This sets up the pre-render shell and is hidden by default. + ++ +[source,JavaScript] +---- +await liveboardEmbed.preRender(); +---- +. Show pre-rendered component. ++ +[source,JavaScript] +---- +await liveboardEmbedembed.showPreRender(); +---- +. For style synchronization such as adjusting the position, width, and height of the pre-rendered component to match the embedding element, call the `syncPreRenderStyle` method to ensure a seamless display of styles. ++ +[source,JavaScript] +---- +embed.syncPreRenderStyle(); +---- + +== Code sample + +[source,JavaScript] +---- +import { + LiveboardEmbed, + AuthType, + init, + prefetch, +} from '@thoughtspot/visual-embed-sdk'; + +// Initialize SDK +init({ + thoughtSpotHost: 'https://', + authType: AuthType.None, +}); + +//Create LiveboardEmbed instance +const liveboardEmbed = new LiveboardEmbed('#embed', { + liveboardId: '', //Replace with your actual Liveboard ID + preRenderId: 'my-prerender-id', //Replace with the actual ID +}); + +// Pre-render in the background +liveboardEmbed.showPreRender(); + +//Show the pre-rendered component when needed +document.getElementById('show-liveboard-btn').onclick = () => { + liveboardEmbed.render(); +}; +---- + +== Best practices +* Use unique `preRenderId` values for each separate embed. +* Place the pre-render shell in the DOM early (on page mount). +* If using `prerenderGeneric`, call this method early. +* Avoid multiple re-instantiations. Initialize once and reuse the instance. +* Use `full-height` if necessary. + +== SDK reference for pre-rendering methods and properties + +The Visual Embed SDK provides the following methods and properties for pre-rendering embed components: + +[width="100%" cols="5,7,7"] +[options="header"] +|==== +| Name +| Description +| Example +| xref:AppEmbed.adoc#_prerender[preRender] +| This method creates `preRender` shell. Optionally, shows the preRender after rendering components. +a| `await embed.preRender();` +| xref:AppEmbed.adoc#_prerendergeneric[prerenderGeneric] +| This method pre-renders a generic instance of the ThoughtSpot embed component. +| `await embed.prerenderGeneric();` +| xref:AppEmbed.adoc#_showprerender[showPreRender] +| This method displays the pre-rendered component. If the component is not pre-rendered, it creates and renders it. +| `await embed.showPreRender();` +| xref:AppEmbed.adoc#_hideprerender[hidePreRender] +| This method hides the pre-rendered component if available. +| `embed.hidePreRender();` +| xref:AppViewConfig.adoc#_getprerenderids[getPreRenderIds] +| This method retrieves unique HTML element IDs for pre-render-related elements, based on `preRenderId`. +| `embed.getPreRenderIds();` +| xref:AppEmbed.adoc#_getprerenderids[preRenderId] +| This configuration property allows defining the object ID for the pre-rendered instance. Can be used with `showPreRender`/`hidePreRender`. +| `preRenderId: "preRenderId-123"` +| xref:AppEmbed.adoc#_syncprerenderstyle[syncPreRenderStyle] +| This method synchronizes style, position, width, height of the pre-rendered component with embedding element. +| `embed.syncPreRenderStyle();` +| xref:AppViewConfig.adoc#_donottrackprerendersize[doNotTrackPreRenderSize] +| This configuration setting disables dynamic size tracking for pre-render component when set to true. +| `doNotTrackPreRenderSize: true` +|==== + +== Additional resources + +* link:https://github.com/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[Pre-rendering examples GitHub repository, window=_blank] +* link:https://codesandbox.io/p/sandbox/github/thoughtspot/developer-examples/tree/main/visual-embed/pre-rendering[Code sandbox, window=_blank] + + +//// +== Prerender + +You can load ThoughtSpot components that are not specific to the user's session before your application user accesses the embedded content. + === How it works @@ -25,10 +168,6 @@ Pre-render allows developers to pre-load the ThoughtSpot application in the back It allows you to create a placeholder element on the page for the Liveboard to eventually populate. To preload components, you must place this element into a section of your application that will be viewed before the Liveboard. For example, it is common for analytics applications to have a custom-built landing page that directs users to relevant pieces of embedded content. This would be an ideal place to preload the component, so the frame is ready to render by the time the user clicks on a specific link. -The following figure illustrates the benefits of the pre-render method: - -image::./images/prerender.png[prerender] - === How to implement prerender Depending on the framework and project, you can implement this using xref:_standard_js[Standard JavaScript] or xref:_react[React]. @@ -278,7 +417,6 @@ function toggleLiveboardSelect(e){ } ---- -//// == Turn on CDN Using a Content Delivery Network (CDN) reduces the time to pre-render static or dynamic ThoughtSpot assets by caching resources closer to the end user. When your application users navigate to ThoughtSpot very quickly after the embedding application loads, they need not wait for assets to finish pre-rendering. diff --git a/modules/ROOT/pages/publish-api.adoc b/modules/ROOT/pages/publish-api.adoc new file mode 100644 index 000000000..77ad1c462 --- /dev/null +++ b/modules/ROOT/pages/publish-api.adoc @@ -0,0 +1,131 @@ += Publish objects to Orgs +:toc: true +:toclevels: 2 + +:page-title: Publish objects to Orgs +:page-pageid: publish-to-orgs +:page-description: Use the publish APIs to publish a master object from a primary Org to destination Orgs on a ThoughtSpot instance + +The publishing feature simplifies and automates content distribution from the Primary Org to one or several target Orgs in a multi-tenant instance. + +For large-scale deployments requiring the same analytics content, with the underlying Table or Connection properties that vary per Org, use xref:variables.adoc[variables] to parameterize the object properties. This ensures that the same object can be used across all target Orgs, with variable values dynamically adjusted to each Org's specific context. + +To publish objects programmatically from the Primary Org to one or several target Orgs in a single API call, use the +++/api/rest/2.0/security/metadata/publish +++ API endpoint. + +== Before you begin + +* Ensure that you have administration permissions with access to all Orgs to publish content to Orgs on your instance. +* If you are publishing a Liveboard or Answer and the properties of its underlying data source vary per Org, ensure that the xref:metadata-parameterization.adoc[underlying data objects are parameterized] to use dynamic values for the target Org context. + +== Publish objects +The publish API allows publishing objects such as Liveboards, Answers, Tables, and Model from the Primary Org to one or several destination Orgs. The API doesn't support publishing Connections. + +To publish an object to one or several Orgs, send a `POST` request to the `/api/rest/2.0/security/metadata/publish` API endpoint, with the following parameters in the request body. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`metadata` a| __Array of strings__. Array of metadata objects to publish. Specify the ID and type of metadata in each array. The supported metadata object types are: + +* `LIVEBOARD` for Liveboards +* `LOGICAL_TABLES` + +For Models and Tables +* `ANSWER` for Answers + +|`org_identifiers` a|__Array of strings__. Array of Org names or IDs to which you want to publish the object. +|`skip_validation` a|__Boolean__. When set to `true`, it skips validation of objects before publishing. By default, it's set to `false`. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/publish' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata": [ + { + "identifier": "c6ce2676-90be-468a-8d92-c22f1255d9dc", + "type": "LIVEBOARD" + } + ], + "org_identifiers": [ + "MyOrg1", + "MyOrg2", + "MyOrg3" + ] +}' +---- + +If the API request is successful, ThoughtSpot returns a 204 response indicating that the object has been successfully published to the Orgs specified in the request. + +== Verify published objects + +After publishing an object to target Orgs, the administrators with all Orgs access can verify the published object in target Orgs and check the object TML to ensure that the variables are substituted with correct values. + +When published, the object and its dependencies will be visible only to administrators of that specific Org. The administrators can share the objects to other users or user groups in their Org. + +== Synchronize updates + +The published object will be available to users in read-only mode within the target Orgs. While users can interact with the published object, only the original version in the Primary Org is editable. +When the object in the Primary Org is updated, the changes are automatically propagated to the published versions in the target Orgs and will be visible to users upon the next reload. + +== Remove published objects + +To remove published objects from the target Orgs, send a `POST` request to the +++/api/rest/2.0/security/metadata/unpublish+++ API endpoint, with the following attributes in the request body. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description + +|`metadata` a|__Array of strings__. Array of the published objects to remove from the Orgs. Specify the ID and type of metadata. The supported metadata object types are: + +* `LIVEBOARD` for Liveboards + +* `LOGICAL_TABLES` + +For Models and Tables +* `ANSWER` for Answers + +|`org_identifiers` a|__Array of strings__. Specify the Orgs from which you want to remove the published object. + +|`include_dependencies` |__Boolean__. When set to `true`, this attribute unpublishes and removes all dependent objects if no other published object is using them. + +|`force` + +__Optional__ a| __Boolean__. Force deletes the published objects from the Orgs specified in the request. If an Org has new content created from the published object, such as an Answer or Liveboard from a Model published from the Primary Org, the API returns an error unless the `force` attribute is set to `true`. + +Exercise caution when using this option, because it may break the association with objects that reference the published object. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}//api/rest/2.0/security/metadata/unpublish' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "include_dependencies": true, + "metadata": [ + { + "identifier": "Sales_Liveboard", + "type": "LIVEBOARD" + } + ], + "org_identifiers": [ + "MyOrg1", + "MyOrg2" + ] +}' +---- + +If the API request is successful, ThoughtSpot returns a 204 response code indicating that the published object is removed from the target Orgs. \ No newline at end of file diff --git a/modules/ROOT/pages/publishing-overview.adoc b/modules/ROOT/pages/publishing-overview.adoc new file mode 100644 index 000000000..ae94eb639 --- /dev/null +++ b/modules/ROOT/pages/publishing-overview.adoc @@ -0,0 +1,133 @@ += Publishing content to Orgs +:toc: true +:toclevels: 2 + +:page-title: Publishing data +:page-pageid: publish-data-overview +:page-description: Use the publishing feature to distrubute and propagete objects to Orgs within a ThoughtSpot instance. + +The publishing feature [beta betaBackground]^Beta^ enables administrators to efficiently manage and distribute ThoughtSpot metadata objects across multiple Orgs within a multi-tenant instance. + +Unlike the deployment method that relies on TML import and Git integration, publishing allows administrators to create an object in the Primary Org and publish it directly to target Orgs without generating duplicate copies. It also allows dynamic customization of the underlying Table or Connection properties using variables. + +Starting with the 10.10.0.cl release, ThoughtSpot provides a set of REST APIs for administrators to create and assign variables, parameterize object properties, and publish objects from the Primary Org to other Orgs on their instances. + +[IMPORTANT] +==== +The publishing feature—including the REST APIs for variable creation and update, metadata parameterization, and publishing content across Orgs—is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== + +== When to use publishing feature + +ThoughtSpot recommends using the publishing feature if you have a multi-tenant ThoughtSpot instance with Orgs and your deployment requires the same metadata objects across different tenant Orgs. + +//* You have set up multiple environments using Orgs on your ThoughtSpot instance, and you want to publish content to multiple Orgs + + +//For example, you want to publish content from a `development` environment to a `test` or `staging` environment. In such cases, you can set the Primary Org on your instance as the development Org and publish content from the Primary Org to other target Orgs. + +Currently, ThoughtSpot allows publishing content to different instances or Orgs via TML import and Git integration. The Publishing feature automates some of these procedures and simplifies content propagation for large-scale deployments. + +The following table lists the key differences and use cases for both these methods. + +[width="100%" cols="7,7"] +[options='header'] +|===== +|Publishing feature |TML Import/Git-based Deployment and publishing +|Recommended for multi-tenant instances requiring standardized and re-usable content| +If a tenant Org requires unique customizations that cannot be handled by variables, use TML-based deployment to create and maintain a separate object for that Org. +|Allows publishing content from the Primary Org to different Orgs within an instance|Allows publishing content to Orgs within a ThoughtSpot instance, or from one ThoughtSpot instance to another +|Maintains a single source of the object and publishes content to Orgs without creating a duplicate object| Creates a separate copy per Org / per instance and can result in a higher memory usage. +|Allows customizing data properties with variables | Creates new copies per Org or instance and thus allows full customization of objects. +|No change to metadata object IDs and references. Hence, GUID mapping is not required.| Requires xref:guid-mapping.adoc[GUID mapping]. +|===== + +== Parameters and variables + +The Connection and Table objects required for building analytics content can vary between data environments. To customize Connection and Table properties for each Org, you can use variables and parameterize object properties. + +You can create the following types of variables using the xref:variables.adoc[variable API] and use them to parameterize Connection or Table properties either through the xref:metadata-parameterization.adoc[metadata parameterization API] or by directly updating the TML for the Connection or Table. This approach ensures that the published metadata objects dynamically adapt to the configuration of each Org without the need for creating a copy of the object. + +[width="100%" cols="5,7"] +[options='header'] +|===== +|Variable type| Description +|`TABLE_MAPPING`| The **TABLE_MAPPING** variable allow parameterizing the following Table properties: + +** `databaseName` +** `schemaName` +** `tableName` +|`CONNECTION_PROPERTY` a| + +The `CONNECTION_PROPERTY` variables allow parameterizing connection properties. For example, `accountName`, `warehouse`, `user`, `password`, `role` and so on. +| `CONNECTION_PROPERTY_PER_PRINCIPLE` a| + +[NOTE] +This feature is disabled by default. To enable this option, contact ThoughtSpot Support. + +This variable supports modifying connection properties per principal (user or user group). This means you can set different values for connection properties depending on the user or group accessing the connection. For example, `warehouse`, `role`, `user`, `password`. + +The `CONNECTION_PROPERTY_PER_PRINCIPLE` variable does not allow parameterizing core connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration and cannot be set per user or user group. + +|| +|===== + +The following figure illustrates variable substitution in Connections and Tables: + +[.widthAuto] +image::./images/variables.png[Variables] + +== Version control + +For the objects in the Primary Org, you can use the xref:git_integration_overview[Git integration] APIs for development, change tracking, and version control. However, Git integration for the objects published in the target Orgs is not supported. + +== User access to objects +ThoughtSpot administrator with access to all Orgs can publish content from the Primary Org to other Orgs on a ThoughtSpot instance. The administrators will also require edit access to the object and the underlying data source in the Primary Org. + +The visibility of a published object in an Org depends on its sharing settings. Org administrators can view the objects published in their Org and grant view access to other users in their Org by sharing the object. + +== Limitations + +Note the following feature limitations in the beta version: + +* Only ThoughtSpot administrators with access to all Orgs can publish objects. +* Objects can be published only from the Primary Org to other Orgs. +* In the target Orgs, published objects are available in read-only mode. The original object in the Primary Org remains editable by the cluster administrator and users with edit permissions. +* Spotter functionality is not supported for published objects. +* Search data indexing is disabled for published tables. +* Git integration is not supported for published objects. + +[NOTE] +==== +ThoughtSpot is actively working on enhancements to support critical features and key user scenarios. Some of these existing limitations will be addressed in upcoming releases. +==== + +//// +* Cohort publishing is not supported. +* Custom calendars with different metadata across Orgs are not supported. +//// + +== Publishing workflow + +The content publishing process with the new publishing method involves the following steps: + +. xref:intro-thoughtspot-objects.adoc#_content_creation_workflow[Step 1: Create a master object] + +This step involves building Answers and Liveboard from a Model or data object in Primary Org. Ensure that the object references Tables or Connections that can be parameterized with variables. Note that parameterizing default system tables is not supported. + +. xref:variables.adoc[Step 2: Define variables] + +Create a variable for each Org using the `/api/rest/2.0/template/variables/create` API endpoint. For example, you can create a variable for table attributes, such as schema, database, or table name, and assign the variable to the relevant table properties using the metadata parameterization API endpoint. When you publish the object, the object properties with the variables are dynamically assigned appropriate values configured for the Org. + +. xref:metadata-parameterization.adoc[Step 3: Parameterize metadata objects] + +Replace the static values of object properties with variables created from the previous step. You can use the `/api/rest/2.0/metadata/parameterize` API endpoint or directly edit the TML to assign variables to the relevant properties. This step is required to enable the use of the same metadata object across different Orgs, with the actual values being supplied at runtime for each Org. + +. xref:publish-api.adoc[Step 4: Publish the objects] + +Publish the objects from the source Org (Primary Org) to target Orgs using the publish metadata API (`/api/rest/2.0/security/metadata/publish`). + +. xref:publish-api.adoc#_validate_published_objects[Step 5: Verify published objects] + +After publishing an object, verify the published object and the associated TML object in each Org to ensure that the variables are correctly substituted with the appropriate values for that Org. ++ +Try updating the original object in the Primary Org and verify whether the published objects in the target Orgs are updated accordingly. + +The following figure provides a visual representation of the publishing workflow: + +[.widthAuto] +image::./images/publishing-flowchart.png[Publishing process] diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index d8e2e54ce..868534d32 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -278,7 +278,8 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version -a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 +a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 or later +a|ThoughtSpot Cloud: 10.10.0.cl | v2.15.0 or later |==== @@ -289,7 +290,7 @@ a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 |===== |Method|HTTP request -|link:ThoughtSpotRestApi.md#activateUser[activateUser*, window=_blank] |*POST* +|link:ThoughtSpotRestApi.md#activateUser[activateUser, window=_blank] |*POST* /api/rest/2.0/users/activate |link:https://github.com/thoughtspot/rest-api-sdk/blob/release/sdks/java/docs/ThoughtSpotRestApi.md#assignChangeAuthor[assignChangeAuthor^] diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 8c693ce86..d2e33de56 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -223,6 +223,7 @@ a|* ThoughtSpot Cloud release versions: + a|ThoughtSpot Cloud: 10.6.0.cl | v2.12.1 or later a|ThoughtSpot Cloud: 10.8.0.cl | v2.13.1 or later a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 or later +a|ThoughtSpot Cloud: 10.10.0.cl | v2.15.0 or later |==== For information about new features, breaking changes, and deprecated parameters, see xref:rest-apiv2-changelog.adoc[API changelog]. diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index 10c7318d0..56bdaf7b9 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -167,6 +167,7 @@ a| |===== -- + == Custom actions [div boxAuto] @@ -289,6 +290,41 @@ ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/email/{template_identifier}/delete` + +Deletes the existing customized configuration set for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/customization/email/search` + + +Searches the customized configuration set for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ a| ++++Try it out +++ + +a|`POST /api/rest/2.0/customization/email/validate` + + +Validates the customized configuration set for the notification emails. + +|ThoughtSpot Cloud: __10.10.0.cl or later__ a| ++++Try it out +++ +|===== +-- == Groups diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index ae1a4b6d7..652c77d5e 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,36 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 10.10.0.cl, July 2025 + +=== Email template customization APIs: +This release introduces the following new endpoints for email template customization: + +* `POST /api/rest/2.0/customization/email` + +Allows you to personalize the ThoughtSpot notification emails content. +* `POST /api/rest/2.0/customization/email/{template_identifier}/delete` + +Removes the customizations done for the ThoughtSpot notification emails. +* `POST /api/rest/2.0/customization/email/search` + +Allows searching the email customization configuration if any set for ThoughtSpot. +* `POST /api/rest/2.0/customization/email/validate` + +Validates the email customization configuration if any set for ThoughtSpot. + +=== Group API + +The `/api/rest/2.0/groups/search` endpoint now supports the following new options in group search API requests: + +* `include_users` + +When set to `true`, it includes user details in the group search API response. +* `include_sub_groups` + +When set to `true`, it includes sub-groups in the group search response. + +=== Schedule API +You can now specify the `personalised_view_id` of a Liveboard in API requests to the following schedule APIs: + +* `POST /api/rest/2.0/schedules/create` +To schedule a job for a personalized view of the Liveboard, specify the `personalised_view_id`. +* `POST /api/rest/2.0/schedules/{schedule_identifier}/update` +To update schedule details for a specific view of the Liveboard, specify the `personalised_view_id`. == Version 10.9.0.cl, June 2025 @@ -121,9 +151,11 @@ The `/api/rest/2.0/report/answer` and `/api/rest/2.0/report/liveboard` now allow * `number_format_locale` * `date_format_locale` +//// === Custom authentication token API The `/api/rest/2.0/auth/token/custom` API endpoint now allows you to define the `reset_option` to specify if the attributes assigned to the token should persist or be reset. +//// === Custom object ID in TML and Metadata APIs diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 3632eda3e..809372208 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -306,5 +306,3 @@ Safari blocks all third-party cookies and does not support partitioned cookies. == Trusted authentication See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management]. - - diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc new file mode 100644 index 000000000..f1c95abf6 --- /dev/null +++ b/modules/ROOT/pages/variables.adoc @@ -0,0 +1,339 @@ += Define variables +:toc: true +:toclevels: 2 + +:page-title: Define template variables +:page-pageid: variables +:page-description: Use the variables REST API to create and update variables for publishing content across Orgs + +Variables allow you to define dynamic placeholders for specific properties of metadata objects such as Connections and Tables. By using variables, you can dynamically assign different values to the object properties for each Org and yet use a single source with a consistent data structure across different Orgs. + +Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties. + +== Before you begin + +* Ensure that you have edit access to the metadata objects to which you want to assign variables. +* Ensure that you have administration privileges to create, edit, or delete a variable. + +== Create a variable +To create a variable, send a `POST` request to the +++/api/rest/2.0/template/variables/create +++ API endpoint, with the following parameters in the request body. + +=== Request parameters +In your `POST` request body, you can include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`type` a| __String__. Type of the variable. The API supports the following types of variables: + +* `TABLE_MAPPING` + +To map Tables properties to variables. + +* `CONNECTION_PROPERTY` + +To define variables for connection properties. This variable allows editing connection properties such as `accountName`, `warehouse`, `user`, `password`, `role` and so on. +* `CONNECTION_PROPERTY_PER_PRINCIPAL` + +To define variables for connection properties per user or user group. This variable allows modifying connection properties such as `warehouse`, `role`, `user`, `password`. The `CONNECTION_PROPERTY_PER_PRINCIPLE` variables d not support modifying core connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration and cannot be set per user or user group. + +[NOTE] +This feature is disabled by default. To enable this option, contact ThoughtSpot Support. + +|`name`| __String__. Name of the variable. For example, `schema_var`. Note that the name must be unique across all Orgs within the instance. +|`sensitive` __Optional__ |__Boolean__. Indicates if the variable contains sensitive values such as passwords. +|`values` __Optional__ a|__Array of strings__. Define the variable attributes. Although it's optional, make sure that you set the value for an Org before publishing content to that Org. + +The `values` array includes the following attributes: + +* `value` __String__ + +The value for the variable. For the primary Org, you can define the variable value as `Primary`. For destination Orgs, specify a separate value, for example, `Org1`. + +* `org_identifier` __String__ + +ID or name of the Org. For primary Org, specify `primaryOrg` or Org 0. + +* `principal_type` and `principal_identifier` __Optional__ + +Applicable if the variable type is set as `CONNECTION_PROPERTY_PER_PRINCIPAL`. Specify the principal type and the ID or principal to set connection properties per user or user group. +* `priority` __Optional__ + +Applicable if the variable type is set as `CONNECTION_PROPERTY_PER_PRINCIPAL`. The priority assigned to this value. If there are two matching values, the one with a higher priority will be used. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "type": "TABLE_MAPPING", + "name": "schema_var", + "sensitive": false, + "values": [ + { + "value": "primary", + "org_identifier": "primaryOrg" + }, + { + "value": "TargetOrg1", + "org_identifier": "MyOrg1" + }, + { + "value": "TargetOrg2", + "org_identifier": "MyOrg2" + } + ] +}' +---- + +=== Example response + +If the API request is successful, the following response is returned: + +[source,JSON] +---- +{ + "id": "180a9cd3-8605-445b-8b70-aa0bcef5dfb0", + "name": "schema_var", + "variable_type": "TABLE_MAPPING", + "sensitive": false, + "values": [ + { + "value": "primaryOrg", + "org_identifier": "Primary", + "principal_type": null, + "principal_identifier": null, + "priority": null + } + ] +} +---- + +Note the variable ID. + +== Update variable values + +To update a variable, the following APIs are available: + +* `+++POST /api/rest/2.0/template/variables/update+++` ++ +Allows adding, removing, and replacing values for multiple variables in a single API call. + +* `+++POST /api/rest/2.0/template/variables/{identifier}/update+++` ++ +Allows adding, removing, and replacing values of a specific variable. + +=== Update properties of a variable + +To update the properties of a variable, send a `POST` request to `/api/rest/2.0/template/variables/{identifier}/update` with the following parameters in the request body. Specify the variable ID in the `{identifier}` path parameter. + +=== Request parameters + +In your `POST` request body, you can include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`identifier` __String__| ID or name of the variable. Include the variable ID as a path parameter in the request body. +|`name` __String__ | New name for the variable. Specify a name if you want to rename the variable. +|`Operation` __String__ a| Specify the update operation type. The following options are available: + +* `ADD` + +Adds new values. Use this operation type if you want to add new attributes to the variable. +* `REMOVE` + +Removes the values assigned to the variable specified in the API request. +* `REPLACE` + +Replaces the existing attributes with new values. +|values + +__Optional__ a|__Array of strings__. Modify the values of the variable specified in the API request. The `values` array includes the following attributes: + +* `value` __String__ + +The new value for the variable. for example, `staging1`. +* `org_identifier` __String__ + +ID or name of the Org. For primary Org, specify `primaryOrg` or Org 0. +* `principal_type` and `principal_identifier` __Optional__ + +Principal attributes such as user and user group. These attributes are applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. +* `priority` __Optional__ + +The priority assigned to this value. Applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. +|===== + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/a1b2c3d4-e5f6-7890-abcd-ef1234567890/update' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "operation": "REPLACE", + "name": "TableVar", + "values": [ + { + "value": "MyOrg`", + "org_identifier": "MyOrg1" + } + ] +}' +---- + +If the update operation is successful, the API returns a 204 response to indicate that the variable was updated successfully. + +=== Update properties of multiple variables + +To update properties of multiple variables in a single call, send a `POST` request to the `/api/rest/2.0/template/variables/update` API endpoint with the following parameters in the request body. + + +=== Request parameters + +In your `POST` request body, you can include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`variable_updates` a|Array of inputs for the variable update. Allows updating the following properties for each variable ID in the array: + +* `identifier` __String__. + +ID or name of the variable to update. +* `variable_values` __Optional__ + +__Array of strings__. Assign new values for the variable attributes. + +** `value` __String__ + +The new value for the variable. for example, `staging1`. +** `org_identifier` __String__ + +ID or name of the Org. For primary Org, specify `primaryOrg` or Org 0. +** `principal_type` and `principal_identifier` __Optional__ + +Principal attributes such as user and user group. These attributes are applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. +** `priority` __Optional__ + +The priority assigned to this value. Applicable to the `CONNECTION_PROPERTY_PER_PRINCIPAL` variable type. +|`Operation` __String__ a| Specify the update operation type. The following values are available: + +* `ADD` + +Adds new values. Use this operation type if you want to add new attributes to the variable. +* `REMOVE` + +Removes the values assigned to the variable specified in the API request. +* `REPLACE` + +Replaces the existing attributes with new values. +|===== + +=== Request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/update' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "variable_updates": [ + { + "variable_identifier": "e61ace04-6651-4725-9174-90ce33423ef9", + "variable_values": [ + { + "value": "prod1", + "org_identifier": "ProdOrg1" + }, + { + "value": "devOrg1", + "org_identifier": "devOrg" + } + ] + } + ], + "operation": "REPLACE" +}' +---- + +If the update operation is successful, the API returns a 204 response to indicate that the variable was updated successfully. + +== Get details of variables +To get a list of variables or the details of a specific variable, send a `POST` request to the `+++/api/rest/2.0/template/variables/search+++` API endpoint. + +To search for a variable, specify the following parameters in your API request: + +* variable type +* variable ID +* Name pattern + +Specify partial name of the variable. For wildcard search, use `%`. +* output format + +Specify one of the following values for output format: +** `METADATA_ONLY` (default) + +Returns only the variable metadata +** `METADATA_AND_VALUES` + +Returns variable metadata and values +** `EDITABLE_METADATA_AND_VALUES` + +Returns metadata details, such as name, type, default value, and whether the variable is editable, and the current values of variables that can be edited. + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/search' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "record_offset": 0, + "record_size": 10, + "output_format": "EDITABLE_METADATA_AND_VALUES", + "variable_details": [ + { + "type": "TABLE_MAPPING" + } + ] +}' +---- + +If the request is successful, the API returns the variable data in the response: + +[source,JSON] +---- +[ + { + "id": "180a9cd3-8605-445b-8b70-aa0bcef5dfb0", + "name": "schema_var", + "variable_type": null, + "sensitive": null, + "values": [ + { + "value": "primaryOrg", + "org_identifier": "Primary", + "principal_type": null, + "principal_identifier": null, + "priority": null + }, + { + "value": "MyOrg1", + "org_identifier": "MyOrg1", + "principal_type": null, + "principal_identifier": null, + "priority": null + }, + { + "value": "MyOrg2", + "org_identifier": "MyOrg2", + "principal_type": null, + "principal_identifier": null, + "priority": null + }, + ] +---- + +== Delete a variable + +To delete a variable, send a `POST` request to the `+++/api/rest/2.0/template/variables/{identifier}/delete+++` API endpoint, with the variable ID in the path parameter. + +Note that you can delete only one variable at a time. + +If the variable is used by other objects, make sure to update the properties of the object before deleting the variable. + +[source,cURL] +---- +curl -X POST \ +--url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/180a9cd3-8605-445b-8b70-aa0bcef5dfb0/delete' \ +-H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +If the API request is successful, ThoughtSpot returns a 204 response code. + diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 6ab2c4924..7f3db5c62 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,41 @@ This page lists new features, enhancements, and deprecated functionality in ThoughtSpot Embedded instances. +== Version 10.10.0.cl + +=== Email customization per Org [beta betaBackground]^Beta^ +ThoughtSpot embedded users can now customize their automated email notifications for each Org through REST APIs v2. You can customize features such as the company logo, style, and fonts, visibility of components in the template, and ThoughtSpot-specific content in notification emails, thus ensuring a consistent brand experience. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + +[NOTE] +==== +These APIs are currently in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== + +=== Publishing content to Orgs [beta betaBackground]^Beta^ + +The publishing feature [beta betaBackground]^Beta^ enables administrators to publish objects from the Primary Org to other Orgs within a multi-tenant instance. This feature simplifies the deployment process for ThoughtSpot administrators, especially when the same object needs to be made available to multiple Orgs within an instance. It also eliminates the need to create duplicate copies of the object, thereby optimizing memory usage. + +The publishing feature includes a set of REST APIs that ThoughtSpot administrators can use to create and assign variables, parameterize properties of underlying data objects such as Connections and Tables per Org, and publish objects from the Primary Org to other Orgs on their instance. For more information, see xref:publishing-overview.adoc[Publishing content to Orgs]. + +[NOTE] +==== +The publishing feature is in beta and turned off by default on ThoughtSpot instances. To enable this feature on your instance, contact ThoughtSpot Support. +==== + +//// +=== Set primary action on a Liveboard visualization +In the default view, visualizations on a Liveboard include a primary action and a few other actions in the More options (`...`) menu. If Spotter is enabled on your instance, *Spotter* is set as a primary action on all visualizations in a Liveboard and the *Explore* action moves to the More options (`...`) menu. In such cases, if you want to replace the default action for primary button, use the `primaryAction` setting in the SDK. +//// + +=== Visual Embed SDK + +For information about the new features and enhancements introduced in Visual Embed SDK version 1.39.x, see xref:api-changelog.adoc[Visual Embed changelog]. + +=== REST API +For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + == Version 10.9.0.cl === String IDs for customizing text strings @@ -68,10 +103,6 @@ For information about the new features and enhancements introduced in Visual Emb === REST API For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. -//// -=== Set primary action on a Liveboard visualization -In the default view, visualizations on a Liveboard include a primary action and a few other actions in the More options (`...`) menu. If Spotter is enabled on your instance, *Spotter* is set as a primary action on all visualizations in a Liveboard and the *Explore* action moves to the More options (`...`) menu. In such cases, if you want to set *Explore* or any other action as a primary button, you can use the `primaryAction` setting in the SDK. -//// == Version 10.8.0.cl diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 823fdac46..a2933fad7 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -35,22 +35,10 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.9.0.cl', + label: '10.10.0.cl', link: ' ', subLabel: 'Cloud (Latest)', }, - { - label: '10.8.0.cl', - link: '10.8.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-10-8-0-cl.vercel.app/docs', - }, - { - label: '10.6.0.cl', - link: '10.6.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-10-6-0-cl.vercel.app/docs', - }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', diff --git a/static/doc-images/images/email-template.png b/static/doc-images/images/email-template.png new file mode 100644 index 000000000..e1c71006a Binary files /dev/null and b/static/doc-images/images/email-template.png differ diff --git a/static/doc-images/images/publishing-flowchart.png b/static/doc-images/images/publishing-flowchart.png new file mode 100644 index 000000000..74f53f34e Binary files /dev/null and b/static/doc-images/images/publishing-flowchart.png differ diff --git a/static/doc-images/images/variables.png b/static/doc-images/images/variables.png new file mode 100644 index 000000000..513839b86 Binary files /dev/null and b/static/doc-images/images/variables.png differ