From 7c4e957258e6c1688c649c43a0af7c4b58fe61df Mon Sep 17 00:00:00 2001 From: Bryant Howell - ThoughtSpot <83678239+bryanthowell-ts@users.noreply.github.com> Date: Wed, 14 Aug 2024 06:44:34 -0500 Subject: [PATCH 1/6] Update nav.adoc Reordered custom actions to bring callback actions to the second slot --- modules/ROOT/pages/common/nav.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 5f0812a65..bc0dff5e2 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -57,11 +57,11 @@ **** link:{{navprefix}}/events-app-integration[Events and app interactions] **** link:{{navprefix}}/custom-action-intro[Custom actions] ***** link:{{navprefix}}/customize-actions[Create and manage custom actions] +***** link:{{navprefix}}/custom-action-callback[Callback actions] ***** link:{{navprefix}}/edit-custom-action[Set the position of a custom action] ***** link:{{navprefix}}/add-action-viz[Add a local action to a visualization] ***** link:{{navprefix}}/add-action-worksheet[Add a local action to a worksheet] ***** link:{{navprefix}}/custom-action-url[URL actions] -***** link:{{navprefix}}/custom-action-callback[Callback actions] ***** link:{{navprefix}}/custom-action-payload[Callback response payload] *** link:{{navprefix}}/in-app-navigation[Build navigation to ThoughtSpot content] From 38a3ca4aab862b5f1bf7f81f9181948ad1ba060d Mon Sep 17 00:00:00 2001 From: Bryant Howell - ThoughtSpot <83678239+bryanthowell-ts@users.noreply.github.com> Date: Wed, 14 Aug 2024 06:55:06 -0500 Subject: [PATCH 2/6] Update customize-actions-menu.adoc Moved the instructions for creating URL and Callback actions into this page from their respective pages --- .../ROOT/pages/customize-actions-menu.adoc | 122 ++++++++++++++++-- 1 file changed, 108 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/customize-actions-menu.adoc b/modules/ROOT/pages/customize-actions-menu.adoc index 067d162d2..dabc7d553 100644 --- a/modules/ROOT/pages/customize-actions-menu.adoc +++ b/modules/ROOT/pages/customize-actions-menu.adoc @@ -1,13 +1,16 @@ = Create and manage custom actions :toc: true -:toclevels: 1 +:toclevels: 2 -:page-title: Custom actions overview +:page-title: Create and manage custom actions :page-pageid: customize-actions -:page-description: Overview of custom actions +:page-description: Create and manage custom actions -The custom actions feature in ThoughtSpot allows users to push data to external applications. To allow ThoughtSpot users to quickly act on the data they analyze, custom actions must be pre-configured in their setup. ThoughtSpot users with developer or admin privileges can create various types of custom actions in the **Develop ** tab and make them available on a saved Answer or visualization page. +To allow ThoughtSpot users to quickly act on the data they analyze, xref:custom-actions.adoc[custom actions] must be defined and configured within ThoughtSpot. +ThoughtSpot users with developer or admin privileges can create various types of custom actions in the **Develop ** tab and make them available on a saved Answer or visualization page. + +//// [div boxDiv boxFullWidth] -- +++
Feature highlights
+++ @@ -19,15 +22,13 @@ The custom actions feature in ThoughtSpot allows users to push data to external * Global actions appear as menu actions on all visualizations. * ThoughtSpot users with edit privileges can add a local custom action to a worksheet, saved Answer, or visualization. -- +//// -== Custom actions page - -To view the *Custom actions* page, go to *Develop* > *Customizations* > *Custom actions*. +To view the *Custom actions* management page, go to *Develop* > *Customizations* > *Custom actions*. The *Custom actions* page displays the **Create action** button, and the *Overview* and *Actions* tabs. - -=== Create action +== Create action button The *Create action* button allows you to create the following types of actions: @@ -65,15 +66,108 @@ For granular access control, developers can restrict a custom action's availabil ==== In embedded ThoughtSpot instances, developers can also use the `visibleActions`, `hiddenActions`, and `disabledActions` properties to xref:embed-actions.adoc[show, hide, and disable a custom action]. ==== - -=== Overview +[#add-callback] +=== Create a callback custom action + +Before you begin, make sure you have the developer privileges to add a custom action in the Developer portal. + +. Go to *Develop* > *Customizations* > *Custom actions*. +. Click *Create action*. +. Add a label for the custom action. For example, __Send Data__. +. Select the *Callback* option. +. Note the callback action ID. + ++ +The callback ID is used as a unique reference in the Visual Embed SDK to handle the callback event. You can also use this ID to disable, show, or hide the callback action in the embedded app. + ++ +By default, custom actions are added to all Liveboard visualizations and saved Answers and set as Global. If you want to add this action only to specific visualizations, clear the *On by default on all visualizations* checkbox. + +. To restrict action availability to specific user groups, click *Show advanced availability settings*, and select the groups. + +. Click *Create action*. ++ +The custom action is added to the *Actions* dashboard in the Developer portal. + +. To view and verify the custom action you just created, navigate to a visualization page. + +include::{path}/global-local-action.adoc[] + + +[#creUrlAction] +=== Create a URL action + +Before you begin: + +* Make sure you have the developer or admin privileges to create a custom action. +* If a URL action is intended to be used by the embedded ThoughtSpot user, add the URL to the xref:security-settings.adoc[CORS and CSP connect-src allowlist]. + +To create a URL action, complete the following steps: + +. Go to *Develop* > *Customizations* > *Custom actions*. +. Click *Create action*. +. Add a label for the custom action. For example, __Send Email__. +. Make sure the *URL* option is selected. +. Add the target URL that you want to invoke when a user clicks this action in the UI. ++ +[NOTE] +==== +The URL-based custom actions do not support the `localhost` hostname. Therefore, use the IP address `127.0.0.1` instead of `localhost` when specifying the target URL. +==== + ++ +Note that the custom action ID is generated automatically. + ++ +. To view additional settings, click *Show URL settings*. +. From the *Authorization* drop-down, select an authentication method. ThoughtSpot will use the specified authentication method to invoke the URL or make an API call. ++ +[IMPORTANT] +The authentication information you specify in these fields is visible to other authenticated users, even if they do not have Developer or Admin privileges. + +None:: +If you do not want to use an authentication method, select `None`. + +Basic authentication:: +Select this authentication method if your server requires ThoughtSpot to pass the authentication information, such as `username` and `password` in the `Authorization` header. If selected, enter the `username` and `password`. + +Bearer:: +Select this authentication method if your server requires ThoughtSpot to obtain a security token and send the token in the `Authorization` headers during an API call. Specify the security `token` to use for authentication and authorization. + +API key:: +Select this authentication method if you want ThoughtSpot to use an API key during API calls to the URL target. Specify the API key value to use in the `X-API-Key` request header. + ++ +. If the URL endpoint requires specific data for the custom action workflow, you can configure the action to send these attributes as query parameters. For example, you may want to send database information in query parameters to the URL endpoint when the action workflow is triggered. Make sure these query parameters are defined as key-value pairs. + +. To add this action to all visualizations and saved Answer pages, select *On by default on all visualizations*. ++ +If you do not select this checkbox, the URL action will be set as a *Local* action. + +. To restrict action availability to specific user groups, click *Show advanced availability settings*, and select the groups. + +. Click *Create action*. ++ +The custom action is added to the *Actions* dashboard in the Developer portal. + +. To view the custom action you just created, navigate to a visualization or saved Answer page. + +include::{path}/global-local-action.adoc[] + +== Overview tab + +The *Overview* tab shows the possible locations for placing a custom action in the ThoughtSpot UI. + +You can add a custom action in the primary menu bar, or as a menu action in the **More** image:./images/icon-more-10px.png[the more options menu] menu or the contextual menu that appears when a user right-clicks on an Answer or Liveboard visualization. + +By default, ThoughtSpot adds all custom actions to the **More** image:./images/icon-more-10px.png[the more options menu] menu. -The *Overview* tab shows the possible locations for placing a custom action in the ThoughtSpot UI. You can add a custom action in the primary menu bar, or as a menu action in the **More** image:./images/icon-more-10px.png[the more options menu] menu or the contextual menu that appears when a user right-clicks on an Answer or Liveboard visualization. +If you want to send only a single row of data instead of the entire data set obtained from a visualization, you can place the custom action in the contextual menu. -By default, ThoughtSpot adds all custom actions to the **More** image:./images/icon-more-10px.png[the more options menu] menu. If you want to send only a single row of data instead of the entire data set obtained from a visualization, you can place the custom action in the contextual menu. To change the position of an existing custom action, click the custom action icon image:./images/custom-action-icon.png[custom action icon] on a saved Answer page, and then click the edit icon next to the custom action in the *Custom action* panel. +To change the position of an existing custom action, click the custom action icon image:./images/custom-action-icon.png[custom action icon] on a saved Answer page, and then click the edit icon next to the custom action in the *Custom action* panel. -=== Actions +== Actions tab The *Actions* tab lists the actions created on your ThoughtSpot instance. From 8b05e7f976142c5645ba94e7fdc8ef6c7099621b Mon Sep 17 00:00:00 2001 From: Bryant Howell - ThoughtSpot <83678239+bryanthowell-ts@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:38:18 -0500 Subject: [PATCH 3/6] Update custom-actions-callback.adoc Moved creation to the other page --- .../ROOT/pages/custom-actions-callback.adoc | 28 +------------------ 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/modules/ROOT/pages/custom-actions-callback.adoc b/modules/ROOT/pages/custom-actions-callback.adoc index 1d11ed825..75d987941 100644 --- a/modules/ROOT/pages/custom-actions-callback.adoc +++ b/modules/ROOT/pages/custom-actions-callback.adoc @@ -29,32 +29,6 @@ To set up a callback custom action workflow, complete the following steps: * xref:custom-actions-callback.adoc#handle-data[Define classes and functions to parse JSON and handle data] * xref:custom-actions-callback.adoc#callback-initiate[Initiate a callback and verify your implementation] -[#add-callback] -== Create a callback custom action - -Before you begin, make sure you have the developer privileges to add a custom action in the Developer portal. - -. Go to *Develop* > *Customizations* > *Custom actions*. -. Click *Create action*. -. Add a label for the custom action. For example, __Send Data__. -. Select the *Callback* option. -. Note the callback action ID. - -+ -The callback ID is used as a unique reference in the Visual Embed SDK to handle the callback event. You can also use this ID to disable, show, or hide the callback action in the embedded app. - -+ -By default, custom actions are added to all Liveboard visualizations and saved Answers and set as Global. If you want to add this action only to specific visualizations, clear the *On by default on all visualizations* checkbox. - -. To restrict action availability to specific user groups, click *Show advanced availability settings*, and select the groups. - -. Click *Create action*. -+ -The custom action is added to the *Actions* dashboard in the Developer portal. - -. To view and verify the custom action you just created, navigate to a visualization page. - -include::{path}/global-local-action.adoc[] [#register-callback] == Register the callback using Visual Embed SDK @@ -357,4 +331,4 @@ Custom actions appear as disabled on unsaved charts and tables. If you have gene //// * link:https://github.com/thoughtspot/ts_everywhere_resources/tree/master/example_actions/download_csv[Custom action examples, window=_blank] -//// \ No newline at end of file +//// From 3a0d1ea5cb7906250a9961221006ede2d1b90735 Mon Sep 17 00:00:00 2001 From: Bryant Howell - ThoughtSpot <83678239+bryanthowell-ts@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:38:28 -0500 Subject: [PATCH 4/6] Update custom-actions-url.adoc Moved creation to the other page --- modules/ROOT/pages/custom-actions-url.adoc | 60 ---------------------- 1 file changed, 60 deletions(-) diff --git a/modules/ROOT/pages/custom-actions-url.adoc b/modules/ROOT/pages/custom-actions-url.adoc index 62c6a22ed..dcbab3368 100644 --- a/modules/ROOT/pages/custom-actions-url.adoc +++ b/modules/ROOT/pages/custom-actions-url.adoc @@ -22,66 +22,6 @@ ThoughtSpot allows you to add a custom action to trigger a data payload to a spe * Only ThoughtSpot users with edit permissions to a Worksheet or visualization can add a URL action to a Worksheet, visualization, or saved Answer. -- -[#creUrlAction] -== Create a URL action - -Before you begin: - -* Make sure you have the developer or admin privileges to create a custom action. -* If a URL action is intended to be used by the embedded ThoughtSpot user, add the URL to the xref:security-settings.adoc[CORS and CSP connect-src allowlist]. - -To create a URL action, complete the following steps: - -. Go to *Develop* > *Customizations* > *Custom actions*. -. Click *Create action*. -. Add a label for the custom action. For example, __Send Email__. -. Make sure the *URL* option is selected. -. Add the target URL that you want to invoke when a user clicks this action in the UI. -+ -[NOTE] -==== -The URL-based custom actions do not support the `localhost` hostname. Therefore, use the IP address `127.0.0.1` instead of `localhost` when specifying the target URL. -==== - -+ -Note that the custom action ID is generated automatically. - -+ -. To view additional settings, click *Show URL settings*. -. From the *Authorization* drop-down, select an authentication method. ThoughtSpot will use the specified authentication method to invoke the URL or make an API call. -+ -[IMPORTANT] -The authentication information you specify in these fields is visible to other authenticated users, even if they do not have Developer or Admin privileges. - -None:: -If you do not want to use an authentication method, select `None`. - -Basic authentication:: -Select this authentication method if your server requires ThoughtSpot to pass the authentication information, such as `username` and `password` in the `Authorization` header. If selected, enter the `username` and `password`. - -Bearer:: -Select this authentication method if your server requires ThoughtSpot to obtain a security token and send the token in the `Authorization` headers during an API call. Specify the security `token` to use for authentication and authorization. - -API key:: -Select this authentication method if you want ThoughtSpot to use an API key during API calls to the URL target. Specify the API key value to use in the `X-API-Key` request header. - -+ -. If the URL endpoint requires specific data for the custom action workflow, you can configure the action to send these attributes as query parameters. For example, you may want to send database information in query parameters to the URL endpoint when the action workflow is triggered. Make sure these query parameters are defined as key-value pairs. - -. To add this action to all visualizations and saved Answer pages, select *On by default on all visualizations*. -+ -If you do not select this checkbox, the URL action will be set as a *Local* action. - -. To restrict action availability to specific user groups, click *Show advanced availability settings*, and select the groups. - -. Click *Create action*. -+ -The custom action is added to the *Actions* dashboard in the Developer portal. - -. To view the custom action you just created, navigate to a visualization or saved Answer page. - -include::{path}/global-local-action.adoc[] - == Initiate a URL action To initiate a URL action: From 3e58f24f29455e51136c1db2d0af0b0666b3cb9f Mon Sep 17 00:00:00 2001 From: Bryant Howell - ThoughtSpot <83678239+bryanthowell-ts@users.noreply.github.com> Date: Wed, 14 Aug 2024 14:47:47 -0500 Subject: [PATCH 5/6] Update custom-actions-url.adoc Clarified the description of URL custom actions, added note that they have a flaw in terms of UI response for the user --- modules/ROOT/pages/custom-actions-url.adoc | 24 +++++++++------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/custom-actions-url.adoc b/modules/ROOT/pages/custom-actions-url.adoc index dcbab3368..4c5e57b13 100644 --- a/modules/ROOT/pages/custom-actions-url.adoc +++ b/modules/ROOT/pages/custom-actions-url.adoc @@ -6,25 +6,21 @@ :page-pageid: custom-action-url :page-description: You can add a custom action to send data to a specific URL target -ThoughtSpot allows you to add a custom action to trigger a data payload to a specific URL target. For example, you may search in ThoughtSpot for specific data and want to programmatically deliver this data to an external application or web page. ThoughtSpot Developer portal allows developers to add a custom menu item in the visualization pages and trigger a data push workflow when a user clicks the action. +ThoughtSpot allows you to add a custom action to trigger a data payload to a specific URL target. +== Overview +URL actions appear in ThoughtSpot even without using the Visual Embed SDK within an embedded application. -[div boxDiv boxFullWidth] --- -+++
Feature highlights
+++ +For URL actions to work in the embedded mode, you must add the URL domain to the CORS and CSP connect-src allowlist. -* Any ThoughtSpot user with admin or developer privileges can create URL custom actions in the Developer portal. -* URL actions are available on both embedded and standalone ThoughtSpot instances and do not require ThoughtSpot Embedded Edition license. -* Developers can set a URL action as a global or local action. -* Developers can limit custom action access to a specific user group. -* To access a URL action, users must have the **New Answer Experience** enabled. -* For URL actions to work in the embedded mode, you must add the URL domain to the CORS and CSP connect-src allowlist. -* Only ThoughtSpot users with edit permissions to a Worksheet or visualization can add a URL action to a Worksheet, visualization, or saved Answer. --- +[NOTE] +==== +URL actions do not display any feedback to the user when they are triggered. For custom actions that can provide user feedback within an embedded app, please use xref:custom-actions-callback.adoc[callback custom actions]. +==== -== Initiate a URL action +== Trigger a URL action -To initiate a URL action: +To trigger a URL action: . Navigate to a Liveboard visualization or saved Answer page, and click the URL action. + From 249260bc44486ad579e7b327db260a1156c6a0b4 Mon Sep 17 00:00:00 2001 From: Bryant Howell - ThoughtSpot <83678239+bryanthowell-ts@users.noreply.github.com> Date: Wed, 14 Aug 2024 17:29:49 -0500 Subject: [PATCH 6/6] Update custom-actions-callback.adoc --- .../ROOT/pages/custom-actions-callback.adoc | 56 ++++++++++++------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/modules/ROOT/pages/custom-actions-callback.adoc b/modules/ROOT/pages/custom-actions-callback.adoc index 75d987941..fd4f7a756 100644 --- a/modules/ROOT/pages/custom-actions-callback.adoc +++ b/modules/ROOT/pages/custom-actions-callback.adoc @@ -5,35 +5,44 @@ :page-pageid: custom-action-callback :page-description: Set up a callback function to the host application and trigger a response payload from the embedded ThoughtSpot component. -Callback custom actions allow you to get data payloads from an embedded ThoughtSpot object and initiate a callback to the host application. For example, if you have embedded a ThoughtSpot Liveboard in your application, you can add a callback action to the Liveboard menu to get a JSON response payload from the Liveboard visualization and initiate a callback to your app. +== Overview +Callback custom actions act fire off an link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_customaction[EmbedEvent] when the menu item or button linked to the action is clicked by a user. +[NOTE] +==== +Callback custom actions only appear in the menu system when ThoughtSpot is embedded using the Visual Embed SDK. Please go the Develop tab and use the Visual Embed SDK Developer Playground to see callback custom actions within ThoughtSpot, or use your embedded application. +==== -[div boxDiv boxFullWidth] --- -+++
Feature highlights
+++ +The embedded app will define a listener for all `EmbedEvent.CustomAction` events, with a number of `if()` statements evaluating the `id` property of the response to determine which callback action has been selected by the user. -* Callback custom actions are supported on embedded ThoughtSpot instances only and require a ThoughtSpot Embedded Edition license. -* Users with developer or admin privileges can create a callback custom action in the Developer portal. -* Developers can set a callback action as a global or local action. -* To access callback actions, users must have the **New Answer Experience** enabled on their application instance. -* Users with edit permissions to a Worksheet or visualization can add a local callback action to a visualization or Answer of their choice. -* Developers must register the callback in the Visual Embed SDK and define data classes and functions to parse and process the JSON data payload retrieved from the callback event. --- +[source,Javascript] +---- +searchEmbed.on(EmbedEvent.CustomAction, payload => { + const data = payload.data; + if (data.id === 'show-data') { + console.log('Custom Action event:', data.embedAnswerData); + } +}) +---- + +The xref:callback-response-payload.adoc[response payload] contains metadata about the callback action, the content where the custom action was triggered from, as well as the data from the table or visualization. -== Get started +Developers must register the callback in the Visual Embed SDK and define data classes and functions to parse and process the JSON data payload retrieved from the callback event. + +== Implement a callback custom action To set up a callback custom action workflow, complete the following steps: -* xref:custom-actions-callback.adoc#add-callback[Create a callback custom action] -* xref:custom-actions-callback.adoc#register-callback[Register the custom action] +* xref:customize-actions-menu.adoc#add-callback[Create a callback custom action] +* xref:custom-actions-callback.adoc#register-callback[Define the event handler using Visual Embed SDK] * xref:custom-actions-callback.adoc#handle-data[Define classes and functions to parse JSON and handle data] * xref:custom-actions-callback.adoc#callback-initiate[Initiate a callback and verify your implementation] [#register-callback] -== Register the callback using Visual Embed SDK +== Define event listener using Visual Embed SDK -After a callback custom action is added in ThoughtSpot, add an event handler to listen to the callback event and trigger a data payload as a response when a user clicks the callback action in the UI. +In your Visual Embed SDK code, add an `.on()` listener for the `EmbedEvent.CustomAction` event, with blocks parsing the `id` property of the response to define different behaviors for different callback customer actions. In this example, the data payload from the custom action response is logged in the console. @@ -105,7 +114,11 @@ include::{path}/callback-payload.adoc[] [#handle-data] == Parse JSON response payload -The callback actions can return JSON payloads that are complex and need to be parsed before using it for application needs. The format of the JSON response payload can vary based on the type of the embedded object and the placement of the custom action in the menu. For example, the format of the data payload triggered by an action on a Liveboard visualization is different from the data retrieved for an Answer. When defining functions in your code to parse and handle data, make sure you use the correct classes. +The callback actions can return JSON payloads that are complex and need to be parsed before using it for application needs. + +The format of the JSON response payload can vary based on the type of the embedded object and the placement of the custom action in the menu. + +For example, the format of the data payload triggered by an action on a Liveboard visualization is different from the data retrieved for an Answer. When defining functions in your code to parse and handle data, make sure you use the correct classes. === Define functions and classes to handle Liveboard data @@ -202,7 +215,11 @@ class LiveboardActionData { } ---- -The above example uses additional classes and functions to parse and get data in the tabular format, the number of columns, rows, and column names. These classes are defined in the code sample in `dataclasses.js` on link:https://github.com/thoughtspot/ts_everywhere_resources/blob/master/apis/dataclasses.js[ThoughtSpot Embedded Resources GitHub repository, window="_blank"]. You can also find sample classes and functions to parse JSON payload from context menu actions in `dataclasses.js`. +The above example uses additional classes and functions to parse and get data in the tabular format, the number of columns, rows, and column names. + +These classes are defined in the code sample in `dataclasses.js` on link:https://github.com/thoughtspot/ts_everywhere_resources/blob/master/apis/dataclasses.js[ThoughtSpot Embedded Resources GitHub repository, window="_blank"]. + +You can also find sample classes and functions to parse JSON payload from context menu actions in `dataclasses.js`. === Define functions and classes to handle Answer data @@ -312,9 +329,8 @@ export { } ---- - [#callback-initiate] -== Initiate a callback and test your implementation +== Trigger a callback custom action and test your implementation To initiate a callback action: