Tse publishing

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]

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].

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 +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fparameterize-metadata">/api/rest/2.0/metadata/parameterize</a>+++ 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 +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Funparameterize-metadata">/api/rest/2.0/metadata/unparameterize</a>+++ 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.

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 +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Fpublish-metadata">/api/rest/2.0/security/metadata/publish </a>+++ 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 +++<a href="{{navprefix}}/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fsecurity%2Funpublish-metadata">/api/rest/2.0/security/metadata/unpublish</a>+++ 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.