diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 1edcfc119..03b59b71c 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -208,13 +208,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/development-and-deployment.adoc b/modules/ROOT/pages/development-and-deployment.adoc index 74ea2ad00..0582582b0 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 default (Primary) Org to other Orgs on a multi-tenant instance. The publishing feature [beta betaBackground]^Beta^ enables administrators to create a single master object in the Primary Org, propagate it to other Orgs within the instance, and synchronize updates across all target Orgs. +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..888d4d40c --- /dev/null +++ b/modules/ROOT/pages/metadata-parameterization.adoc @@ -0,0 +1,136 @@ += 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. + +To parameterize the properties of a Connection or Table object programmatically, use the +++/api/rest/2.0/metadata/parameterize+++ API endpoint. + +[NOTE] +==== +ThoughtSpot does not support parameterizing default system tables. +==== + +== Before you begin + +* Ensure that that xref:variables.adoc[variables are available] on your instance. You can use the `/api/rest/2.0/template/variables/search` API to xref:variables.adoc#_get_details_of_variables[get a list of variables]. +* Ensure that you have edit access to the Connections and Tables to which you want to assign variables. + +== Parameterize object properties +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="1,4"] +[options='header'] +|===== +|Parameter|Description +|`metadata_type` 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 +|`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 +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` 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 + +This is an optional attribute. However, if you have multiple objects with same name and you have specified the object name as the identifier in `metadata_identifier`, 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/publish-api.adoc b/modules/ROOT/pages/publish-api.adoc new file mode 100644 index 000000000..39919b24a --- /dev/null +++ b/modules/ROOT/pages/publish-api.adoc @@ -0,0 +1,128 @@ += 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 propagation from the Primary Org to other Orgs in a multi-tenant instance. + +For large-scale deployments that require similar analytics content, you can use the xref:variables.adoc[variables] to parameterize object properties to ensure that each Org receives a version of the object that is correctly configured for its environment. + +To publish objects programmatically from the Primary Org to one or several target Orgs, 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, 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 and Answers from the Primary Org to one or several destination Orgs, while ensuring that the variables assigned to metadata objects are substituted with correct values for each Org. + +To publish an object, 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": [ + "Staging1", + "Staging2", + "ProdOrg1" + ] +}' +---- + +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`, the published object with all its dependent objects is removed from the Orgs. If the dependent objects are associated to other objects in the Orgs, they will be retained in the Orgs. +|`force` + +__Optional__ a| __Boolean__. Removes the published objects from the Orgs. Exercise caution when using this option, because it will break the object references in the currently published Orgs. +|===== + +=== 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": [ + "testOrg", + "stagingOrg" + ] +}' +---- + +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..57ea5327f --- /dev/null +++ b/modules/ROOT/pages/publishing-overview.adoc @@ -0,0 +1,116 @@ += 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 propagate objects such as Liveboards and Answers across multiple Orgs within a multi-tenant ThoughtSpot instance. + +Unlike the deployment method that relies on TML import and Git integration, the publishing feature allows administrators to create an object in the Primary Org and publish it directly to target Orgs without creating duplicate copies of the object. The publishing feature also provides the ability to customize the object properties of the underlying Table or Connection using variables. + +ThoughtSpot provides a set of REST APIs to manage the publishing workflow in the 10.10.0.cl release. Administrators can use these APIs to create and assign variables, parameterize object properties, and publish objects seamlessly from the Primary Org to other target Orgs on a ThoughtSpot instance. + + +[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 in the following scenarios: + +* 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. 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 +|Automatically maps objects using variables and object IDs| 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. This approach ensures that metadata objects dynamically adapt to the configuration of each Org, supporting multi-tenant scenarios and reducing the need to duplicate objects for each Org + +You can create the following types of variables using xref:variables.adoc[variable API] and use these variables to parameterize Connection or Table properties via xref:metadata-parameterization.adoc[metadata parameterization API]: + +* `CONNECTION_PROPERTY` + +The `CONNECTION_PROPERTY` variables allow parameterizing connection properties such as `accountName`, `warehouse`, `user`, `password`, `role` and so on. + +* `TABLE_MAPPING` + +The **TABLE_MAPPING** variable allow parameterizing the following Table properties: + +** `databaseName` +** `schemaName` +** `tableName` + +* `CONNECTION_PROPERTY_PER_PRINCIPLE` + +Allows parameterizing connection properties per user or user group. However, it doesn't allow parameterizing core Connection properties such as `accountName`, `host`, or `port`. These properties must be derived from the connection configuration. + +This feature is disabled by default. To enable this option, contact ThoughtSpot Support. + +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 or UI for development, change tracking, and version control. However, Git integration is not supported for objects published in the target Orgs. + +== 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: + +* Only ThoughtSpot administrators with access to all Orgs can publish objects. +* Objects can be published only from the Primary Org to other Orgs. Publishing from non-default Orgs is not supported. +* 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. + +//// +* 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. + +. xref:variables.adoc[Step 2: Define variables] + +Create a variable with placeholder values for each Org and assign values using `/api/rest/2.0/template/variables/create` API. 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 in via metadata parameterization API. When you publish the object, it will use the variable, and the correct value for that variable will be substituted based on 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 to assign variables to the relevant object 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 and update objects] + +After publishing an object, verify the published 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 updates are automatically propagated to the target orgs and the published objects are synchronized. + +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/variables.adoc b/modules/ROOT/pages/variables.adoc new file mode 100644 index 000000000..65f56612a --- /dev/null +++ b/modules/ROOT/pages/variables.adoc @@ -0,0 +1,259 @@ += 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 your analytics content to other Orgs, you must define and assign variables to metadata objects. + +== 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, 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: + +* `CONNECTION_PROPERTY` + +To define variables for connection properties. This variable allows editing core connection properties such as `accountName`, `warehouse`, `user`, `password`, `role` and so on. +* `TABLE_MAPPING` + +To map Tables properties to variables. +* `CONNECTION_PROPERTY_PER_PRINCIPAL` + +To define variables for connection properties per user or user group. 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 a|__Array of strings__. Assign values for the variable. You must specify the variable values for each Org to which you want to publish content. 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, `staging1`. +* `org_identifier` __String__ + +ID or name of the Org. For primary Org, specify `primaryOrg` or Org 0. +* `principal_type` and `principal_identifier` __Optional__ + +Specify if the variable should be applied per user or user group. Based on the principal type, specify the ID or name of the user or user group. These attributes are used if the variable type is `CONNECTION_PROPERTY_PER_PRINCIPAL` +* `priority` __Optional__ + +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": "staging" + }, + { + "value": "TargetOrg2", + "org_identifier": "prod" + } + ] +}' +---- + +=== 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 modifying properties 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 modified properties. Specify the variable ID in the `{identifier}` path parameter. + +[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": "schema_var1", + "values": [ + { + "value": "stagingOrg1", + "org_identifier": "staging" + } + ] +}' +---- + +=== 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 modified parameters for each `value` array in the request body. + +[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 JSON array of variables with the new values. + +== 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 only the variable metadata and values that are editable + +[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": "test", + "org_identifier": "testOrg", + "principal_type": null, + "principal_identifier": null, + "priority": null + }, + { + "value": "staging", + "org_identifier": "StagingOrg", + "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/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