Merge pull request #406 from thoughtspot/obj_id_in_sdlc

Obj id in sdlc

Author: ShashiSubramanya

modules/ROOT/pages/intro-thoughtspot-objects.adoc

@@ -6,41 +6,50 @@
 :page-pageid: thoughtspot-objects
 :page-description:
 
-ThoughtSpot is a business intelligence and data analytics platform that helps you explore, analyze and share real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides a robust and guided search functionality using which business users can search data instantly. ThoughtSpot is different from other BI tools, because ThoughtSpot Search is the core of the ThoughtSpot system.
+ThoughtSpot is a business intelligence and data analytics platform that helps you explore, analyze, and share real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system.
 
 Before you look at the rest of the developer documentation, please review this page to understand how ThoughtSpot works relative to other tools you may be familiar with.
 
 == Object model hierarchy
 
-The following figure illustrates the object model hierarchy in ThoughtSpot.
+The following figure illustrates the object model hierarchy in ThoughtSpot within a single xref:orgs.adoc[Org]:
 
 image::./images/object_model_hierarchy.png[Object Model Hierarchy]
 
+== Object identifiers
+Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs.
+
+Objects have an additional `obj_id` property that is *user-settable* and *unique per Org*. It appears as `metadata_obj_id` in responses from the `/metadata/search` REST API.
+
+Each Org can have one object with a particular `obj_id`. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID.
+
+`obj_id` allows you to export TML that can be imported into any Org on any instance, letting ThoughtSpot determine the object's GUID automatically without requiring any additional effort on your part.
+
 == Data modeling
-You must create a data model comprising at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] with one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to begin using link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content.
-Most often, there will be multiple *Tables*, with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, with a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] bringing those tables together into a presentable analytic data model for the end-users.
+You must create a data model with at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] before you can use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content.
+Most often, there will be multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users.
 
-Data engineers with *Can manage data* privilege can add connections either link:https://docs.thoughtspot.com/cloud/latest/connections[in the UI, window=_blank] or via xref:connections.adoc[REST API]. Connections are owned and accessible only to their creator, who then imports *Tables* from the connection. Once imported, tables can be shared with other ThoughtSpot groups and users.
+Data engineers with the *Can manage data* privilege can add connections either link:https://docs.thoughtspot.com/cloud/latest/connections[in the UI, window=_blank] or via xref:connections.adoc[REST API]. Connections are owned and accessible only to their creator, who then imports *Tables* from the connection. Once imported, tables can be shared with other ThoughtSpot groups and users.
 
 *Tables* can have link:https://docs.thoughtspot.com/cloud/latest/security-rls[Row Level Security (RLS), window=_blank] rules that filter the data results based on the signed-in link:https://docs.thoughtspot.com/cloud/latest/user-management[username, window=_blank] or the link:https://docs.thoughtspot.com/cloud/latest/group-management[ThoughtSpot groups, window=_blank] to which the user belongs, and those rules apply to any *Model* that uses the *Table*.
 
 [NOTE]
 ====
-Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0.cl and later release versions.
+Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0.cl and later versions.
 ====
 
 === Data modeling workflow
 1. Create a *connection* to a cloud data warehouse.
 2. Import *tables* from the *connection*.
-3. Create *Models* (analytic data models) based on tables. You can also create link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank] and add tables.
+3. Create link:https://docs.thoughtspot.com/cloud/latest/models[*Models*, window=_blank] (analytic data models) based on tables.
 4. Create link:https://docs.thoughtspot.com/cloud/latest/views[ThoughtSpot Views, window=_blank] or link:https://docs.thoughtspot.com/cloud/latest/sql-views[SQL Views, window=_blank] as necessary.
 
-ThoughtSport also supports programmatic deployment of data models via link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] and table import from link:https://docs.thoughtspot.com/cloud/latest/dbt-integration#integrate[dbt, window=_blank].
+ThoughtSpot also supports programmatic deployment of data models via link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] and table import from link:https://docs.thoughtspot.com/cloud/latest/dbt-integration#integrate[dbt, window=_blank].
 
 == Content creation
-ThoughtSpot Search data creates a single table or chart view based on the query in the search bar and other configurations to the view made after the search results are visible.
+ThoughtSpot Search data creates a table or chart view based on the query in the search bar and any additional view configuration applied after the search results are displayed.
 
-Search data serves the role of report builder or widget designer, while *Liveboards* serve the role of dashboards in other tools. A single search can be saved as an link:https://docs.thoughtspot.com/cloud/latest/answers[Answer, window=_blank] object, or the search result can be pinned to a Liveboard.
+Search data serves the role of report builder or widget designer, while *Liveboards* serve the role of dashboards in other tools. A single search can be saved as a link:https://docs.thoughtspot.com/cloud/latest/answers[*Answer*, window=_blank] object, or the search result can be pinned to a Liveboard.
 
 A link:https://docs.thoughtspot.com/cloud/latest/liveboard[Liveboard, window=_blank] is a collection of many visualizations presented in a defined layout. You do not create the visualizations on a Liveboard directly; they are created from search data results and then pinned to a Liveboard. You can create a new Liveboard from the *Liveboards* page and then add a visualization from the search data result, or you can create a new Liveboard when pinning an Answer retrieved from search data.
 
@@ -51,8 +60,8 @@ To create content:
 1. Use the link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] functionality to build visualizations from data sources such as *Models* or *Views*.
 2. Save the search result as an *Answer* or pin it to a Liveboard as a visualization.
 
-=== Visualizations on a Liveboard 
-You can add any number of visualizations retrieved from the search to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of the objects saved as *answers*.
+=== Visualizations on a Liveboard
+You can add any number of visualizations from search results to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as *Answers*.
 
 Each time you pin a search result, a separate new visualization is created on the Liveboard.
 
@@ -72,38 +81,40 @@ A tag object is created by the administrator, is visible to all users, and can b
 Tag search is always an *OR* operation: filtering on multiple tags results in all objects with any of the tags, not just those with all of the specified tags.
 
 == Access control (sharing)
-ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/data-security[access control model, window=_blank] works by an `author` or `administrator` sharing objects to link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[ThoughtSpot groups, window=_blank] or other individual users:
+ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/data-security[access control model, window=_blank] works by having an `author` or `administrator` share objects with link:https://docs.thoughtspot.com/cloud/latest/groups-privileges[ThoughtSpot groups, window=_blank] or individual users:
 
 * The creator of an object is referred to as the *author*.
 * The author can share the object with their groups using the *Shareable* property.
 * The author can share the object with other users in *Shareable* groups that the *author* belongs to, and if the other *user* is also marked *Shareable*.
 
-An administrator user can share any object with any group or user with no restrictions. ThoughtSpot administrators can add users locally link:https://docs.thoughtspot.com/cloud/latest/user-management[in the UI, window=_blank] or via xref:user-api.adoc[REST API]. Similarly, they can manage groups and sharing privileges by using the *Groups* feature in the UI or via REST API.
+An administrator can share any object with any group or user without restrictions. ThoughtSpot administrators can add users locally link:https://docs.thoughtspot.com/cloud/latest/user-management[in the UI, window=_blank] or via xref:user-api.adoc[REST API]. Similarly, they can manage groups and sharing privileges by using the *Groups* feature in the UI or via REST API.
 
 === Single sign-on
-If xref:configure-saml.adoc[SAML] or xref:configure-oidc.adoc[OpenID Connect (OIDC)] integration support is enabled on your instance, users that authenticate to external identity providers (IdP) can log in to ThoughtSpot with their Single Sign-On credentials.
-Embedded ThoughtSpot instances also support the xref:trusted-authentication.adoc[trusted authentication] method to sign in their application users.
+If xref:configure-saml.adoc[SAML] or xref:configure-oidc.adoc[OpenID Connect (OIDC)] integration is enabled on your instance, users who authenticate with external identity providers (IdP) can log in to ThoughtSpot with their Single Sign-On credentials.
+Embedded ThoughtSpot instances also support the xref:trusted-authentication.adoc[trusted authentication] method to sign in application users.
 
 == Object properties in REST API
-The object representations in ThoughtSpot REST API include the following properties:
+Object representations in the ThoughtSpot REST API include the following properties:
 
 * `id` +
-GUID of the object. Unique within a given ThoughtSpot instance
+GUID of the object. Unique within a given ThoughtSpot instance.
+* `obj_id` +
+User-defined string identifier for the object. Unique within a given Org.
 * `author` +
 GUID of the user who created / uploaded the object, or had the object transferred to them.
 * `owner` +
-GUID representing the relationship between hierarchical objects, For example, a *column* would have the GUID of a *Table* or *Model* as owner.
+GUID representing the relationship between hierarchical objects. For example, a *column* would have the GUID of a *Table* or *Model* as owner.
 * `created` +
-timestamp of object creation
+Timestamp of object creation.
 * `modified` +
-timestamp from last time object was modified
+Timestamp of the last time the object was modified.
 * `modifiedBy` +
-GUID of the user who last modified the object
+GUID of the user who last modified the object.
 * `tags` +
-An array of tag objects representing the tags assigned to the object.
+Array of tag objects representing the tags assigned to the object.
 
 == Object names in REST API v1
-The object type names in the ThoughtSpot REST API v1 differ from the current names seen in the ThoughtSpot UI. Data objects have both a `type` and a `subtypes` within the REST API, allowing you to request all valid data objects or specify the individual subtype.
+Object type names in ThoughtSpot REST API v1 differ from the current names shown in the ThoughtSpot UI. Data objects have both a `type` and a `subtypes` field in the REST API, allowing you to request all valid data objects or specify an individual subtype.
 
 The following notation is used in REST API v1 for object types:
 
@@ -122,7 +133,7 @@ The following notation is used in REST API v1 for object types:
 * *Users*: `USER`
 * *Groups*: `USER_GROUP`
 
-Column and join objects with their own GUIDs do exist within the ThoughtSpot system, but they are connected to *Tables*,  *Models*, or other data objects.  Columns and joins can be viewed or modified only within the context of the data object to which they belong.
+Column and join objects with their own GUIDs do exist within the ThoughtSpot system, but they are connected to *Tables*, *Models*, or other data objects. Columns and joins can be viewed or modified only within the context of the data object to which they belong.
 
 == Related resources