Merge pull request #371 from thoughtspot/sf-integration-update

SF integration LWC plugin update

Author: ShashiSubramanya

modules/ROOT/pages/sf-integration.adoc

@@ -6,55 +6,155 @@
 :page-pageid: sf-integration
 :page-description: Methods for embedding ThoughtSpot into Salesforce Cloud products
 
-Integrating ThoughtSpot with Salesforce enables users to access analytics directly within their Salesforce environment. By embedding ThoughtSpot content, organizations can deliver data-driven insights where your end users work, enhancing decision-making and efficiency. This guide explores the various embedding options, including the Visual Embed SDK and non-SDK approaches, and discusses key recommendations for authentication, customization/branding, and embedding in mobile apps.
+Integrating ThoughtSpot with Salesforce enables users to access analytics directly within Salesforce. By embedding ThoughtSpot content, organizations can deliver data-driven insights where their end users work, enhancing decision-making and efficiency.
 
-== Embeddable objects
+This guide explores the various embedding options, including the ThoughtSpot Lightning Web Component (LWC) plugin for Salesforce, Visual Embed SDK, and non-SDK approaches, and provides key recommendations for authentication, customization/branding, and embedding in mobile apps.
 
-ThoughtSpot allows users to create several types of objects. Before we get into the details, it's important to understand that any of the following objects can be easily embed into Salesforce:
+== Embeddable objects
+ThoughtSpot allows users to create several types of objects. You can easily embed any of the following objects into Salesforce:
 
-* *Search* - A self-service interface that allows users to perform searches on data and build visualizations
-* *Answers* - Individual visualizations generated and saved from user search queries
-* *Liveboards* - Interactive dashboards that contain one or more visualizations (Answers)
-* *Spotter* - AI-powered assistant that helps users analyze data using natural language
-* *Full Application* - Allows you to embed the full ThoughtSpot application or the individual application pages
+* *Search* - A self-service interface that allows users to perform searches on data and build visualizations.
+* *Answers* - Individual visualizations generated and saved from user search queries.
+* *Liveboards* - Interactive dashboards that contain one or more visualizations (Answers).
+* *Spotter* - An AI-powered assistant that helps users analyze data using natural language.
+* *Full Application* - Allows embedding the full ThoughtSpot application or the individual application pages.
 
 == Embedding methods
-There are two development options for this integration:
 
-* Embedding with Visual Embed SDK
-* iFrame embedding without the SDK
+You can embed ThoughtSpot in Salesforce using the following methods:
 
-=== Visual Embed SDK
-If you are using the `Salesforce Lightning platform`, we highly recommend using ThoughtSpot's Visual Embed SDK as it provides maximum flexibility and allows you to create highly customized solutions across all Salesforce Cloud products.
+[width="100%" cols="4,8"]
+[options='header']
+|=====
+| Embedding method | Description
 
-==== Key considerations
+| ThoughtSpot supported LWC Plugin
+| ThoughtSpot-managed Lightning Web Component (LWC) plugin for Salesforce enables seamless embedding of Liveboards and Spotter directly within Salesforce.
 
-* Simplified integration using Lightning Web Components (LWC)
-* Enhanced customization and interactivity
-* Support for authentication mechanisms like SAML and Trusted Authentication
+This is the recommended approach for most Salesforce Lightning environments.
 
-=== iFrame embedding
-For organizations using the `Salesforce Classic platform`, or that prefer not to use the SDK, embedding ThoughtSpot can be achieved via iframes. This method is simpler, but considered a legacy approach for embedding.
+| Custom LWC with Visual Embed SDK
+| For maximum flexibility and customization, use the Visual Embed SDK within your own custom LWC. This method supports embedding all ThoughtSpot components such as Liveboards, Spotter, Search, Answers and full application experience, and allows for deep integration with Salesforce Cloud products.
+
+| iFrame embedding (without SDK)
+| For Salesforce Classic or when SDK/LWC plugin use is not possible, embed ThoughtSpot using a simple iFrame. This legacy approach is quick to implement but has limitations in authentication, event handling, and customization.
+|=====
+
+== Key considerations
+
+[width="100%" cols="1,1,1,1"]
+[options='header']
+|=====
+| Capability
+| ThoughtSpot LWC Plugin (managed package)
+| Custom LWC with SDK
+| iFrame via Visualforce/Apex
+
+| Setup effort
+| Low +
+
+Install, drag and drop in Lightning App Builder, and configure props
+
+| Medium/High +
+
+Build LWC, handle authentication, events, and testing
+| Low/Medium +
+
+Quick to place, but manual parameter and authentication handling is required
+
+| Supported ThoughtSpot experiences
+
+| Liveboards and Spotter
+
+| All SDK-supported components +
+(Liveboards, Spotter, Search, Answers, Full application)
+
+| Any embeddable ThoughtSpot URL
 
-==== Key considerations
+| Record-aware context +
+(for example, Account/Opportunity filters)
+| Built-in support +
 
-* Fewer customization options
-* Potential styling limitations
-* SAML authentication only
+Pass recordId/fields via properties
+| Yes +
 
-=== Mobile considerations
-If you require ThoughtSpot content to be available in the Salesforce mobile app, we recommend leveraging the Visual Embed SDK with Single Sign-On (SSO) using Cookieless Trusted Authentication (AuthType.TrustedAuthTokenCookieless). This combination will provide a seamless embedding experience.
+Compose runtime filters from record context
+| Manual +
 
-Now that we understand our options, let's walk through the implementation steps for each method.
+Append query parameters to iFrame URL
+
+| Authentication options
+| SSO and Cookieless Trusted authentication
+| All authentication methods supported, including SSO, Cookieless Trusted authentication and more)
+| Works with SSO only. +
+Limited options
+
+| Salesforce Mobile app
+| Supported when Org authentication is configured
+| Recommended with Cookieless Trusted authentication
+| Inframe authentication limitations
+
+| CSP and security
+| Documented CSP entries; package streamlines most settings
+| You must manage Trusted Sites and CSP allowlists
+| Must allow ThoughtSpot as trusted host
+
+| Branding, styles, themes
+| Configurable via component properties +
+
+Limited deep styling
+| Full control via SDK and custom CSS
+| Minimal +
+
+Basic styling options for ThoughtSpot application only
+
+| Events and callbacks +
+(For filters, drilldown, and more)
+| Common events exposed via component API
+| Full event surface; wire to Apex/Flow
+| None
+
+| Custom Actions
+| None
+| Supported
+| None
+
+| Access to ThoughtSpot REST APIs +
+(Object export, metadata, Answer Service, and so on)
+| Limited
+| Available +
+
+SDK and REST APIs supported
+| None
+
+| Time-to-production
+| Fastest
+| Moderate
+| Fast
+
+| Maintainability and upgrades
+| Vendor-maintained; update by package version
+| You own app lifecycle and SDK versioning
+| You own app lifecycle
+
+| Granular UX control
+| Medium
+| High
+| Low
+|=====
 
 == High-level implementation steps
 
 To embed ThoughtSpot content, complete the steps described in the following sections:
 
-* Embed with Visual Embed SDK
-* Use iFrame to embed
+* xref:sf-integration.adoc#_embed_spotter_or_a_liveboard_using_lwc_plugin[Embed using ThoughtSpot supported LWC plugin]
+* xref:sf-integration.adoc#_embed_with_visual_embed_sdk[Custom LWC with Visual Embed SDK]
+* xref:sf-integration.adoc#_use_iframe_to_embed[Use iFrame to embed]
+
+=== Embed using ThoughtSpot LWC plugin
+For information about the LWC plug-in installation and setup, see link:https://docs.thoughtspot.com/cloud/10.13.0.cl/salesforce-plugin[Integration Guide, window=_blank].
 
-=== Embed with Visual Embed SDK
+=== Custom LWC with Visual Embed SDK
 The Salesforce lightning platform moved developers away from Visualforce to *Lightning Web Components (LWC)*. If you are considering using the SDK, we will assume your Salesforce instance is running on Lightning.
 
 NOTE: To simplify development, we recommend using the link:https://marketplace.visualstudio.com/items?itemName=salesforce.salesforcedx-vscode[Salesforce extensions pack] in Visual Studio Code.
@@ -69,7 +169,7 @@ NOTE: This guide does not cover LWC development. We will assume you have experie
 Any LWC you develop in Salesforce will contain an html, js, and meta.xml file.  Let's walk through a simple Liveboard embed component.
 
 *meta.xml* +
-Defines the metadata values for the component. Specifically, where you want to embed in Salesforce (Record Pages, Experience Cloud, Homepage, etc.), and any configurable parameters for your ThoughtSpot objects (type of object to embed, Cluster URL, Org, etc.).
+Defines the metadata values for the component. Specifically, where you want to embed in Salesforce (Record Pages, Experience Cloud, Homepage, and more), and any configurable parameters for your ThoughtSpot objects (type of object to embed, Cluster URL, Org, and more).
 
 [source, xml]
 ----
@@ -151,8 +251,8 @@ This page defines the div where your ThoughtSpot object will be embedded.
 ** The js file will communicate with  your ThoughtSpot cluster and use the Visual Embed SDK to embed your objects.
 ** Variables set in the `meta.xml` will be tracked and applied in the SDK initialization.
 ** You must import the Visual Embed SDK as a static resource in Salesforce. Get the latest NPM version link:https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/tsembed.js[here].
-** Add Salesforce URL to CORS allowed-domains in ThoughtSpot
-** Update CORS and CSP settings in Salesforce with your ThoughtSpot cluster URL
+** Add Salesforce URL to CORS allowed-domains in ThoughtSpot.
+** Update CORS and CSP settings in Salesforce with your ThoughtSpot cluster URL.
 
 [source, javascript]
 ----
@@ -307,7 +407,7 @@ export default class TsEmbedTemplate extends LightningElement {
 We can provide all the code needed to get you started. Contact your ThoughtSpot Sales representative for access to our Git repositories.
 ====
 
-=== Use iFrame to embed
+=== iFrame embedding
 
 If you have configured ThoughtSpot to use the same SAML provider as your Salesforce instance, you can create a simple Visualforce page that can seamlessly embed a ThoughtSpot Object.
 
@@ -362,5 +462,5 @@ The Visual Embed SDK allows extensive customization, including the following:
 * Controlling user experience via ThoughtSpot’s developer-friendly APIs.
 
 == Conclusion
-Embedding ThoughtSpot into Salesforce enhances analytics accessibility, enabling users to gain insights without leaving their CRM. Whether using the ThoughtSpot SDK or iframe-based approaches, choosing the right authentication and embedding method is essential. By leveraging LWC and customizing ThoughtSpot’s appearance, organizations can create a seamless and powerful analytics experience within Salesforce.
+Embedding ThoughtSpot into Salesforce enhances analytics accessibility, enabling users to gain insights without leaving their CRM. Whether using the ThoughtSpot LWC plugin, Visual Embed SDK or iframe-based approaches, choosing the right authentication and embedding method is essential. By leveraging LWC and customizing ThoughtSpot’s appearance, organizations can create a seamless and powerful analytics experience within Salesforce.