diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index da7ec9f9f..3b1570542 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -45,7 +45,7 @@ customizations to the new answers from an embedded Search data interface at init The `visualOverrides` object provides the following customization controls to modify the chart and table display: -* `legend`: control legend visibility, position, and color palette of charts. +* `legend` to control legend visibility, position, and color palette of charts. * `dataLabel` attribute for data labels and per-column label filters. * `display` attributes for such as regression line overlay and grid line visibility in charts and table themes and content density in tables. * `axis` property for axis name and label visibility and fixed y-axis range. @@ -86,7 +86,6 @@ For more information, see xref:embed-spotter.adoc#fileUpload[Allowing file uploa |==== - == Version 1.48.x, May 2026 [width="100%" cols="1,4"] |==== @@ -155,8 +154,6 @@ EmbedEvent:: The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to dispatch host events during the initial load without race conditions. This is particularly useful for Spotter, where host events such as `HostEvent.ResetSpotterConversation` may be triggered immediately after load. * `EmbedEvent.Error` + The `EmbedEvent.Error` now fires on HostEvent payload validation failures. -* `EmbedEvent.ChangePersonalizedView` + -Emits when a user selects a different Personalized View or resets to default. HostEvent:: * `HostEvent.GetExportRequestForCurrentPinboard` [.version-badge.breaking]#Breaking# + @@ -164,8 +161,17 @@ The response payload of the `GetExportRequestForCurrentPinboard` passthrough host event has been updated to include a `type` discriminator field, making it consistent with the shape of other host event responses. It now returns `{ data: { v2Content }, type }` instead of `{ v2Content }` directly. This enhancement introduces a breaking change for any code that reads `result.v2Content` directly. Update your integration workflows to use `result.data.v2Content`. + +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +===== Personalized View selection via host event + +* `EmbedEvent.ChangePersonalizedView` + +Emits when a user selects a different Personalized View on an embedded Liveboard, or resets to the default view. For more information, see xref:EmbedEvent.adoc#_changepersonalizedview[EmbedEvent reference documentation]. + * `HostEvent.SelectPersonalizedView` + -Triggers the selection of a specific Personalized View and resets the default view on a Liveboard. +The SDK introduces `HostEvent.SelectPersonalizedView` to programmatically switch the active Personalized View on an embedded Liveboard from the host application. For more information, see xref:HostEvent.SelectPersonalizedView[HostEvent reference documentation]. ⚠️Deprecated events and action IDs️:: The following events are deprecated and replaced with new event IDs. @@ -177,7 +183,6 @@ The following events are deprecated and replaced with new event IDs. * `Action.PersonalisedViewsDropdown`. Use `Action.PersonalizedViewsDropdown`. * `Action.OrganiseFavourites`. Use `Action.OrganizeFavorites`. - |==== @@ -997,7 +1002,6 @@ Can be used to show or hide the *Verified Liveboard* banner. * `hidehomepageleftnav` * `hideorgswitcher` * `reorderedhomepagemodules` -* `hiddenhomeleftnavitems` * `HomeLeftNavItem` For more information, see xref:full-app-customize.adoc[Customize full application embedding] and xref:AppViewConfig.adoc[AppViewConfig]. @@ -1272,7 +1276,6 @@ Use the following action enumeration members instead of `Action.Download` to sho * `Action.DownloadAsXlsx` * `Action.DownloadAsPng` -+ To disable or hide download actions, you can use `Action.Download` in the `disabledActions` and `hiddenActions` arrays respectively. However, if you are using the `visibleActions` array to show or hide actions on a visualization or Answer, include the following download action enumerations along with `Action.Download` in the array: + ** `Action.DownloadAsCsv` + @@ -1314,7 +1317,6 @@ For more information, see xref:css-customization.adoc[Customize CSS]. |[tag redBackground]#BREAKING CHANGE# a|The new Liveboard experience mode introduces changes to the data format of the JSON response payload triggered by callback custom actions. For example, the `reportBookData`, and `vizData` attributes are modified, and the custom action `id` now is part of the data attribute. These changes may break your current custom action event handlers. For interoperability, we recommend adding the data attribute to `payload` in your code as shown in the example here: [source,JavaScript] - ---- liveboardEmbed.on(EmbedEvent.CustomAction, payload => { if (payload.id === "callback-action-id" \|\| payload.data.id === "callback-action-id") { diff --git a/modules/ROOT/pages/events-hostEvents.adoc b/modules/ROOT/pages/events-hostEvents.adoc index b397dec92..732726929 100644 --- a/modules/ROOT/pages/events-hostEvents.adoc +++ b/modules/ROOT/pages/events-hostEvents.adoc @@ -7,9 +7,9 @@ :page-description: Events allow the host application to trigger actions in or payloads from the embedded ThoughtSpot components. [#host-events] -Host events provide programmatic entry points to actions that your host or embedding application can trigger into the embedded ThoughtSpot iframe to perform the same operations a user can perform in the UI, such as opening filters, editing, saving, pinning, drilling, or navigating to an answer. +Host events provide programmatic entry points to actions that your host or embedding application can trigger in the embedded ThoughtSpot iframe to perform the same operations a user can perform in the UI, such as opening filters, editing, saving, pinning, drilling, or navigating to an answer. -Host events use the `.trigger()` method to send the event message to embedded ThoughtSpot components in the `.trigger(hostEvent, data)` format. The host events are part of the *HostEvent* object; for example, `HostEvent.SetVisibleTabs`. +Host events use the `.trigger()` method to send the event message to embedded ThoughtSpot components in the `.trigger(hostEvent, data)` format. The host events are part of the `HostEvent` object; for example, `HostEvent.SetVisibleTabs`. == Event categories @@ -24,7 +24,7 @@ Host events can be categorized based on their schema and what they do: == Configuring host events -To configure a host event, use the `.trigger()`. +To configure a host event, use the `.trigger()` method. The following example uses `HostEvent.SetVisibleTabs` to show specific tabs whose IDs are specified in the payload. Any tabs whose IDs are not included in this array are hidden. @@ -47,7 +47,7 @@ In your host events implementation, you can choose to trigger an action without ==== Parameters for HostEvent.Pin -The *Pin* action is available on the charts and tables generated from a search query, saved Answers, and visualizations on a Liveboard. Generally, when a user initiates the pin action, the *Pin to Liveboard* modal opens, and the user is prompted to specify the Liveboard to pin the object. The modal also allows the user to add or edit the title text of the visualization and create a new Liveboard if required. +The *Pin* action is available on the charts and tables generated from a search query, saved Answers, and visualizations on a Liveboard. Generally, when a user initiates the pin action, the *Pin to Liveboard* modal opens, and the user is prompted to specify the Liveboard to pin the object to. The modal also allows the user to add or edit the title text of the visualization and create a new Liveboard if required. With `HostEvent.Pin`, you can automate the pin workflow to programmatically add an Answer or visualization to a Liveboard. For example, to pin an object to an existing Liveboard, use the following parameters in the host event object: @@ -56,15 +56,13 @@ __String__. GUID of the saved Answer or visualization to pin to a Liveboard. Not * `liveboardId` + __String__. GUID of the Liveboard to pin the Answer. If there is no Liveboard, you must specify the `newLiveboardName` to create a new Liveboard. * `newVizName` + -__String__. Name string for the Answer that will be added as a visualization to the Liveboard. Note that each time the user clicks, a new visualization object with a new GUID is generated. +__String__. Name string for the visualization. When specified, it adds a new visualization or creates a copy of the Answer or visualization specified in `vizId`. Note that each time this event is triggered, a new visualization object with a new GUID is generated. * `tabId` + __String__. GUID of the Liveboard tab. Adds the Answer to the Liveboard tab specified in the code. -* `newLiveboardName` +* `newLiveboardName` + __String__. Name string for the new Liveboard. Creates a new Liveboard object with the specified name. * `newTabName` + __String__. Name string for the new Liveboard tab. Adds a new tab to the Liveboard specified in the code. -* `newVizName` + -__String__. Name string for the visualization. When specified, it adds a new visualization or creates a copy of the Answer or visualization specified in `vizId`. In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is initiated to add a specific visualization to a specific Liveboard tab: @@ -83,12 +81,12 @@ In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is init [source,JavaScript] ---- const pinResponse = await searchEmbed.trigger(HostEvent.Pin, { - newVizName: `Sales by region`, + newVizName: "Sales by region", liveboardId: "5eb4f5bd-9017-4b87-bf9b-8d2bc9157a5b", }) ---- -In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is initiated to create a new Liveboard with a tab, and then pin the Answer or visualization to it. +In this example, when the `HostEvent.Pin` is triggered, the *Pin* action is initiated to create a new Liveboard with a tab, and then pin the Answer or visualization to it: [source,JavaScript] ---- @@ -113,7 +111,7 @@ For `HostEvent.SaveAnswer`, you can pass the pre-defined attributes such as name * `name` + __String__. Name string for the Answer object. * `description` + -__String__. Description text for the Answer +__String__. Description text for the Answer. [source,JavaScript] ---- @@ -130,19 +128,67 @@ If `HostEvent.SaveAnswer` does not include any parameters, the event triggers th searchEmbed.trigger(HostEvent.SaveAnswer); ---- - === Retrieving and updating filters - The SDK provides the following events for filter retrieval and updates: -* `HostEvent.GetFilters` to get the filters that are currently applied on an embedded Liveboard. You can use this event to inspect the current filter state or to retrieve filter values. -* `HostEvent.UpdateFilters` to update the filters applied on an embedded Liveboard. -* `HostEvent.OpenFilter` to open the filter panel for the specified column. -* `HostEvent.UpdateRuntimeFilters` to update xref:runtime-filters.adoc[Runtime filters]. + -Runtime filters are applied at runtime, that is, when loading the embedded ThoughtSpot content. Runtime filters can also be updated after the load time using `HostEvent.UpdateRuntimeFilters`. You can add a UI option or button in your embedding app and assign the `HostEvent.UpdateRuntimeFilters` to trigger the `UpdateRuntimeFilters` event when that button is clicked. -+ +==== HostEvent.GetFilters +You can use this event to inspect the current filter state or to retrieve filter values. The `HostEvent.GetFilters` returns an array of filter objects representing the filters currently applied on the embedded Liveboard. Each filter object includes the following additional properties: + +`applicable_viz`:: +An object describing which visualizations on the Liveboard this filter applies to. Includes the following properties: + +* `type`. __String__. Scope of the filter. + +** `ALL` means the filter applies to all visualizations. + +** `SPECIFIC` means the filter applies only to the visualization IDs listed in `viz_ids`. +* `viz_ids`. __Array of strings__. Array of visualization GUIDs to which the filter applies. Populated only when `type` is `SPECIFIC`. + +`linking`:: +An object describing the filter-linking state of this filter. Includes the following properties: + +* `is_linked`. __Boolean__. Is `true` if this filter is linked to other filters on the Liveboard. +* `linked_columns`. __Array of strings__. Array of column names or GUIDs that this filter is linked to. + +[source,JSON] +---- +[ + { + "column": "Region", + "operator": "EQ", + "values": ["West"], + "applicable_viz": { + "type": "SPECIFIC", + "viz_ids": ["viz-guid-1", "viz-guid-2"] + }, + "linking": { + "is_linked": true, + "linked_columns": ["Country"] + } + }, + { + "column": "Date", + "operator": "BW_INC", + "values": ["2024-01-01", "2024-12-31"], + "applicable_viz": { + "type": "ALL", + "viz_ids": [] + }, + "linking": { + "is_linked": false, + "linked_columns": [] + } + } +] +---- + +==== HostEvent.UpdateFilters +Updates the filters applied on an embedded Liveboard. For more information and examples, see xref:HostEvent.adoc#_updatefilters[HostEvent reference documentation]. + +==== HostEvent.OpenFilter +Opens the filter panel for the specified column. For more information and examples, see xref:HostEvent.adoc#_openfilter[HostEvent reference documentation]. + +==== HostEvent.UpdateRuntimeFilters +xref:runtime-filters.adoc[Runtime filters] are applied at runtime, that is, when loading the embedded ThoughtSpot content. Runtime filters can also be updated after the load time using `HostEvent.UpdateRuntimeFilters`. You can add a UI option or button in your embedding app and assign `HostEvent.UpdateRuntimeFilters` to a button to trigger the event when that button is clicked. + In this example, the host event is assigned to a button that updates runtime filters when clicked. When `HostEvent.UpdateRuntimeFilters` is triggered, the filters are updated with the attributes specified in the code. -+ + [source,JavaScript] ---- document.getElementById('updateFilters').addEventListener('click', e => { @@ -163,12 +209,12 @@ In this example, the host event is assigned to a button that updates runtime fil === Filtering from the selection Filtering from a selection on a chart or table can be implemented by combining the `EmbedEvent.VizPointClick` or `EmbedEvent.VizPointDoubleClick` events with the `HostEvent.UpdateRuntimeFilters` event. -The callback function from the `VizPointClick` event will need to read the response, parse out the attributes from the response that will be sent to the Runtime Filters object, and then send the attributes and their target fields in the format used by `UpdateRuntimeFilters`. +The callback function from the `VizPointClick` event will need to read the response, parse out the attributes from the response that will be sent to the Runtime Filters object, and then send the attributes and their target fields in the format used by `HostEvent.UpdateRuntimeFilters`. === Using vizId to target a specific visualization If a host event allows the `vizId` parameter, you can use it to target a specific visualization where applicable. For example, to trigger the *Edit* action on a specific visualization in an embedded Liveboard, you can specify the `vizId` parameter in the host event payload. -In the following example, the host event triggers the **Edit** action on the specified visualization in a Liveboard embed: +In the following example, the host event triggers the *Edit* action on the specified visualization in a Liveboard embed: [source,JavaScript] ---- @@ -181,7 +227,7 @@ liveboardEmbed.trigger(HostEvent.Edit, { }); ---- -If `vizId` is not specified, the edit action is triggered at the Liveboard level, instead of the visualization layer. +If `vizId` is not specified, the *Edit* action is triggered at the Liveboard level, instead of the visualization layer. In Spotter embed, `vizId` is a required parameter for several host events. If it is not specified in the host event, the event trigger fails and results in an error indicating that the visualization context is missing. @@ -192,7 +238,7 @@ In the above example, if the visualization with the `730496d6-6903-4601-937e-2c6 == Host event behavior in single-layer and multi-layer UI scenarios -In single‑layer UI, such as a single visualization embed, Spotter embed, or Liveboards listing page in full application embed, a host event call typically results in a single visible action. However, in multi-modal or multi-layer UI, such as Spotter on Liveboard embed, a visualization opened from a Liveboard, or any experience with dialogs on top of a base page, a host event call can trigger multiple handlers at once. For example, the `HostEvent.OpenFilter` can open filters on both the visualization page in the overlay and the underlying Liveboard. +In single-layer UI, such as a single visualization embed, Spotter embed, or Liveboards listing page in full application embed, a host event call typically results in a single visible action. However, in multi-modal or multi-layer UI, such as Spotter on Liveboard embed, a visualization opened from a Liveboard, or any experience with dialogs on top of a base page, a host event call can trigger multiple handlers at once. For example, the `HostEvent.OpenFilter` can open filters on both the visualization page in the overlay and the underlying Liveboard. For context-aware routing and per‑context payload validation, we recommend using the host events framework with page context. For more information, see xref:events-context-aware-routing.adoc[Context-based execution of host events]. @@ -251,7 +297,6 @@ video::./images/hostEvent.mp4[width=100%,options="autoplay,loop"] ++++ Try it out in Playground - ++++ == Event enumerations and examples diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index d0659c9bb..d4c0d9849 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -35,7 +35,7 @@ xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more i 4. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filters, window=_blank] + Liveboard filters apply to all visualizations on the Liveboard and are visible as UI components at the top of a Liveboard page. When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + -Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using the `HostEvent.UpdateFilters`. +Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using `HostEvent.UpdateFilters`. 5. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters-cross[Liveboard cross filters, window=_blank] + Cross filters are ad-hoc filters based on user selection. These filters are used for brushing and linking Liveboard visualizations. + @@ -55,7 +55,7 @@ All operations result in a `WHERE` clause being applied to the queries generated A data filter object in ThoughtSpot typically includes the following attributes: `column`, `columnName`, **or** `columnId`:: -The name of the column to filter on. For example, `item type` or `product`. The column value must match the actual column name in the ThoughtSpot model. If the model uses column aliases, use the base column name, not the alias. This attribute is defined as `col1`, `col2`, `col3` in the object URLs and REST API requests, as `columnName` in the `runtimeFilters` array in the Visual Embed SDK. The filter object for host events in the SDK allows `column` or `columnName`. +The name of the column to filter on. For example, `item type` or `product`. The column value must match the actual column name in the ThoughtSpot model. If the model uses column aliases, use the base column name, not the alias. This attribute is defined as `col1`, `col2`, `col3` in the object URLs and REST API requests, and as `columnName` in the `runtimeFilters` array in the Visual Embed SDK. The filter object for host events in the SDK allows `column` or `columnName`. + If there are multiple columns with the same name, you can use the `WORKSHEET_NAME::COLUMN_NAME` format; for example, `"(Sample) Retail - Apparel::city"`. @@ -63,7 +63,7 @@ If there are multiple columns with the same name, you can use the `WORKSHEET_NAM The supported operators include: + [width="80%" cols="1,2,2"] -[options='header'] +[options="header"] |=== |Operator|Description|Number of Values @@ -122,6 +122,7 @@ The supported operators include: | `IN` | is included in this list of values | multiple + | `NOT_IN` | is not included in this list of values | multiple @@ -220,19 +221,38 @@ liveboardEmbed.trigger(HostEvent.UpdateFilters, { ---- === GetFilters and GetParameters events -If you want to build your own filter UI within the embedding app, you can find out details of the Liveboard and runtime filters that are defined using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getfilters[HostEvent.GetFilters]. There is an equivalent link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getparameters[HostEvent.GetParameters] to get the currently set Parameter values: +If you want to build your own filter UI within the embedding app, you can find out details of the Liveboard and runtime filters that are defined using `HostEvent.GetFilters`. + +**GetFilters** [source,JavaScript] ---- const data = await liveboardEmbed.trigger(HostEvent.GetFilters); console.log('data', data); +---- + +Each filter object in the `HostEvent.GetFilters` response includes two additional fields: + +* `applicable_viz`: indicates whether the filter applies to `ALL` visualizations or only `SPECIFIC` ones (with a `viz_ids` array). +* `linking`: indicates whether the filter is linked to other filters, and which columns it is linked to (`is_linked`, `linked_columns`). + +For more information, see xref:events-hostEvents.adoc#_hostevent_getfilters[HostEvent.GetFilters] and xref:HostEvent.adoc#_getfilters[HostEvent reference documentation]. + +**GetParameters** + +To get the currently set Parameter values, use `HostEvent.GetParameters`: + +[source,JavaScript] +---- liveboardEmbed.trigger(HostEvent.GetParameters).then((parameter) => { console.log('parameters', parameter); }); ---- -Note that `HostEvent.GetFilters` and `HostEvent.GetParameters` return a promise directly rather than taking a callback function as their second argument. +[NOTE] +==== +`HostEvent.GetFilters` and `HostEvent.GetParameters` return a promise directly rather than taking a callback function as their second argument. +==== === FilterChanged and ParameterChanged events You can also listen for the user's interactions with the filters using the link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_filterchanged[EmbedEvent.FilterChanged]. @@ -267,7 +287,7 @@ When updating filters using `HostEvent.UpdateFilters`, you must include the date The following table lists the supported filter types and examples for each type: [width="100%" cols="3,8"] -[options='header'] +[options="header"] |===== |Type| Description @@ -460,7 +480,7 @@ The `override_filters` value is a JSON array of filter objects, with each object [IMPORTANT] ==== -* The `override_filters` accepts a JSON array directly, not an object that wraps the array. +* The `override_filters` parameter accepts a JSON array directly, not an object that wraps the array. * Specifying two or more filter objects that target the same date column returns the error, `more than one filter objects are not allowed for date type column `. However, columns with other data type do not have this restriction. Multiple filter objects on the same non-date column are merged. ==== @@ -508,6 +528,7 @@ Valid values for rolling date filters include: + * `TODAY` - The current calendar day. * `TOMORROW` - The next calendar day. * `THIS_PERIOD` - The current period (for example, this quarter). +* `LAST_PERIOD` - The previous single period (for example, last month). * `NEXT_PERIOD` - The next single period (for example, next month). * `LAST_N_PERIOD` - The last _N_ complete periods. * `NEXT_N_PERIOD` - The next _N_ complete periods. @@ -536,7 +557,7 @@ Valid values for `datePeriod` include: * `MONTH` - Calendar month * `QUARTER` - Calendar quarter * `YEAR` - Calendar year -* `HOUR` - Hour (`dateTime` columns only) +* `HOUR` - Hour (`datetime` columns only) * `MINUTE` - Minute (`datetime` columns only) * `SECOND` - Second (`datetime` columns only) @@ -675,7 +696,7 @@ Name of the month in uppercase. Required for `MONTH_YEAR`. Refer to the following table for examples of JSON object for date filters: [width="100%" cols="3,8"] -[options='header'] +[options="header"] |===== |Date filter type | Example @@ -917,4 +938,6 @@ Refer to the following documentation for more information: === Events There is no specific event to update `search_query filters` in the `SearchEmbed` component or the Liveboard edit mode. -You can set your app to listen to link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_querychanged[EmbedEvent.QueryChanged] and trigger the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_gettml[HostEvent.GetTML] event to get a new TML generated for the `search_query` string after an update. \ No newline at end of file +You can set your app to listen to link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_querychanged[EmbedEvent.QueryChanged] and trigger the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_gettml[HostEvent.GetTML] event to get a new TML generated for the `search_query` string after an update. + +//// \ No newline at end of file diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index 718d098b8..109bf50fb 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -4,7 +4,7 @@ :page-title: Using REST API v2.0 metadata/search endpoint :page-pageid: rest-apiv2-metadata-search -:page-description: Many use cases are possible with the very V2.0 metadata/search endpoint +:page-description: Many use cases are possible with the V2.0 metadata/search endpoint The `link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fsearch-metadata[/metadata/search, target=_blank]` endpoint is the most versatile of all metadata endpoints. It can be used to search for lists or to retrieve very detailed information about specific objects. This endpoint replaces `metadata/list`, `metadata/listobjectheaders`, `metadata/details`, and `metadata/listvizheaders` from REST API v1. @@ -86,7 +86,7 @@ The response from any call to `metadata/search` returns an array of link:https:/ "metadata_detail": null, "metadata_header": {...}, "visualization_headers": null, - "stats": null, + "stats": null }, ... ] @@ -112,7 +112,7 @@ The value of `metadata_header` is a complex object with the most important set o "name": "Snowflake", "description": "Connection to Snowflake data warehouse", "author": "67e15c06-d153-4924-a4cd-ff615393b60f", - "authorName": "UserA, + "authorName": "UserA", "hasLenientDiscoverability": false, "descriptionAutoGenerated": false, "authorDisplayName": "UserA", @@ -3601,7 +3601,7 @@ The `permissions` object takes an array of objects that define a `principal` and The `share_mode` can be `READ_ONLY` ('Can View' in the UI), `MODIFY` ('Can Edit' in the UI), or `NO_ACCESS`, which shows denial of access and is not visible in the UI. === tag_identifiers -Thoughtspot objects can be assigned multiple **tags**, and the `/metadata/search` endpoint allows you to filter for items with a set of tags using the `tag_identifiers` parameter, which takes an array of tag names or GUIDs. +ThoughtSpot objects can be assigned multiple **tags**, and the `/metadata/search` endpoint allows you to filter for items with a set of tags using the `tag_identifiers` parameter, which takes an array of tag names or GUIDs. Including multiple tags behaves as a logical **OR** operation, retrieving all content with **any** of the listed tags. The following request body retrieves any content tagged with `Staging` or `Accounting` tags: @@ -3735,12 +3735,98 @@ The `include_details` parameter in the `metadata/search` API request adds the eq } ---- -The details of each object type is a complex object that is unique to each object type within ThoughtSpot. +The details of each object type are a complex object that is unique to each object type within ThoughtSpot. -The JSON output for `metadata_detail` varies for Liveboards based on the response version specified in the API request. For more information, see xref:rest-api-v2-metadata-search.adoc#lbResponse[Liveboard response format]. +The JSON output for `metadata_detail` varies for Liveboards based on the response version specified in the API request. For more information, see xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[Liveboard response format]. + +=== include_personalised_views +When fetching Liveboard metadata with `include_details: true`, you can also request the list of Personalized Views saved on each Liveboard by setting `include_personalised_views` to `true`. + +This parameter is only applicable to `LIVEBOARD` type objects and has no effect on other metadata types. It requires `include_details` to also be `true` in the same request. + +[source,JSON] +---- +{ + "metadata": [ + { + "type": "LIVEBOARD" + } + ], + "include_details": true, + "include_personalised_views": true +} +---- + +When both parameters are set to `true`, each Liveboard object in the response will include a `personalised_views` array nested within `metadata_detail`: + +[source,JSON] +---- +[ + { + "metadata_id": "4081f38c-1f26-4354-a418-af14136e3bd7", + "metadata_name": "Sales Overview", + "metadata_type": "LIVEBOARD", + "metadata_detail": { + "personalised_views": [ + { + "view_guid": "6e3d11b2-9a4f-4c1e-8b5a-2f3d7e0c1a9d", + "view_name": "Q1 Revenue View", + "author_guid": "59481331-ee53-42be-a548-bd87be6ddd4a", + "author_name": "Alice Johnson", + "is_public": false + }, + { + "view_guid": "a9c42f17-3b8e-4d20-91fa-7c5e2d0b8f3a", + "view_name": "Executive Summary", + "author_guid": "67e15c06-d153-4924-a4cd-ff615393b60f", + "author_name": "Bob Smith", + "is_public": true + } + ] + }, + "metadata_header": {...}, + "visualization_headers": null, + "dependent_objects": null, + "incomplete_objects": null, + "stats": null + } +] +---- + +The `personalised_views` array contains one object per saved Personalized View on the Liveboard. Each object has the following properties: + +[width="100%",cols="2,1,4"] +|==== +|Property|Type|Description + +|`view_guid` +|String +|Unique GUID of the Personalized View. + +|`view_name` +|String +|Display name of the Personalized View as set by its author. + +|`author_guid` +|String +|GUID of the ThoughtSpot user who created this Personalized View. + +|`author_name` +|String +|Display name of the user who created this Personalized View. + +|`is_public` +|Boolean +|If `true`, the Personalized View is shared publicly and visible to other users with access to the Liveboard. If `false`, the view is private to its author. +|==== + +[NOTE] +==== +If a Liveboard has no saved Personalized Views, the `personalised_views` array will be empty (`[]`). If `include_personalised_views` is `false` or omitted, the `personalised_views` key will not appear in `metadata_detail`. +==== === include_dependent_objects -Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects** that connect to them. Liveboards and Answers do not have dependent objects, they can only be a dependent object. +Data objects in ThoughtSpot like Tables and Worksheets have **dependent objects** that connect to them. Liveboards and Answers do not have dependent objects; they can only be a dependent object. An object can only be deleted if all of its dependent objects are deleted first. @@ -3793,7 +3879,7 @@ The `include_hidden_objects`, `include_incomplete_objects`, and `include_auto_cr === Pagination settings -By default, the following pagination settings are applied to the API response retrieved search metadata endpoint: +By default, the following pagination settings are applied to the API response retrieved from the search metadata endpoint: [source,JSON] ---- diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 0cad327a6..41a32dc07 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -53,8 +53,8 @@ The `GET /api/rest/2.0/webhooks/storage-config` API endpoint allows retrieving t Enhancements:: -* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. -* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activate status, resetting authentication, signature verification, and storage destination properties. +* The `/api/rest/2.0/webhooks/create` endpoint allows activating a webhook and configuring a GCS storage destination for webhook delivery. The API endpoint also returns GCS storage configuration details in the response. +* The `/api/rest/2.0/webhooks/{webhook_identifier}/update` API endpoint supports configuring webhook activation status, resetting authentication, signature verification, and storage destination properties. * API requests to the `/api/rest/2.0/system/communication-channels/validate` now return GCS storage properties in response. === Communication channel monitoring @@ -165,7 +165,7 @@ Valid range: 80–500%. Automatic file naming:: The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). -Contact ThoughtSpot support to enable these settings for PNG downloads on your ThoughtSpot instance. +Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. === Share metadata API: Collections support [beta betaBackground]^Beta^ @@ -178,7 +178,7 @@ For more information, see xref:collections.adoc#share-collection[Share a Collect == Version 26.5.0.cl, May 2026 === Sync connection metadata attributes -You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. +You can now synchronize connection metadata attributes from your Cloud Data Warehouse (CDW) with ThoughtSpot by sending a request to the `POST /api/rest/2.0/connections/{connection_identifier}/resync-metadata` API endpoint. === Spotter APIs @@ -239,6 +239,20 @@ The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF download For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. +=== Metadata search API enhancements + +Personalized Views in metadata search:: +The `POST /api/rest/2.0/metadata/search` API endpoint introduces the `include_personalised_views` request parameter. + +When both `include_details: true` and `include_personalised_views: true` are specified in the request, the API returns a `personalised_views` array in the `metadata_detail` object for `LIVEBOARD` metadata type responses. + +This allows you to retrieve the full list of Personalized Views associated with a Liveboard in a single API call, without requiring a separate TML export. + +For more information, see xref:rest-api-v2-metadata-search.adoc#_include_personalised_views[Search metadata API]. + +=== TML API enhancements +The previous limit of 100 Personalized Views per Liveboard on TML import has been removed. You can now import all associated Personalized Views of a Liveboard without any views being dropped. For more information, see the xref:tml-api.adoc[TML API documentation]. + == Version 26.4.0.cl, April 2026 === Variable API endpoints @@ -439,7 +453,7 @@ Sets a communication channel preference for all Orgs at the cluster level or at * `POST /api/rest/2.0/system/preferences/communication-channels/search` [beta betaBackground]^Beta^ + Gets details of the communication channel preferences configured on ThoughtSpot. + -For more information, see xref:webhooks-lb-schedule.adoc#_configure_a_webhook_communication_channel[Configure communication channel settings]. +For more information, see xref:webhooks-comm-channel.adoc[Configure and monitor communication channels]. Webhook:: The following APIs are introduced for webhook CRUD operations: @@ -1077,7 +1091,7 @@ For more information, see xref:tse-eco-mode.adoc#_cluster_status_during_upgrade[ The `deploy_policy` property in the `/api/rest/2.0/vcs/git/commits/deploy` endpoint now supports the `VALIDATE_ONLY` option, which allows you to compare and validate TML content on the destination environment against the content in the main branch before deploying commits. -== Version 9.7.0, November 2023 +== Version 9.7.0.cl, November 2023 === Version Control APIs @@ -1306,7 +1320,7 @@ Deletes a data connection Enhancements:: * Support for runtime filters and runtime sorting of columns + -The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_apply_runtime_filters_in_rest_api_v2_requests[runtime filters] and xref:runtime-sort.adoc[sorting column data]: +The following REST API v2.0 endpoints support applying xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[runtime filters] and xref:runtime-sort.adoc[sorting column data]: + ** `POST /api/rest/2.0/report/liveboard` + ** `POST /api/rest/2.0/report/answer`