diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..521816585 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,36 @@ +name: Vale + +on: + pull_request: + branches: + - main + - release + +jobs: + vale: + name: Lint prose (ts-docs) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install AsciiDoc dependencies + run: sudo apt-get install -y asciidoctor + + - name: Run Vale + uses: errata-ai/vale-action@v2 + with: + # CI config: ts-docs rules only, error level gate. + # Does not run vale sync — no package downloads needed. + vale_flags: "--config=.vale-ci.ini" + # Run on all files; filter_mode=added limits PR annotations + # to lines added/changed in this PR only. + files: all + filter_mode: added + # Fail the build on errors (merge conflict markers, + # unfilled placeholders). Warnings are reported but + # do not block the PR. + fail_on_error: true + reporter: github-pr-review + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index d07bcc884..366f88c39 100644 --- a/.gitignore +++ b/.gitignore @@ -106,6 +106,11 @@ docs/public/ # TernJS port file .tern-port +# Vale prose linter — downloaded packages (committed: ts-docs style + ts-vocab) +# Run `vale sync` after cloning to download these. +.vale/styles/Google/ +.vale/styles/Microsoft/ + # Code editors or IDEs .vscode/ @@ -114,5 +119,10 @@ modules/**/generated/ # PyCharm and Mac .idea +# Exception: share IntelliJ project dictionary so the team's +# ThoughtSpot-specific terms don't show as spell-check typos. +!.idea/ +!.idea/dictionaries/ +!.idea/dictionaries/*.xml .DS_store *.swp diff --git a/.vale-ci.ini b/.vale-ci.ini new file mode 100644 index 000000000..15c17fbb5 --- /dev/null +++ b/.vale-ci.ini @@ -0,0 +1,22 @@ +# ============================================================= +# .vale-ci.ini — CI-only Vale configuration +# ============================================================= +# Used exclusively by the GitHub Actions vale.yml workflow. +# Runs only the committed ts-docs style; does NOT require +# `vale sync` (no Google / Microsoft packages are downloaded). +# +# Gate: MinAlertLevel = error — only hard errors fail the build. +# ts-docs rules at error level: +# - PreCommitChecks (merge conflict markers, unfilled placeholders) +# ============================================================= + +StylesPath = .vale/styles +MinAlertLevel = error +Vocab = ts-vocab + +[*.{adoc,asciidoc}] +BasedOnStyles = ts-docs + +# Preserve the same AsciiDoc comment and inline-span exclusions as .vale.ini +TokenIgnores = (\/\/.+), (\[(?:\.version-badge[^\]]*|tag [^\]]*|earlyAccess [^\]]*|beta [^\]]*)\][#^][^#^]+[#^]), (\[(NOTE|TIP|WARNING|IMPORTANT|CAUTION|DANGER)\]) +BlockIgnores = (?s)(\/{4}[\s\S]*?\/{4}) diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..dbec69078 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,137 @@ +# ============================================================= +# .vale.ini — ThoughtSpot Developer Docs +# ============================================================= +# SETUP (one-time, after cloning): +# vale sync +# This downloads Google and Microsoft into .vale/styles/ (gitignored). +# The ts-docs custom style and ts-vocab vocabulary are committed to the repo. +# +# USAGE: +# vale path/to/file.adoc +# vale modules/ROOT/pages/ +# +# INTELLIJ IDEA: +# Settings > Tools > Vale > Config: point to this file. +# The AsciiDoc plugin picks up Vale alerts inline. +# ============================================================= + +StylesPath = .vale/styles + +# suggestion = show everything (noisy, good for authoring) +# warning = hide suggestions, show warnings + errors (recommended for review) +# error = show only blocking errors (good for CI gates) +MinAlertLevel = suggestion + +# ---- Packages (downloaded by `vale sync`, then gitignored) -- +Packages = Google, Microsoft + +# ---- Shared vocabulary -------------------------------------- +# Files: .vale/styles/config/vocabularies/ts-vocab/accept.txt +# reject.txt +Vocab = ts-vocab + +# ============================================================= +# Catch-all: disable Vale on every file type not listed below. +# This prevents IDE plugins from running checks on .yml, .json, +# .js, and other non-prose files even when .valeignore is ignored. +# ============================================================= +[*] +BasedOnStyles = + +# ============================================================= +# AsciiDoc files (authored content only) +# Generated pages and node_modules are excluded via .valeignore +# ============================================================= +[*.{adoc,asciidoc}] +BasedOnStyles = Google, Microsoft, ts-docs + +# ---- Comment exclusions ------------------------------------- +# AsciiDoc single-line comments (// text) are ignored. +# AsciiDoc block comments (////...////) are ignored. +# EXCEPTION: comments inside ---- code blocks are part of code +# content and are preserved by Asciidoctor — they are not +# matched by these patterns and continue to be checked. +# Inline role spans are also stripped before style rules run so that +# capitalization checks do not fire on fixed labels: +# [.version-badge.*]#New# [.version-badge.*]#Breaking# +# [tag *]#NEW FEATURE# [tag *]#DEPRECATED# +# [earlyAccess *]#Early Access# [beta *]^Beta^ +# [NOTE] [WARNING] [IMPORTANT] [TIP] [CAUTION] +TokenIgnores = (\/\/.+), (\[(?:\.version-badge[^\]]*|tag [^\]]*|earlyAccess [^\]]*|beta [^\]]*)\][#^][^#^]+[#^]), (\[(NOTE|TIP|WARNING|IMPORTANT|CAUTION|DANGER)\]), ([A-Z][a-zA-Z]+\.[A-Z][a-zA-Z]+) +BlockIgnores = (?s)(\/{4}[\s\S]*?\/{4}) + +# ---- Rule overrides ----------------------------------------- +# Tuned based on audit of alerts against ThoughtSpot developer docs. + +# Vocabulary: managed by ts-vocab; disable built-in Microsoft vocab. +Microsoft.Vocab = NO + +# Headings: sentence case enforced by ts-docs.Headings. +Google.Headings = NO +Microsoft.Headings = NO +Microsoft.HeadingPunctuation = NO +Microsoft.HeadingAcronyms = NO + +# Passive voice: sometimes necessary in reference docs. +Microsoft.Passive = NO +Google.Passive = suggestion + +# Contractions: avoid in formal developer docs. +Microsoft.Contractions = NO + +# List-item punctuation: technical lists often don't end with periods. +Microsoft.Periods = NO + +# Oxford comma: required. +Google.OxfordComma = error + +# URLs: Antora/AsciiDoc handles link formatting; these rules add noise. +Microsoft.GeneralURL = NO +Microsoft.URLFormat = NO + +# Sentence length: covered by ts-docs.SentenceLength. +Microsoft.SentenceLength = NO + +# Parentheses and optional plurals: too noisy for technical API docs. +Google.Parens = NO +Google.OptionalPlurals = NO + +# Google WordList: contains Google-internal product name substitutions +# (for example, Cloud → "Google Cloud Platform") that conflict with +# ThoughtSpot product names. Applicable entries are maintained in +# ts-docs/WordList.yml instead. +Google.WordList = NO + +# Date format: downgraded from error — docs use various date formats +# depending on context (API responses, UI labels, prose). +Microsoft.DateFormat = suggestion +Google.DateFormat = suggestion + +# Colon capitalisation: flags proper nouns and product names after colons. +# Cannot be tuned without rewriting the rule. +Google.Colons = NO +Microsoft.HeadingColons = NO + +# Semicolons: "Use semicolons judiciously" is not actionable feedback. +Google.Semicolons = NO +Microsoft.Semicolon = NO + +# Dotted abbreviations: error-level rule flagging U.S.A.-style patterns. +# Writers are aware of this convention; same check was intentionally +# excluded from ts-docs styles. +Google.Periods = NO + +# Avoided terms: relevant token (and so on) absorbed into ts-docs.DoNotUseTerms. +# Remaining tokens are Microsoft-specific or legitimate in ThoughtSpot docs. +Microsoft.Avoid = NO + +# Wordy phrases: applicable substitutions absorbed into ts-docs.WordList. +# Rule suppressed to avoid duplicate alerts. +Microsoft.Wordiness = NO + +# ============================================================= +# Markdown files +# ============================================================= +[*.{md,markdown}] +BasedOnStyles = Google, Microsoft, ts-docs + diff --git a/.vale/styles/config/vocabularies/ts-vocab/accept.txt b/.vale/styles/config/vocabularies/ts-vocab/accept.txt new file mode 100644 index 000000000..958be61cb --- /dev/null +++ b/.vale/styles/config/vocabularies/ts-vocab/accept.txt @@ -0,0 +1,163 @@ +# ts-vocab/accept.txt +# Terms Vale's spell-check should accept as correctly spelled. +# One entry per line. Regex is supported. +# Add product names, SDK identifiers, and technical terms here +# rather than suppressing spell-check globally. + +# ------------------------------------------------------- +# THOUGHTSPOT PRODUCT AND PLATFORM NAMES +# Prose form - correctly capitalised brand name +# ------------------------------------------------------- +ThoughtSpot +ThoughtSpot Cloud +ThoughtSpot Embedded +Visual Embed SDK +REST API v2 +REST API Playground +ThoughtSpotSDK +ThoughtSpotRestApi +ThoughtSpotDeliveryRole + +# ------------------------------------------------------- +# THOUGHTSPOT LOWERCASE / CODE-CONTEXT VARIANTS +# These appear legitimately in URLs, config parameters, +# variable names, and code - accepted here so the spell +# checker does not flag them. +# ------------------------------------------------------- +thoughtspot +thoughtSpotHost +thoughtSpotUrl +thoughtspot\.cloud +tsconfig +tsEmbedSDK + +# ------------------------------------------------------- +# SPOTTER / AI PRODUCT NAMES +# ------------------------------------------------------- +Spotter +SpotterAgent +SpotterCode +SpotterDocs +SpotterEmbed +SpotterAgentEmbed +SpotterAgentEmbedConfig +SpotterAgentEmbedViewConfig +SpotterChatConnectors +SpotterChatConnectorResources +SpotterChatDelete +SpotterChatMenu +SpotterChatModeSwitcher +SpotterChatRename +SpotterChatViewConfig +SpotterConversationDeleted +SpotterConversationRenamed +SpotterConversationSelected +SpotterCSS +SpotterEmbedViewConfig +SpotterFeedback +SpotterInit +SpotterMessage +SpotterNewChat +SpotterPastChatBanner +SpotterQueryTriggered +SpotterSearch +SpotterSidebarFooter +SpotterSidebarHeader +SpotterSidebarToggle +SpotterSidebarViewConfig +SpotterTokenQuickEdit +SpotterWarningsBanner +SpotterWarningsOnTokens +ConversationEmbed + +# ------------------------------------------------------- +# EMBED SDK COMPONENT NAMES +# ------------------------------------------------------- +AppEmbed +LiveboardEmbed +LiveboardEmbedController +LiveboardEmbedView +SearchEmbed +SearchBarEmbed +SpotterAgentEmbed +PreRenderedLiveboardEmbed +TsEmbedSDK +SwiftEmbedSDK +TSEmbedConfig +EmbedConfig +visual-embed-sdk + +# ------------------------------------------------------- +# LIVEBOARD AND DATA TYPES +# ------------------------------------------------------- +Liveboard +Liveboards +LiveboardActionData +LiveboardConfigStyle +LiveboardContextActionData +LiveboardController +LiveboardData +LiveboardInfo +LiveboardPureStyle +LiveboardRendered +LiveboardScheduleData +LiveboardSchedules +LiveboardStyle +LiveboardStyleConfig +LiveboardStylePanel +LiveboardUsers +LiveboardView +LiveboardViewConfig + +# ------------------------------------------------------- +# AUTH AND CONFIG TYPES +# ------------------------------------------------------- +AuthType +TrustedAuthToken +TrustedAuthTokenCookieless +TrustedAuthCookieless +EmbedEvent +HostEvent +RuntimeFilter +RuntimeSort +OAuthRedirectWindowType +ConnectionType + +# ------------------------------------------------------- +# ORG / MULTI-TENANCY TERMS +# ThoughtSpot uses "Org" (not "organization") for its +# multi-tenancy unit. "Orgs" is the accepted plural. +# ------------------------------------------------------- +Org +Orgs +org +orgs + +# ------------------------------------------------------- +# PLATFORM AND FEATURE TERMS +# ------------------------------------------------------- +SpotApps +SpotDev +spotdev +TML +GUID +Antora +TSCLI +tscli + +# Worksheet is deprecated in prose (WordList.yml flags it). +# Retained here so the spell checker does not flag the term +# in code blocks or SDK parameter contexts (e.g. worksheetId). +Worksheet +Worksheets +worksheetId +worksheetIds + +# ------------------------------------------------------- +# INTEGRATION AND CLOUD +# ------------------------------------------------------- +Snowflake +Databricks +Salesforce +Vercel +Pendo diff --git a/.vale/styles/config/vocabularies/ts-vocab/reject.txt b/.vale/styles/config/vocabularies/ts-vocab/reject.txt new file mode 100644 index 000000000..0b2a6e00f --- /dev/null +++ b/.vale/styles/config/vocabularies/ts-vocab/reject.txt @@ -0,0 +1,29 @@ +# ts-vocab/reject.txt +# Plain English terms that are wrong in ALL contexts (prose, headings). +# Vale flags any match as a spelling error. +# One entry per line. Regex is supported. +# +# SCOPE NOTE: reject.txt runs through the spell checker. +# Code blocks are excluded by Vale's Asciidoctor parser, but +# inline code and attribute values may still be checked. +# For deprecated SDK class names, use WordList.yml (tokens:) +# which is strictly prose-scoped. +# +# Use this file only for plain English words that are ALWAYS +# wrong in authored prose, regardless of context. + +# ------------------------------------------------------- +# DEPRECATED PRODUCT / FEATURE NAMES +# "pinboard" and "pinboards" are plain English words that +# should always be replaced with Liveboard in prose. +# Word boundaries prevent matching PinboardEmbed etc. +# ------------------------------------------------------- +\bpinboard\b +\bpinboards\b +\bPinboard\b +\bPinboards\b + +# ------------------------------------------------------- +# ADD DEPRECATED OR BANNED TERMS BELOW +# ------------------------------------------------------- +# OldProductName diff --git a/.vale/styles/ts-docs/Abbreviations.yml b/.vale/styles/ts-docs/Abbreviations.yml new file mode 100644 index 000000000..27ec19ce2 --- /dev/null +++ b/.vale/styles/ts-docs/Abbreviations.yml @@ -0,0 +1,153 @@ +# ts-docs/Abbreviations.yml +# Flags acronyms used without a definition earlier on the same page. +# Expected format on first use: Full Name (ACRONYM) +# Example: "Representational State Transfer (REST)" +# +# How it works: +# For each bare acronym (first pattern), Vale checks whether the +# spelled-out form with the acronym in parentheses (second pattern) +# has appeared before it in the document. If not, it flags that use. +# Once a definition is added, all subsequent bare uses are cleared. +# scope: text means the entire file is the unit of comparison. +extends: conditional +message: "Define '%s' on first use: spell it out as 'Full Name (ABBR)'." +level: warning +ignorecase: false +# Bare acronym - three or more consecutive uppercase letters, optional plural s +first: '\b([A-Z]{3,}s?)\b' +# Spelled-out form followed by the acronym in parentheses +# e.g. "Representational State Transfer (REST)" +second: '(?:[A-Za-z][A-Za-z]* ){1,}\(([A-Z]{3,})\)' +scope: text + +exceptions: + # Include well-known acronyms and abbreviations that need not be defined in technical documentation + # If the documentation is intended for non-technical audience, define these on first use + # Add THOUGHTSPOT and product-specific acronyms/abbreviations that need not be expanded/defined. + - AI + - API + - APIs + - AWS + - BI + - CD + - CDN + - CI + - CLI + - CSS + - CSV + - DOM + - ETL + - FAQ + - GA + - GCP + - GUID + - HTML + - HTTP + - HTTPS + - IDE + - JSON + - JWT + - LLM + - MFA + - OAuth + - PDF + - PNG + - REST + - SAML + - SDK + - SQL + - SSH + - SSL + - SpotIQ + - SSO + - TLS + - URI + - URL + - URLs + - UI + - UX + - XLSX + - XML + - YAML + + # ------------------------------------------------------- + # SECURITY / AUTH + # Well-known to the developer audience — no expansion needed. + # (Domain-specific acronyms such as ABAC, IAM, RLS, RBAC, + # ACL, OIDC, IDP are NOT listed here — they should be + # expanded on first use in body text.) + # ------------------------------------------------------- + - ADFS + - CORS + - CRUD + - CSP + - SHA + - STS + - XSS + + # ------------------------------------------------------- + # HTTP METHODS + # Standard REST verbs used throughout API reference pages. + # ------------------------------------------------------- + - DELETE + - GET + - OPTIONS + - PATCH + - POST + - PUT + + # ------------------------------------------------------- + # WEB / FILE FORMATS / STANDARDS + # ------------------------------------------------------- + - AJAX + - CNAME + - DNS + - GMT + - ISO + - JPEG + - NPM + - POSIX + - SVG + - UTC + - WOFF + - ZIP + + # ------------------------------------------------------- + # CLOUD / INFRASTRUCTURE / DATABASE + # ------------------------------------------------------- + - JDK + - RDS + + # ------------------------------------------------------- + # DEVELOPMENT TOOLS / PROCESSES + # ------------------------------------------------------- + - CICD + - GPT + - GUI + - UAT + - UDF + + # ------------------------------------------------------- + # ENTERPRISE / INTEGRATION + # ------------------------------------------------------- + - HANA + - SAP + - SMS + + # ------------------------------------------------------- + # THOUGHTSPOT-SPECIFIC TERMS + # All-caps forms of ThoughtSpot product names and + # constants (changelogs, SDK code, API reference pages). + # ------------------------------------------------------- + - LIVEBOARD + - SPOTTER + - THOUGHTSPOT + - TQL + - TSE + - VIZ + + # ------------------------------------------------------- + # MISCELLANEOUS + # ------------------------------------------------------- + - FAQs + - JSESSIONID diff --git a/.vale/styles/ts-docs/Ampersands.yml b/.vale/styles/ts-docs/Ampersands.yml new file mode 100644 index 000000000..e9a606b9f --- /dev/null +++ b/.vale/styles/ts-docs/Ampersands.yml @@ -0,0 +1,13 @@ +# ts-docs/Ampersands.yml +# Flags ampersands used in place of "and" in prose. +# ThoughtSpot style: spell out "and" in full. +# Exception: ampersands are allowed in formal names and +# common abbreviations (Q&A, R&D, P&L) where no spaces +# surround the symbol - those forms are not matched here. +extends: existence +message: "Spell out 'and' in full. Use '&' only in formal names (e.g. Q&A, R&D)." +level: warning +tokens: + # Matches & surrounded by spaces - the prose "and" usage. + # Does NOT match Q&A, R&D, or other no-space abbreviations. + - '\s&\s' diff --git a/.vale/styles/ts-docs/AsciiDocSyntax.yml b/.vale/styles/ts-docs/AsciiDocSyntax.yml new file mode 100644 index 000000000..698a46446 --- /dev/null +++ b/.vale/styles/ts-docs/AsciiDocSyntax.yml @@ -0,0 +1,53 @@ +# ts-docs/AsciiDocSyntax.yml +# Flags AsciiDoc markup and convention issues that cause rendering +# problems in Antora or break accessibility and link integrity. +# All patterns run on raw source text before Vale strips markup. +# +# Checks: +# - Unresolved attribute references {attr-name} +# - Bare or malformed URL macros +# - Missing blank line before list items +# - Source blocks without a language tag +# - Image macros with empty alt text (accessibility) +# - Xref and hyperlink convention violations (Antora) +extends: existence +message: "AsciiDoc markup or convention issue: '%s'. Check formatting." +level: warning +raw: + # ---- Attribute references -------------------------------- + # Unresolved attribute references (common in Antora content). + # Matches {attr-name} that is NOT followed by a + continuation. + - '\{[a-z][a-z0-9-]+\}(?!\+)' + + # ---- URL macros ------------------------------------------ + # Bare URLs without a link macro - render literally in some outputs. + # Matches http(s)://... followed by an unclosed bracket. + - 'https?://\S+\[(?!\])' + + # ---- List formatting ------------------------------------- + # Missing blank line before a list item - common cause of list + # items rendering as plain text instead of a list. + - '^[*-]\s' + + # ---- Source blocks --------------------------------------- + # Source block without a language tag produces unhighlighted output. + # Use [source,language], e.g. [source,javascript] or [source,bash]. + - '^\[source\]$' + - '^\[source,\s*\]$' + + # ---- Image alt text (accessibility) ---------------------- + # Image macros with empty alt text break screen readers (WCAG 2.1 AA). + # FAIL: image::diagram.png[] PASS: image::diagram.png[API flow diagram] + # FAIL: image:icon.png[] PASS: image:icon.png[Settings icon] + - 'image::[^\[]+\[\s*\]' + - 'image:[^:][^\[]+\[\s*\]' + + # ---- Xref and hyperlink conventions (Antora) ------------- + # Double-bracket cross-reference: Antora recommends xref: syntax. + - '<<[a-zA-Z_][^>]*>>' + # xref: macro with empty display text — readers need descriptive text. + - 'xref:[^\[]+\[\s*\]' + # link: macro for an internal .adoc file — use xref: instead. + - 'link:[^\[]*\.adoc\[' + # External link macro with empty display text. + - 'link:https?://[^\[]+\[\s*\]' diff --git a/.vale/styles/ts-docs/DoNotUseTerms.yml b/.vale/styles/ts-docs/DoNotUseTerms.yml new file mode 100644 index 000000000..08e2c3673 --- /dev/null +++ b/.vale/styles/ts-docs/DoNotUseTerms.yml @@ -0,0 +1,71 @@ +# ts-docs/DoNotUseTerms.yml +# Flags phrases and words that add no meaning, violate the ThoughtSpot +# developer docs style guide, or are inappropriate in technical writing. +# Renamed from BannedPhrases.yml; expanded with IBM/RedHat-sourced additions. +extends: existence +message: "Avoid '%s' in technical documentation. Rewrite the sentence." +link: '' +level: warning +ignorecase: true +tokens: + # ---- Filler / hedge words -------------------------------- + - 'simply' + # Excludes "just-in-time" and "just in time" (legitimate technical phrases). + - 'just(?![ -]in[ -]time)' + - '\beasy\b' + - '\beast\b' + - 'easily' + - 'trivial' + - 'obviously' + - 'of course' + - 'clearly' + - 'basically' + - 'essentially' + - 'actually' + - '\bvery\b' + - '\bquite\b' + - '\breally\b' + + # ---- Vague time / marketing language -------------------- + - '\bsoon\b' + - 'new and improved' + - 'state of the art' + - 'cutting[- ]edge' + - 'best in class' + - 'world[- ]class' + - 'industry[- ]leading' + - 'best of breed' + + # ---- Redundant meta-commentary -------------------------- + - 'as mentioned (above|previously|earlier)' + - 'as stated (above|previously|earlier)' + - 'needless to say' + - 'it goes without saying' + - 'it should be noted' + - 'it is important to note' + + # ---- "Please" in technical writing ---------------------- + # Technical docs use imperative voice; "please" is informal. + - '\bplease\b' + + # ---- Ambiguous constructions (IBM/RedHat) --------------- + # and/or: rewrite as "a and b", "a or b", or "a, b, or both". + - 'and/or' + # "respectively" forces readers to mentally match items across lists; + # rewrite as explicit pairings instead. + - '\brespectively\b' + + # ---- Vague enumerations (Microsoft.Avoid) --------------- + # "and so on" is vague — list all items explicitly or use "such as". + - 'and so on' + + # ---- Placeholder jargon --------------------------------- + # foo/fubar are developer in-jokes; use descriptive variable names. + - '\bfoo\b' + - '\bfubar\b' + + # ---- ThoughtSpot-specific banned phrases ---------------- + # Add deprecated product names, old slogans, or phrases + # prohibited by legal or brand guidelines. + # - 'OldBrandName' + # - 'deprecated-feature' diff --git a/.vale/styles/ts-docs/Headings.yml b/.vale/styles/ts-docs/Headings.yml new file mode 100644 index 000000000..21b9e4e8e --- /dev/null +++ b/.vale/styles/ts-docs/Headings.yml @@ -0,0 +1,125 @@ +# ts-docs/Headings.yml +# Enforces sentence-case headings (capitalise only the first word +# and proper nouns). Follows Google and Red Hat conventions. +extends: capitalization +message: "'%s' should use sentence case — capitalise only the first word and noun phrases." +level: warning +scope: heading +match: $sentence +# Add every proper noun, product name, acronym, and brand term +# that should remain capitalised mid-heading. +exceptions: + # ------------------------------------------------------- + # STANDARD TECHNICAL ACRONYMS + # ------------------------------------------------------- + - API + - APIs + - CLI + - UI + - UX + - URL + - URLs + - URI + - HTTP + - HTTPS + - REST + - YAML + - JSON + - XML + - HTML + - CSS + - SQL + - SSH + - TLS + - SSL + - OAuth + - JWT + - SDK + - IDE + - CI + - CD + - AWS + - GCP + - Azure + - Linux + - macOS + - Windows + - GitHub + - GitLab + - Docker + - Kubernetes + + # ------------------------------------------------------- + # THOUGHTSPOT PRODUCT AND BRAND NAMES + # ------------------------------------------------------- + - ThoughtSpot + - Spotter + - SpotterAgent + - SpotterCode + - SpotterDocs + - SpotApps + - SpotDev + + # Embed SDK component names + - AppEmbed + - LiveboardEmbed + - SearchEmbed + - SearchBarEmbed + - SpotterEmbed + - SpotterAgentEmbed + - ConversationEmbed + - PreRenderedLiveboardEmbed + + # Product feature nouns + - Liveboard + - Liveboards + - Worksheet + - Worksheets + - TML + - GUID + + # SDK event types (appear in headings as EmbedEvent.Load, HostEvent.Pin, etc.) + - EmbedEvent + - HostEvent + + # Auth and security terms + - TrustedAuthToken + - TrustedAuthTokenCookieless + - AuthType + - SAML + - SSO + - CORS + - RBAC + - ABAC + - RLS + - CRUD + + # Multi-tenancy + - Org + - Orgs + + # Languages and frameworks + - JavaScript + - TypeScript + - React + - Antora + + # Additional acronyms + - CSV + - PDF + - JWT + + # Cloud and integration partners + - Salesforce + - Snowflake + - Databricks + - Google + - Microsoft + - Slack + - Vercel + - Pendo + + # ------------------------------------------------------- + # ADD YOUR OWN PROPER NOUNS BELOW + # Format: - TermToKeepCapitalised + # ------------------------------------------------------- diff --git a/.vale/styles/ts-docs/LinkText.yml b/.vale/styles/ts-docs/LinkText.yml new file mode 100644 index 000000000..bccbb8329 --- /dev/null +++ b/.vale/styles/ts-docs/LinkText.yml @@ -0,0 +1,17 @@ +# ts-docs/LinkText.yml +# Flags non-descriptive link text that violates accessibility +# and ThoughtSpot style guidelines. +# Rule: linked text must tell the reader what they are clicking on. +# Do not link more than three to four words. +extends: existence +message: "Avoid '%s' as link text. Use words that tell the reader what they are clicking on." +level: warning +ignorecase: true +tokens: + - 'click here' + - 'click this link' + - 'click here to' + - 'read more' + - 'learn more' + - 'here\.' + - 'this link' diff --git a/.vale/styles/ts-docs/PreCommitChecks.yml b/.vale/styles/ts-docs/PreCommitChecks.yml new file mode 100644 index 000000000..0a4800da1 --- /dev/null +++ b/.vale/styles/ts-docs/PreCommitChecks.yml @@ -0,0 +1,54 @@ +# ts-docs/PreCommitChecks.yml +# Flags content that must be removed or replaced before committing. +# Covers unfilled template tokens and Git merge conflict markers. +# Applied to raw source (raw:) so tokens in AsciiDoc attributes +# and headers are also caught. +extends: existence +message: "Pre-commit issue: '%s' — remove or replace before committing." +level: error +nonword: true +raw: + # ---- Standard template tokens --------------------------- + - '' + - '' + - 'DOC-XXXX' + - 'JIRA-REF' + - 'ENG-XXXX' + - 'your-style-guide-url' + + # ---- In-template TODO comments -------------------------- + - 'TODO: verify with engineering' + - 'TODO: verify scope with engineering' + - 'TODO: add screenshot' + - 'TODO: confirm with' + + # ---- ThoughtSpot template tokens ------------------------ + # Tokens used in modules/_templates/*.adoc that must be + # replaced before a page is published. + - '' + - '' + - '' + - 'your-instance' + - 'liveboard-GUID' + - '' + - '' + - '' + - '' + - '' + + # ---- Add your own template placeholder patterns --------- + # - '' + + # ---- Git merge conflict markers ------------------------- + # These must never appear in committed or published content. + - '^<{7}\s.*$' + - '^={7}$' + - '^>{7}\s.*$' diff --git a/.vale/styles/ts-docs/RepeatedWords.yml b/.vale/styles/ts-docs/RepeatedWords.yml new file mode 100644 index 000000000..1752ad930 --- /dev/null +++ b/.vale/styles/ts-docs/RepeatedWords.yml @@ -0,0 +1,17 @@ +# ts-docs/RepeatedWords.yml +# Flags consecutive repeated words, e.g. "the the" or "and and". +# Ported from RedHat.RepeatedWords. +extends: repetition +message: "'%s' is repeated. Remove the duplicate." +level: warning +ignorecase: false +alpha: true +action: + name: edit + params: + - regex + - '(\w+)(\s\w+)' + - "$1" +tokens: + - '[^\s\.]+' + - '[^\s]+' diff --git a/.vale/styles/ts-docs/SentenceLength.yml b/.vale/styles/ts-docs/SentenceLength.yml new file mode 100644 index 000000000..36a32392c --- /dev/null +++ b/.vale/styles/ts-docs/SentenceLength.yml @@ -0,0 +1,11 @@ +# ts-docs/SentenceLength.yml +# Flags sentences in paragraph prose that exceed 30 words. +# Code blocks, headings, lists, and other non-prose content +# are ignored automatically by Vale's AsciiDoc parser. +# Raise max if the rule is too noisy for your content. +extends: occurrence +message: "Long sentence (%d words). Aim for 30 or fewer." +level: suggestion +scope: sentence +max: 30 +token: '\b\w+' diff --git a/.vale/styles/ts-docs/SmartQuotes.yml b/.vale/styles/ts-docs/SmartQuotes.yml new file mode 100644 index 000000000..4ebbf970b --- /dev/null +++ b/.vale/styles/ts-docs/SmartQuotes.yml @@ -0,0 +1,16 @@ +# ts-docs/SmartQuotes.yml +# Flags curly/smart quotation marks in raw AsciiDoc source. +# AsciiDoc source should use straight ASCII quotes; the renderer +# applies typographic quotes as needed. Curly quotes in source +# can cause rendering issues and encoding problems. +# Ported from RedHat.SmartQuotes. +extends: substitution +message: "Do not use curly/smart quotation marks. Use straight ASCII quotes instead of '%s'." +level: warning +nonword: true +scope: raw +action: + name: replace +swap: + '\u2018|\u2019': "'" + '\u201C|\u201D|\u201F|\u2033|\u2036': '"' diff --git a/.vale/styles/ts-docs/WordList.yml b/.vale/styles/ts-docs/WordList.yml new file mode 100644 index 000000000..defae7967 --- /dev/null +++ b/.vale/styles/ts-docs/WordList.yml @@ -0,0 +1,212 @@ +# ts-docs/WordList.yml +# Adapted from github.com/splunk/vale-splunk-style-guide +# Flags variant or deprecated terms and suggests the preferred form. +extends: substitution +message: "Use '%s' instead of '%s'." +level: warning +ignorecase: false +action: + name: replace +swap: + # ------------------------------------------------------- + # UI INTERACTION TERMS + # ------------------------------------------------------- + 'click on': click + 'hit': press + 'depress': press + 'check out': see + + # ------------------------------------------------------- + # DIRECTIONAL REFERENCES + # Replace spatial directions with relative document refs + # ------------------------------------------------------- + 'above': the previous section + 'below': the following section + + # ------------------------------------------------------- + # WORDY PHRASES - replace with concise alternatives + # ------------------------------------------------------- + 'in order to': to + 'due to the fact that': because + 'at this point in time': now + 'at present': now + 'basic steps': steps + 'be sure to': make sure + 'in the event that': if + 'prior to': before + 'subsequent to': after + 'with regard to': about + 'with respect to': about + 'as per': per + 'a number of': several|many + + # ------------------------------------------------------- + # TECHNICAL TERM CONSISTENCY + # ------------------------------------------------------- + 'boolean': Boolean + 'can not': cannot + 'checkbox': check box + 'carriage return': line break + 'utilize': use + 'utilization': usage + 'leverage': use + 'functionality': features + 'performant': high-performance + + # ------------------------------------------------------- + # INCLUSIVE LANGUAGE + # ------------------------------------------------------- + 'whitelist': allowlist + 'blacklist': blocklist + 'master branch': main branch + 'dummy': placeholder|stub + 'sanity check': confidence check|smoke test + + # ------------------------------------------------------- + # THOUGHTSPOT PRODUCT-SPECIFIC TERMS + # Applies to prose text only - code blocks, URLs, and + # parameter/variable names are excluded by Vale's + # AsciiDoc parser before these rules run. + # ------------------------------------------------------- + + # Deprecated plain-English feature names (prose only) + 'pinboard': Liveboard + 'Pinboard': Liveboard + 'sage embed': Spotter embed + 'sage search': natural language search + 'Ask sage': Ask AI + + # Worksheet deprecated - replaced by Model. + # Word boundaries ensure worksheetId and other SDK parameter + # names in code are never matched - only bare prose words fire. + # Context guide: + # UI element reference -> Model (capitalized) + # Descriptive prose -> model or data model (lowercase) + '\bworksheet\b': model + '\bWorksheet\b': Model + '\bworksheets\b': models + '\bWorksheets\b': Models + + + # Deprecated SDK class names referenced in prose + # (e.g. "Use SageEmbed to..." in a migration guide) + 'SageEmbed': SpotterEmbed + 'SageEmbedQuery': SpotterEmbed + 'PinboardEmbed': LiveboardEmbed + 'PinboardEmbedViewConfig': LiveboardViewConfig + + # ------------------------------------------------------- + # THOUGHTSPOT WRITING CONVENTIONS + # Source: ThoughtSpot style guide + # ------------------------------------------------------- + + # Brand abbreviations - always write the full name in external content + '\bTS\b': ThoughtSpot + '\bTSE\b': ThoughtSpot Embedded + + # All-caps variant — incorrect casing, suggest correct brand name + '\bTHOUGHTSPOT\b': ThoughtSpot + + # Deprecated product name - replaced by ThoughtSpot Embedded + '\bThoughtSpot Everywhere\b': ThoughtSpot Embedded + + # Acronym style - no periods (use AI not A.I.) + 'A\.I\.': AI + 'B\.I\.': BI + + # Compound word and hyphenation conventions + 'dropdown': drop-down + 'drop down': drop-down + '[Ee]-mail': email + '[Ee]-book': ebook + 'front line': frontline + 'front-line': frontline + 'white paper': whitepaper + + # ThoughtSpot product and feature naming + 'liveboards': Liveboards + 'live analytics': Live Analytics + 'data lakehouse': lakehouse + '[Rr]eal-time insights': Instant insights + 'zero to search': zero-to-search + + # Use low-code, not no-code + 'no-code': low-code + + # ------------------------------------------------------- + # PLAIN ALTERNATIVES (from IBM/RedHat SimpleWords) + # Prefer plain alternatives in technical writing. + # ------------------------------------------------------- + 'commence': begin + 'initiate': start|begin + 'numerous': many + 'a lot of': many|much + + # ------------------------------------------------------- + # WORDY PHRASES (from Microsoft.Wordiness) + # ------------------------------------------------------- + 'has the ability to': can + 'has the capacity to': can + 'whether or not': whether + 'despite the fact that': although + 'because of the fact that': because + 'successfully complete': complete + 'take into account': consider + 'in lieu of': instead of + 'make reference to': refer to + 'made reference to': referred to + 'with the exception of': except for + 'except when': unless + 'not in a position to': unable + 'in many cases': often + 'in most cases': usually + 'a (?:large)? majority of': most + 'a myriad of': myriad + 'any and all': all + 'at all times': always + 'at a later date': later + 'continue on': continue + 'during the period of': during + 'during the time that': while + 'establish connectivity': connect + 'for the duration of': during + 'in an effort to': to + 'in between': between + 'in spite of the fact that': although + 'pertaining to': about + 'until such time as': until + + # ------------------------------------------------------- + # TERMS ADOPTED FROM GOOGLE DEVELOPER STYLE GUIDE + # Google.WordList is suppressed in .vale.ini; applicable + # entries are maintained here instead. + # Excluded: Google-specific product names (Cloud, Container + # Engine, Developers Console), Android/mobile-only terms, + # and entries already covered above. + # ------------------------------------------------------- + + # Auth and security + '(?:OAuth ?2|Oauth)': OAuth 2.0 + 'authN': authentication + 'authZ': authorization + 'SHA1': SHA-1 + 'sign into': sign in to + + # Capitalization and spelling + '(?:WiFi|wifi)': Wi-Fi + 'HTTPs': HTTPS + '\burl\b': URL + 'synch': sync + 'k8s': Kubernetes + + # Technical writing conventions + 'data are': data is + 'file name': filename + 'a\.k\.a|aka': or|also known as + 'vs\.': versus + 'approx\.': approximately + 'autoupdate': automatically update + + # UI actions + 'un(?:check|select)': clear + '(?:kill|terminate|abort)': stop|exit|cancel|end diff --git a/.valeignore b/.valeignore new file mode 100644 index 000000000..b92abd6c5 --- /dev/null +++ b/.valeignore @@ -0,0 +1,24 @@ +# Vale ignore patterns — syntax mirrors .gitignore +# Paths matched here are skipped entirely by `vale`. + +# Build output and dependencies +node_modules/ +public/ +.cache/ +dist/ +lib/ +coverage/ + +# Auto-generated TypeDoc pages — not authored prose +modules/ROOT/pages/generated/ + +# Legacy / deprecated embed pages (kept for reference, not linted) +# Uncomment if you want to suppress alerts on legacy pages: +# modules/ROOT/pages/embed-pinboard.adoc +# modules/ROOT/pages/pinboard-export-api.adoc + +# Vale style packages and config — not authored prose +.vale/styles/Google/ +.vale/styles/Microsoft/ +.vale/styles/ts-docs/ +.vale/styles/config/ diff --git a/modules/ROOT/pages/3rd-party-script.adoc b/modules/ROOT/pages/3rd-party-script.adoc deleted file mode 100644 index a978ada50..000000000 --- a/modules/ROOT/pages/3rd-party-script.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= External tools and script integration -:toc: true -:toclevels: 2 - -:page-title: Integrate external tools and allow scripts -:page-pageid: external-tool-script-integration -:page-description: Security settings for embedding - -ThoughtSpot supports integrating third-party apps such as Mixpanel, Pendo, LogRocket, and more in your embed. If you are using third-party tools to track usage, trace, log, or onboard your application users, you can seamlessly integrate these tools with ThoughtSpot embed and add custom JavaScript. This feature is disabled by default on ThoughtSpot instances. To enable this feature, contact ThoughtSpot Support. - -[IMPORTANT] -==== -While ThoughtSpot allows the injection of custom JavaScript, it is important to be aware of the associated security risks, particularly Cross-Site Scripting (XSS). XSS is a vulnerability that can enable malicious actors to inject and execute unauthorized scripts within a trusted environment. This can lead to data breaches, unauthorized access to user sessions, and compromised system integrity. ThoughtSpot strongly recommends reviewing security guidelines before activating this feature in your instances and exercising caution when integrating third-party tools into your embedded application. -==== - -== Security considerations - -Before requesting ThoughtSpot Support to enable this feature on your instance, do the following: - -* Review the security risks associated with custom-hosted scripts and understand the potential consequences of XSS attacks. -* Implement security controls and measures to validate hosted scripts and mitigate potential vulnerabilities. - -== Feature enablement - -Enabling third-party tools on embed involves two steps: - -. Request for feature activation and provide the script details to ThoughtSpot Support -. Adding the script sources to the CSP allowlist - -=== Request for feature enablement - -Create a ThoughtSpot Support ticket to enable the feature on your instance. In your request, specify the domain URLs that will host the scripts in your embedding environment. - -Wait for ThoughtSpot Support to validate and approve, and then add the domain that hosts the script to the CSP allowlist on your instance. This step will ensure that only the trusted and vetted domains are allowed to run scripts in your application environment. - -=== Add script source to CSP allowlist -After the script hosting URL is approved and configured by ThoughtSpot Support, you must add the JavaScript hosting domain to the CSP allowlist. This step requires administration privileges, so make sure you log in to ThoughtSpot with your administrator credentials. - -. In your ThoughtSpot application, navigate to *Develop* > *Customizations* > *Security Settings*. -. If your instance has the Orgs feature enabled, ensure that you are in the *All Orgs* context. -. On the *Security Settings* page, click *Edit* and turn on the *CSP script-src domains* toggle switch. -+ -[.widthAuto] -[.bordered] -image::./images/csp-script-domain.png[CSS script-src domain] -. Add the script hosting domain. -. Click *Save changes*. - -[NOTE] -==== -* The *CSP script-src domains* section is visible to users with administrative privileges only if the third-party integration feature is enabled on your instance. -* The *CSP script-src domains* cannot be enabled and configured at the Org level. When configured, this setting will apply to all the Orgs configured on your instance. -==== - -=== Allow Websocket endpoints -If your tool uses WebSockets, add the tool’s `wss://` endpoint to the CSP and CORS allowlists in ThoughtSpot. This enables secure WebSocket connections from an embedded ThoughtSpot page to the tool's WebSocket endpoint without being blocked by the browser’s Content Security Policy. - -Only hosts explicitly listed with `wss://` are permitted. You can add `wss://` URL in the **Develop** > **Security Settings** page. - -== Passing variables to the hosted script - -To pass variables to the customer's hosted script, Visual Embed SDK provides the `customVariablesForThirdPartyTools` parameter. The `customVariablesForThirdPartyTools` is an object containing the variables that you wish to pass to the customer’s hosted JavaScript. These may include private information such as credentials or keys. The hosted JavaScript will access these variables via the `window.tsEmbed` object. - -Developers can define this parameter in the **init()** function as shown in the following example. Once initialized, the JavaScript will run after the authentication is successfully completed in the ThoughtSpot Embed App. - -[source,JavaScript] ----- -init({ - //... - customVariablesForThirdPartyTools: { cloud: "123Basic" } -}); ----- diff --git a/modules/ROOT/pages/abac_rls-variables.adoc b/modules/ROOT/pages/abac_rls-variables.adoc index 4e13c153a..66bf24e44 100644 --- a/modules/ROOT/pages/abac_rls-variables.adoc +++ b/modules/ROOT/pages/abac_rls-variables.adoc @@ -21,7 +21,7 @@ Formula variables are custom variables defined within ThoughtSpot that enable dy //// In embedded analytics scenarios, where each user may require different data access, administrators can assign security attributes and rules on a per-user basis. For these use cases, administrators can implement a JWT-based ABAC model combined with RLS to enforce data security using dynamic attributes derived from formula variables. -In the ABAC via RLS with variables method, administrators add formula variables to RLS rules and pass their values (`variable_values`) as security attributes and entitlements to the user session through a JWT. All derived objects then inherit the data security rules from the underlying Table and are filtered according to the user’s entitlements provided in the token. +In the ABAC via RLS with variables method, administrators add formula variables to RLS rules and pass their values (`variable_values`) as security attributes and entitlements to the user session through a JWT. All derived objects then inherit the data security rules from the underlying Table and are filtered according to the user's entitlements provided in the token. //// === Implementation steps @@ -93,7 +93,7 @@ RLS rules are defined on Table objects: [NOTE] ==== -Variable values are set through the token request. The RLS rule specifies how the values will be used in the generated RLS WHERE clauses in the SQL. +Variable values are set through the token request. The RLS rule specifies how the values will be used in the generated RLS `WHERE` clauses in the SQL. ==== === RLS rule examples diff --git a/modules/ROOT/pages/ai-integration-options.adoc b/modules/ROOT/pages/ai-integration-options.adoc index ec760fd73..dfa4d3837 100644 --- a/modules/ROOT/pages/ai-integration-options.adoc +++ b/modules/ROOT/pages/ai-integration-options.adoc @@ -21,16 +21,16 @@ The primary ways to integrate ThoughtSpot analytics and AI into your environment All options allow using your existing ThoughtSpot data models, Liveboards, Answers, row-level and column-level security, and governance. The main differences are where the UI or conversation layer exists and who orchestrates the analytics workflow. ==== -=== ThoughtSpot MCP Server +=== ThoughtSpot Spotter MCP Server -ThoughtSpot xref:mcp-integration.adoc[MCP Server] exposes governed analytics as MCP tools and resources to AI agents and clients. The MCP Server can be integrated with your MCP client, agent, LLM, or application UI, allowing your users to explore ThoughtSpot's agentic capabilities within the context of your application. +ThoughtSpot xref:mcp-integration.adoc[Spotter MCP Server] exposes governed analytics as MCP tools and resources to AI agents and clients. Spotter MCP Server can be integrated with your MCP client, agent, LLM, or application UI, allowing your users to explore ThoughtSpot's agentic capabilities within the context of your application. -ThoughtSpot recommends using the MCP Server in these scenarios: +ThoughtSpot recommends using Spotter MCP Server in these scenarios: * When you want to plug ThoughtSpot into AI agents and clients that already support MCP, such as Claude, ChatGPT, Gemini, IDEs, and custom MCP clients. * If you are building your own MCP-based chatbot or application, and want to call ThoughtSpot MCP tools behind a custom web experience. -For more information, see the xref:mcp-integration.adoc[MCP Server] documentation. +For more information, see the xref:mcp-integration.adoc[Spotter MCP Server] documentation. === Embedding Spotter in your app diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 1a1338efd..0c0a75e58 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,18 +8,77 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 1.49.x, June 2026 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Visual overrides for charts and tables +The SDK introduces the `visualOverrides` object in `SearchViewConfig` and +`AppViewConfig`, enabling embed developers to apply chart and table display +customizations to the new answers from an embedded Search data interface at initialization time. + +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. +* `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. +* `columns` property for per-column series color and conditional formatting rules. +* `updateMaskPaths` property for partial updates +* `columns` property for column visibility, text wrapping, conditional formatting, and column summary in tables. + +For more information, see xref:viz-overrides.adoc[Visualization overrides]. + +//|[tag greenBackground]#NEW FEATURE# a| +//[discrete] +//===== New charts library + +//The SDK introduces the `newChartsLibrary` parameter to enable the new Muze charting library in Liveboard and full application embedding. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Liveboard browser cache refresh + +The SDK introduces the following event IDs and action ID to support programmatic and user-triggered browser cache refresh for the Liveboard ChartViz containers. These APIs require `enableLiveboardDataCache` to be enabled in your embed configuration. + +Events:: + +* `EmbedEvent.RefreshLiveboardBrowserCache` + +Emitted when a user clicks the *Refresh* button in the Liveboard header to clear the browser cache. + +* `HostEvent.RefreshLiveboardBrowserCache` + +Allows the host application to programmatically trigger a browser cache refresh for all visualization containers on the embedded Liveboard. + +New action ID:: + +* `Action.RefreshLiveboardBrowserCache` + +Action ID to control the visibility of the *Refresh* button that clears the browser cache and fetches new data for Liveboard ChartViz containers. + +|[tag greenBackground]#NEW FEATURE# a| +[discrete] +===== Spotter file upload +The SDK introduces the following configuration parameters in `SpotterChatViewConfig` to enable and control file uploads in the embedded Spotter chat interface. + +* `spotterFileUploadEnabled` + +When set to `true`, enables the file upload feature in the Spotter chat panel. + +* `spotterFileUploadFileTypes` + +Restricts the file types allowed for upload in the Spotter chat panel. Accepts a `SpotterFileUploadFileTypes` object. +|==== + + == Version 1.48.x, May 2026 [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE# a| [discrete] ===== Liveboard embedding - The SDK includes the following new features and enhancements in Liveboard embedding. Continuous Liveboard layout in PDF downloads [beta betaBackground]^Beta^:: - When set to `true`, the `isContinuousLiveboardPDFEnabled` enables the Liveboard tab to render on a single page that matches the exact UI layout you see in ThoughtSpot. This update addresses the issue where visualizations for PDF downloads were split across multiple A4 pages regardless of how they appear on screen. This feature is in beta and can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true`. New events and action IDs;; @@ -75,7 +134,7 @@ Note the following changes: EmbedEvent:: * `EmbedEvent.Subscribed` + -The SDK introduces the `EmbedEvent.Subscribed` to emit an event when a HostEvent listener is registered. You can use this event to safely dispatch host events during the initial load without race conditions. +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` + @@ -370,7 +429,7 @@ The Visual Embed SDK now supports runtime overrides in Spotter embed. * To apply runtime Parameters, use the `runtimeParameters` object. |[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* + -To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. +To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. The SDK also provides the following action IDs: @@ -668,7 +727,7 @@ Allows adding `name` and `description` text strings. When these parameters are d * `HostEvent.Pin` + Allows adding custom properties for visualization ID, name, and description, Liveboard ID, and Tab ID. When these parameters are defined, the event triggers an action to pin the Answer to the Liveboard specified in the code, without opening the *Pin* modal. -For more information, see xref:embed-events.adoc#hostEventParameterization[Host Events] documentation. +For more information, see xref:events-hostEvents.adoc#hostEventParameterization[Host Events] documentation. |[tag greenBackground]#NEW FEATURE# a| @@ -1261,7 +1320,7 @@ You may also want to update the data classes in your scripts to process the JSON * `HostEvent.SyncToOtherApps` * `HostEvent.SyncToSheets` -For more information, see xref:embed-events.adoc#host-events[Host events]. +For more information, see xref:events-hostEvents.adoc[Host events]. |[tag redBackground]#DEPRECATED# a|The `noRedirect` property in the SDK is deprecated and replaced with the `inPopup` attribute. When set to `true`, the `inPopup` attribute allows the SAML SSO authentication flow in a pop-up window. @@ -1354,7 +1413,7 @@ For more information, see xref:embed-pinboard.adoc#_liveboard_tabs[Customize Liv * SchedulesList * UpdateTML -For more information, see xref:embed-events.adoc#host-events[Events reference]. +For more information, see xref:events-hostEvents.adoc[Events reference]. |==== == Version 1.14.0, August 2022 @@ -1371,14 +1430,13 @@ The earlier versions of the SDK supported only `GET` API requests. For more info [width="100%" cols="1,4"] |==== |[tag greenBackground]#NEW FEATURE#| -This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. + -//For more information, see xref:search-assist-tse.adoc[Enable Search Assist, window=_blank]. +This version of Visual Embed SDK includes the `enableSearchAssist` attribute, using which you can turn on the Search Assist feature on an embedded instance. |[tag greenBackground]#NEW FEATURE#| The new version of SDK introduces the `AuthType.SAML` enum for SAML-based SSO authentication. Note that `AuthType.SAML` replaces the `AuthType.SSO` enum, which is deprecated in the v1.13.0 version of the SDK. + For more information, see xref:embed-authentication.adoc#saml-sso-embed[Authentication]. |[tag redBackground]#DEPRECATED#| The `AuthType.SSO` enum is deprecated in v1.13.0. ThoughtSpot recommends using `AuthType.SAML` for the SAML SSO authentication method. + This change does not impact your current embed implementation with `AuthType.SSO`. |[tag greenBackground]#NEW FEATURE#| The SDK includes the `getExportRequestForCurrentPinboard` event, which is triggered when a user tries to export a Liveboard in its current state. + -For more information, see xref:embed-events.adoc#host-events[Events reference]. +For more information, see xref:events-hostEvents.adoc[Events reference]. |==== == Version 1.12.0, June 2022 @@ -1388,7 +1446,7 @@ For more information, see xref:embed-events.adoc#host-events[Events reference]. |[tag greenBackground]#NEW FEATURE#| This version of Visual Embed SDK introduces the `navigate` host event, which is triggered when a user navigates to an application page without a page reload. -For more information, see xref:embed-events.adoc[Events reference]. +For more information, see xref:events-hostEvents.adoc[Events reference]. |[tag greenBackground]#NEW FEATURE# | The new `getThoughtSpotPostUrlParams` method fetches ThoughtSpot URL query parameters prefixed with `ts-`. |==== @@ -1469,7 +1527,7 @@ Bug fix and improvements to the `logout` method. [width="100%" cols="1,4"] |==== -|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:embed-events.adoc#embed-events[Events reference]. +|[tag greenBackground]#NEW FEATURE# a| The `AddRemoveColumns` event is now available in the SDK. For more information, see xref:event-embedEvents.adoc[Events reference]. |==== == Version 1.9.8, April 2022 @@ -1526,7 +1584,7 @@ For more information, see xref:embed-pinboard.adoc[Embed a Liveboard]. * `LiveboardRendered` (EmbedEvent) -For more information, see xref:embed-events.adoc#embed-events[Events reference]. +For more information, see xref:event-embedEvents.adoc[Events reference]. |==== == Version 1.9.0, March 2022 @@ -1541,7 +1599,7 @@ For more information, see xref:embed-events.adoc#embed-events[Events reference]. For more information, see xref:embed-actions.adoc#standard-actions[Show or hide UI actions]. -|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:embed-events.adoc#host-events[Events reference]. +|[tag greenBackground]#NEW FEATURE# a| The SDK now supports the `UpdateRuntimeFilters` host event. For more information, see xref:events-hostEvents.adoc[Events reference]. |==== == Version 1.8.x, February 2022 @@ -1569,7 +1627,7 @@ The SDK includes the following new event: * `RouteChange` -For more information, see xref:embed-events.adoc#embed-events[Events reference]. +For more information, see xref:event-embedEvents.adoc[Events reference]. |==== @@ -1594,7 +1652,7 @@ The SDK supports the following new events: * `DialogOpen` * `DialogClose` -For more information, see xref:embed-events.adoc#embed-events[Events reference]. +For more information, see xref:event-embedEvents.adoc[Events reference]. |==== == Version 1.5.0, October 2021 @@ -1620,7 +1678,7 @@ The SDK EmbedEvent library includes the following new events: * `Drilldown` * `SetVisibleVizs` -For more information, see xref:embed-events.adoc#embed-events[Events reference]. +For more information, see xref:event-embedEvents.adoc[Events reference]. |==== diff --git a/modules/ROOT/pages/api-intercept.adoc b/modules/ROOT/pages/api-intercept.adoc index 85153b063..7ec334347 100644 --- a/modules/ROOT/pages/api-intercept.adoc +++ b/modules/ROOT/pages/api-intercept.adoc @@ -78,7 +78,7 @@ embed.on(EmbedEvent.OnBeforeGetVizDataIntercept, == Intercept specific requests or all API calls -The API intercept feature lets you intercept API calls made by the embedded application, modify or block requests, and provide custom responses before they are sent to the backend. +The API intercept feature lets you intercept API calls made by the embedded application, modify or block requests, and provide custom responses before they are sent to the backend. To intercept API requests from specific URLs, specify one of the following values in the `interceptUrls` array: diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 4d0b69cf0..eb70d5729 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -87,13 +87,105 @@ Once the security rules are set, they are fixed for at least that user's session ||| |=== +[#_enable_trusted] +=== Configure trusted authentication +To generate an access token, trusted authentication must be enabled on your ThoughtSpot instance. +You can enable trusted authentication through the ThoughtSpot UI or the REST API v2. + +*Through the ThoughtSpot UI* + +The administrator must enable xref:trusted-auth-secret-key.adoc[Trusted authentication] on the +*Develop* > *Customizations* > *Security settings* page. + +*Through the REST API v2* + +Before enabling trusted authentication through the REST API v2, check your existing +authentication configuration. +To retrieve the current authentication configuration at the +cluster or Org level, send a request to the `POST /api/rest/2.0/auth/search` endpoint. + +==== Request parameters +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`auth_type` +|__String__. Type of authentication mechanism to configure. Currently, supports `TRUSTED_AUTH` only. + +|`scope` +__Optional__ +|__String__. Select `CLUSTER` to retrieve only cluster-level settings, or `ORG` to retrieve only Org-level settings. If no selection is made, both cluster and Org-level settings are retrieved based on user permissions. +|===== + +==== API request + +.cURL +[source, cURL] +---- +curl -X POST \ +--url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/search' \ +-H 'Accept: application/json' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer {AUTH_TOKEN}' + { + "auth_type": "TRUSTED_AUTH" + }' +---- + + +If trusted authentication is not enabled, you can enable or disable it at the cluster or Org level by sending a request to the `POST /api/rest/2.0/auth/configure` endpoint. + + +=== Request parameters +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description +|`auth_type` +|__String__. Type of authentication mechanism to configure. Currently, supports `TRUSTED_AUTH` only. + +|`cluster_preferences` +__Optional__ +|__Nullable__. `ENABLE` or `DISABLE` authentication for the cluster. When enabled, a new token is generated if one does not exist. When disabled, the existing cluster-level access token is revoked. + +|`org_preferences` +__Optional__ +|__Nullable__. `ENABLE` or `DISABLE` authentication for a particular Org. When enabled, a new org-level access token is generated if one does not exist. When disabled, the existing org-level access token is revoked. + +|`org_identifier` + +|===== + +==== API request + +.cURL +[source, cURL] +---- +curl -X POST \ +--url 'https://{ThoughtSpot-host}/api/rest/2.0/auth/configure' \ +-H 'Content-Type: application/json' \ +-H 'Authorization: Bearer {AUTH_TOKEN} + '{ + "auth_type": "TRUSTED_AUTH", + "org_preferences": [ + { + "org_identifier": "Test", + "auth_status": "ENABLED" + } + ] + }' +---- + +If the API request is successful, ThoughtSpot returns a 204 status code. + + [#_generate_a_full_access_token] === Generating a full access token To generate a full access token, send a `POST` request to the `/api/rest/2.0/auth/token/full` API endpoint with the required attributes. You can generate a token by providing a `username` and `password`, or by using a `secret_key`. -To generate a `secret_key`, the administrator must enable xref:trusted-auth-secret-key.adoc[trusted authentication] on the **Develop** > **Customizations** > **Security Settings** page. +To generate a `secret_key`, the administrator must enable xref:trusted-auth-secret-key.adoc[trusted authentication] on the **Develop** > **Customizations** > **Security Settings** page or through the APIs. After ThoughtSpot issues an authentication token, the user must include the token in the `Authorization` header of their subsequent API requests. @@ -117,7 +209,7 @@ To get an access token that grants full access to ThoughtSpot, send a `POST` req |`org_id` + __Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0). |`validity_time_in_sec` + -__Optional__|__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. You can set the token expiry duration to a higher value. API requests with an expired or invalid token result in an error. In such cases, REST clients must obtain a new token from ThoughtSpot and use it in their subsequent API calls. +__Optional__ |__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. You can set the token expiry duration to a higher value. API requests with an expired or invalid token result in an error. In such cases, REST clients must obtain a new token from ThoughtSpot and use it in their subsequent API calls. || |===== @@ -161,7 +253,7 @@ If the API request is successful, ThoughtSpot returns the authentication token t ==== API request with username and secret key To obtain an authentication token for a user, include `username` and `secret_key` in the API request. In a trusted authentication implementation, you can request tokens on behalf of users who require access to the ThoughtSpot content embedded in a third-party application. -To request a token on behalf of another user, you need administrator privileges and a `secret key` that allows you to securely pass the authentication details of an embedded application user. The `secret key` is generated xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled on a ThoughtSpot instance]. +To request a token on behalf of another user, you need administrator privileges and a `secret_key` that allows you to securely pass the authentication details of an embedded application user. The `secret_key` is generated xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled on a ThoughtSpot instance]. To get a trusted authentication token that grants full access to ThoughtSpot, send a `POST` request with `username`, `secret_key`, and other attributes to the `/api/rest/2.0/auth/token/full` endpoint: @@ -172,7 +264,7 @@ To get a trusted authentication token that grants full access to ThoughtSpot, se |`username` |__String__. Username of the ThoughtSpot user. If the user is not available in ThoughtSpot, you can set the `auto_create` parameter to `true` to create a user just-in-time (JIT). |`secret_key` -|__String__. The secret key string generated for your ThoughtSpot instance. The secret key is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance. +|__String__. The `secret_key` string generated for your ThoughtSpot instance. The `secret_key` is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance. |`validity_time_in_sec` + __Optional__|__Integer__. Token expiry duration in seconds. The default duration is 300 seconds. You can set the token expiry duration to a higher value. API requests with an expired or invalid token result in an error. In such cases, REST clients must obtain a new token from ThoughtSpot and use it in their subsequent API calls. |`org_id` + @@ -187,7 +279,7 @@ The following example shows the request body with `username` and `secret_key`: [source,cURL] ---- curl -X POST \ - --url 'https://stage-grapes-champagne.thoughtspotstaging.cloud/api/rest/2.0/auth/token/full' \ + --url 'https://{ThoughtSpot-Host}api/rest/2.0/auth/token/full' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ --data-raw '{ @@ -245,9 +337,9 @@ To get a token that grants read-only access to a ThoughtSpot metadata object, se |__String__. GUID of the ThoughtSpot object. The token obtained from this API request grants `read-only` access to the specified object. |`org_id` + -__Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0). +__Optional__ |__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0). |`validity_time_in_sec` + -__Optional__|__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. +__Optional__ |__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. |===== ===== Example request @@ -298,7 +390,7 @@ To get a token that grants `read-only` access to a specific metadata object, sen |__String__. Username of the ThoughtSpot user. If the user is not available in ThoughtSpot, you can set the `auto_create` parameter to `true` to create a user just-in-time (JIT). |`secret_key` -|__String__. The secret key string generated for your ThoughtSpot instance. The secret key is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance. +|__String__. The `secret_key` string generated for your ThoughtSpot instance. The `secret_key` is created xref:trusted-auth-secret-key.adoc#trusted-auth-enable[when trusted authentication is enabled] on your instance. |`object_id` |__String__. GUID of the ThoughtSpot object. @@ -542,7 +634,7 @@ For cookie-based authentication, make an API call to the `/api/rest/2.0/auth/ses |__String__. The password of the user account. |`org_identifier` -|__String__. Name or ID of the Org. If no Org ID is specified, the user will be logged into the Org context of their previous session. +|__String__. Name or ID of the Org. If no Org ID is specified, the user is logged into the Org context of their previous session. |`remember_me` __Optional__ @@ -772,13 +864,5 @@ curl -X POST \ If the API request is successful, ThoughtSpot returns a 204 status code and ends the user session. -//// -==== Response codes -[options="header", cols="2,4"] -|=== -|HTTP status code|Description -|**204**|The user is logged out of ThoughtSpot -|**500**|Failed operation -|=== -//// + diff --git a/modules/ROOT/pages/code-samples.adoc b/modules/ROOT/pages/code-samples.adoc index 620d3a4c0..1d8b810d8 100644 --- a/modules/ROOT/pages/code-samples.adoc +++ b/modules/ROOT/pages/code-samples.adoc @@ -254,7 +254,7 @@ const MyComponent = () => { == Trusted authentication -* See xref:trusted-auth-sdk#_code_examples[Trusted authentication] +* See xref:trusted-auth-sdk.adoc#_code_examples[Trusted authentication] * Check link:https://github.com/thoughtspot/ts_everywhere_resources/tree/master/examples/token_auth[the ts_everywhere_resources GitHub repository, window=_blank] * Check link:https://codesandbox.io/s/big-tse-react-demo-i4g9xi[the React components code sandbox, window=_blank] diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index d1638447d..a028490b6 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -235,6 +235,146 @@ curl -X POST \ If the API request is successful, the objects in the Collection are replaced with the objects in this API request. +== Share a Collection +[NOTE] +==== +Collections sharing via the security API is available from ThoughtSpot Cloud 26.6.0.cl. +==== + +To share a Collection with a user or group, send a `POST` request to the `POST /api/rest/2.0/security/metadata/share` endpoint with `metadata_type` set to `COLLECTION`. + +Collections support dual permissions that let you set independent access levels for the Collection and the objects within it. + +=== Permission fields + +[width="100%", cols="1,1,3"] +[options='header'] +|===== +|Field|Applies to|Description + +|`share_mode`|Collection |Controls access to the Collection itself — view, edit, or delete the Collection. +Accepted values: `READ_ONLY`, `MODIFY`, `NO_ACCESS`. + +|`content_share_mode`|Collection content|Controls access to the objects within the Collection — Liveboards, Answers, Models, and nested Collections. +Accepted values: `READ_ONLY`, `MODIFY`, `NO_ACCESS`. + +Only applicable when `metadata_type` is `COLLECTION`. If omitted, defaults to `READ_ONLY` (or `NO_ACCESS` when `share_mode` is `NO_ACCESS`). +|===== + +=== Permission scenarios + +[width="100%", cols="1,1,1,2"] +[options='header'] +|===== +|Role|`share_mode`|`content_share_mode`|What the principal can do + +|`MODIFY`|`MODIFY`|Full control — manage the Collection and edit its contents +|`MODIFY`|`READ_ONLY`|Manage the Collection structure but cannot edit objects within it +|`READ_ONLY`|`MODIFY`|Edit objects within the Collection but cannot change the Collection itself +|`READ_ONLY`|`READ_ONLY`|View the Collection and its contents only +|===== + +=== Share a Collection (read-only) + +To share a Collection with a user in read-only mode, send the following request: + +[source,CURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_type": "COLLECTION", + "metadata_identifiers": ["Sales reports"], + "permissions": [ + { + "principal": { + "type": "USER", + "identifier": "name@example.com" + }, + "share_mode": "READ_ONLY" + } + ], + "notification": { + "message": "I have shared the Sales reports collection with you.", + "notify_on_share": true + } +}' +---- + +If the request is successful, the API returns the HTTP `204 No Content` status code. + +=== Share a Collection with dual permissions + +To give a user different levels of access to the Collection and its contents, set both `share_mode` and `content_share_mode`. + +[source,CURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_type": "COLLECTION", + "metadata_identifiers": ["Marketing Analytics"], + "permissions": [ + { + "principal": { + "type": "USER", + "identifier": "name@example.com" + }, + "share_mode": "MODIFY", + "content_share_mode": "READ_ONLY" + }, + { + "principal": { + "type": "USER_GROUP", + "identifier": "Marketing Team" + }, + "share_mode": "READ_ONLY", + "content_share_mode": "READ_ONLY" + } + ], + "notification": { + "message": "Sharing the Marketing Analytics collection with your team.", + "notify_on_share": true + } +}' +---- + +If the request is successful, the API returns the HTTP `204 No Content` status code. + +=== Remove Collection access + +To remove a user's access to a Collection, set `share_mode` to `NO_ACCESS`: + +[source,CURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/security/metadata/share' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_type": "COLLECTION", + "metadata_identifiers": ["Confidential Reports"], + "permissions": [ + { + "principal": { + "type": "USER", + "identifier": "former-member@example.com" + }, + "share_mode": "NO_ACCESS" + } + ] +}' +---- + +If the request is successful, the API returns the HTTP `204 No Content` status code. + == Delete a Collection To remove an existing Collection, send a `POST` request to the `POST /api/rest/2.0/collections/delete` API endpoint. diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index 5632e6cbd..c5a64bbb4 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -23,6 +23,7 @@ Embed ThoughtSpot in a web app * Embed token-based Search ** link:{{navprefix}}/search-embed[Embed Search] ** link:{{navprefix}}/embed-searchbar[Embed search bar] +** link:{{navprefix}}/visualization-overrides[Visualization overrides] * link:{{navprefix}}/react-app-embed[Embed with React components] [.sidebar-title] diff --git a/modules/ROOT/pages/common/nav-mcp-server.adoc b/modules/ROOT/pages/common/nav-mcp-server.adoc index d40f131d7..f1e6d4822 100644 --- a/modules/ROOT/pages/common/nav-mcp-server.adoc +++ b/modules/ROOT/pages/common/nav-mcp-server.adoc @@ -1,16 +1,16 @@ :page-pageid: nav-mcp-server -:page-description: MCP Server navigation +:page-description: Spotter MCP Server navigation [navSection] [.sidebar-title] -ThoughtSpot MCP server +ThoughtSpot Spotter MCP Server * link:{{navprefix}}/mcp-integration[Overview] ** link:{{navprefix}}/mcp-server-spotter3[MCP Server with Spotter 3] ** link:{{navprefix}}/mcp-server-legacy[Legacy MCP Server architecture and tools] -* link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to MCP clients] +* link:{{navprefix}}/connect-mcp-server-to-clients[Connecting MCP Server to clients] * link:{{navprefix}}/custom-chatbot-integration-mcp[Integrating MCP Server in a custom app] [.sidebar-title] @@ -18,7 +18,7 @@ MCP tools reference * link:{{navprefix}}/mcp-tool-reference[Overview] * link:{{navprefix}}/mcp-tool-reference-spotter3[MCP tool reference (Spotter 3)] -* link:{{navprefix}}/mcp-tool-reference-spotter3[MCP tool reference (legacy version)] +* link:{{navprefix}}/mcp-tool-reference-legacy[MCP tool reference (legacy version)] [.sidebar-title] Related SDK components @@ -27,6 +27,6 @@ Related SDK components * [.typedoc-Interface]#link:{{navprefix}}/Interface_AutoMCPFrameRendererViewConfig[AutoMCPFrameRendererViewConfig]# [.sidebar-title] -MCP Server release notes +Spotter MCP Server release notes -* link:{{navprefix}}/mcp-server-changelog[MCP Server changelog] +* link:{{navprefix}}/mcp-server-changelog[Spotter MCP Server changelog] diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 49e2944d8..f37a0a86e 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -12,7 +12,7 @@ Release notes and changelogs ** link:{{navprefix}}/embed-sdk-changelog[Visual Embed SDK changelog] ** link:{{navprefix}}/mobile-sdk-changelog[Mobile Embed SDK changelog] ** link:{{navprefix}}/rest-v2-changelog[REST API v2 changelog] -** link:{{navprefix}}/mcp-server-changelog[MCP Server changelog] +** link:{{navprefix}}/mcp-server-changelog[Spotter MCP Server changelog] * link:{{navprefix}}/deprecated-features[Deprecation announcements] [.sidebar-title] @@ -25,7 +25,7 @@ Live Playgrounds ** link:{{navprefix}}/rest-playground[How to use] //** link:{{navprefix}}/graphql-play-ground[GraphQL Playground] //** +++REST API v1 Playground+++ -* link:{{navprefix}}/theme-builder[Theme Builder] +* +++Theme Builder+++ ** link:{{navprefix}}/theme-builder-doc[How to use] diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index e7012e98b..29b2e42cd 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -4,7 +4,7 @@ :page-title: Customize navigation panels :page-pageid: customize-nav-controls -:page-description: Customize the the navigation panel and menu items in full application embedding using the settings in the Visual Embed SDK +:page-description: Customize the navigation panel and menu items in full application embedding using the settings in the Visual Embed SDK You can customize the navigation experience and the visibility of navigation menu elements using the Visual Embed SDK. @@ -125,6 +125,9 @@ const embed = new AppEmbed("#embed", { }); ---- +== Command palette availability in embed +In ThoughtSpot application, users can open the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage#command-palette[command palette] by pressing kbd:[Cmd+K] on macOS or kbd:[Ctrl+K] on Windows to quickly navigate to objects and perform actions. However, when you embed ThoughtSpot, this feature is disabled and embedded pages include only the standard object search experience. + == Customize the left navigation panel on the home page In the V2 and V3 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides the left navigation only on the home page. diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 17daad593..196c8361d 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -459,7 +459,7 @@ To download Answer data via `/api/rest/2.0/report/answer` API, you need at least In the request body, specify the GUID or name of the Answer object as `metadata_identifier`. -You can download the Answer data in the `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. +The API supports exporting saved Answers, pinned Answers from a Liveboard, and Spotter-generated Answers. You can download Answer data in `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. ==== Example @@ -477,10 +477,46 @@ curl -X POST \ [NOTE] ==== -* The downloadable file returned in API response file is extensionless. You need to rename the downloaded file by typing in the relevant extension. +* Exported files are automatically named after the Answer title, with the file extension appended based on the selected format. * HTML rendering is not supported for PDF exports of Answers with tables. ==== + +Contact ThoughtSpot support to enable these enhanced settings for this API endpoint on your ThoughtSpot instance: + +* `personalised_view_identifier` [earlyAccess eaBackground]#Early Access# + +Optional parameter to specify the GUID of the personalised view of the `PINNED` Answer object that you want to download. +* `type` [earlyAccess eaBackground]#Early Access# + +Used to distinguish between a saved answer and a pinned answer on a Liveboard. Setting this parameter to `PINNED` allows the API to +accept the guid of a pinned Answer directly as the `metadata_identifier`. When +exporting an Answer, all Liveboard-level filters, Runtime Filters, and Column +Security Rules (CSR) are automatically applied to the export output. + +The `png_options` [earlyAccess eaBackground]#Early Access# support the following properties: + +[cols="1,1,3"] +|=== +|Property |Type |Description + +|`x_resolution` +|Number +|Width of the exported PNG in pixels. + +Valid range: `600px` to `3840px`. + +|`y_resolution` +|Number +|Height of the exported PNG in pixels. + +Valid range: `600px` to `3840px`. + +|`scaling` +|Integer +|Display scale percentage for objects rendered in the image. Adjusts the relative +size of visual elements without cropping the image. + +Valid range: `80%` to `500%`. +|=== + +You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. + [#exportSpotterData] ==== Export data generated from Spotter APIs To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. @@ -504,7 +540,7 @@ curl -X POST \ * `session_identifier` refers to session ID returned in the Spotter API response. * `generation_number` indicates the Answer generation number. -* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG or CSV file. By default, the API exports this data in PNG file format. +* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. ===== API Response diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index 06089a22d..480e99dc8 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -14,6 +14,8 @@ As ThoughtSpot applications evolve, some existing features will be deprecated an [options='header'] |===== |Feature|Impacted interface and release versions|Deprecation date |End of Support / removal from the product +a|xref:deprecated-features.adoc#everynmins[Minute-level schedule frequency] +|ThoughtSpot Cloud 26.8.0.cl and later | August 2026 | - a|xref:deprecated-features.adoc#hostEventv1[HostEvent v1 framework] |ThoughtSpot Cloud 26.10.0.cl and later | October 2026 | March 2027 a|xref:deprecated-features.adoc#v1-v2-exp-fullApp-embed[V1 and V2 UI experience in full application embedding]|ThoughtSpot Cloud 26.8.0.cl and later | February 2026 | August 2026 @@ -87,6 +89,17 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic |||| |===== +[#everynmins] +== Minute-level schedule frequency +The `POST /api/rest/2.0/schedules/create` and `POST /api/rest/2.0/schedules/{schedule_identifier}/update` API endpoint no longer accept `minute` as a valid `frequency` value for schedule intervals. + +Impact on your instance:: +Starting ThoughtSpot 26.8.0.cl, all existing Liveboard schedules set to `minute` as the frequency will be automatically changed to an hourly frequency. + +Recommended action:: +Before upgrading, review your existing Liveboard schedules. +If your workflows require sub-hourly frequencies after this change takes effect, contact ThoughtSpot Support. Beyond reinstating the `minute` frequency, ThoughtSpot will not provide ongoing maintenance for that frequency. + [#hostEventv1] == HostEvent v1 framework in Visual Embed SDK The HostEvent v1 framework will be deprecated in the ThoughtSpot Cloud 26.10.0.cl release version. The default behavior of host events and application workflows with the HostEvent v1 framework will be replaced with the HostEvent v2 framework. diff --git a/modules/ROOT/pages/development-and-deployment.adoc b/modules/ROOT/pages/development-and-deployment.adoc index 396ed312f..3f02b9674 100644 --- a/modules/ROOT/pages/development-and-deployment.adoc +++ b/modules/ROOT/pages/development-and-deployment.adoc @@ -85,7 +85,7 @@ Each Org in ThoughtSpot can be xref:version_control.adoc[paired] to a link:https //// //// -Once your environments are configured, you can xref:version_control.adoc#moving-tml-changes-between-environments[move data models and content] from the initial "dev environment" to any other environment using the xref:git-rest-api-guide.adoc[Git integration REST APIs]. +Once your environments are configured, you can xref:version_control.adoc#_moving_tml_changes_between_environments[move data models and content] from the initial "dev environment" to any other environment using the xref:git-rest-api-guide.adoc[Git integration REST APIs]. //// diff --git a/modules/ROOT/pages/embed-action-ref.adoc b/modules/ROOT/pages/embed-action-ref.adoc index 43d3e94ed..64335416c 100644 --- a/modules/ROOT/pages/embed-action-ref.adoc +++ b/modules/ROOT/pages/embed-action-ref.adoc @@ -352,7 +352,7 @@ The *Add to Coaching* feature allows adding reference questions and business ter `AppEmbed` | Controls visibility and disable state of the mode switcher in the Spotter chat interface. |===== -For information about the action IDs available for Answers generated from Spotter (`SpotterEmbed`), see xref:embed-action-ref#answer-actions[Answers]. +For information about the action IDs available for Answers generated from Spotter (`SpotterEmbed`), see xref:embed-action-ref.adoc#answer-actions[Answers]. [#answer-actions] == Answers diff --git a/modules/ROOT/pages/embed-ai-analytics.adoc b/modules/ROOT/pages/embed-ai-analytics.adoc index b247ed0df..6d52bf60b 100644 --- a/modules/ROOT/pages/embed-ai-analytics.adoc +++ b/modules/ROOT/pages/embed-ai-analytics.adoc @@ -14,7 +14,7 @@ ThoughtSpot supports three experience modes: Spotter Classic, Spotter Agent (Spo [options="header"] |==== |Version| Supported features -|Spotter 3 [tag purpleBackground]#Early Access# +|Spotter 3 a| Spotter 3 is the latest and most advanced version of Spotter. **Key features and user experience**: + @@ -123,7 +123,7 @@ The updated chat interface that provides a more intuitive and interactive analyt [tag redBackground tick]#x# Spotter 2 + [tag redBackground tick]#x# Spotter Classic -**Feature status**: Early Access. Available by default on instances that have Spotter 3 enabled. + +**Feature status**: Available by default on instances that have Spotter 3 enabled. + **Required settings**: Spotter 3 must be enabled at the instance level. + @@ -140,7 +140,7 @@ The thinking and reasoning UX in Spotter conversations shows step-by-step reason [tag greenBackground tick]#✓# Spotter 2 + [tag redBackground tick]#x# Spotter Classic + -**Feature status**: Early Access. Enabled by default on instances with Spotter 2 or Spotter 3 enabled. +**Feature status**: Enabled by default on instances with Spotter 2 or Spotter 3 enabled. **Required settings**: Spotter 2 or Spotter 3 experience must be enabled at the instance level. + **Embed SDK component**: Use `SpotterEmbed`. + @@ -204,7 +204,7 @@ Ability to function as a data-aware analyst, derive context data model, and perf [tag redBackground tick]#x# Spotter 2 + [tag redBackground tick]#x# Spotter Classic -**Feature status**: Early Access. Enabled by default if Spotter 3 is enabled on the instance. +**Feature status**: Enabled by default if Spotter 3 is enabled on the instance. **Required settings**: Spotter 3 experience must be enabled on the instance. @@ -221,7 +221,7 @@ Ability to ask questions to automatically generate explanations and identify key [tag greenBackground tick]#✓# Spotter 2 + [tag redBackground tick]#x# Spotter Classic -**Feature status**: Early Access. Disabled by default. +**Feature status**: Disabled by default. **Required settings**: Spotter 2 or Spotter 3 experience must be enabled on the instance. @@ -239,7 +239,7 @@ Automatic data source discovery and model selection by Spotter. [tag redBackground tick]#x# Spotter 2 + [tag redBackground tick]#x# Spotter Classic -**Feature status**: Early Access. Disabled by default. +**Feature status**: Disabled by default. **Required settings**: Spotter 3 experience and the *Auto-mode* feature must be enabled at the instance level. + @@ -247,6 +247,7 @@ Automatic data source discovery and model selection by Spotter. **Default state in embed**: Disabled by default. To enable this feature, set the `worksheetId` attribute to `auto_mode` in the SDK. When the Auto mode is enabled, the *Preview data* option in the conversation panel is hidden. + |link:https://docs.thoughtspot.com/cloud/latest/spotter-conversation-history[Chat history, window=_blank] + Saves Spotter conversations and allows reloading chat history with past conversations. @@ -256,30 +257,42 @@ Saves Spotter conversations and allows reloading chat history with past conversa [tag redBackground tick]#x# Spotter 2 + [tag redBackground tick]#x# Spotter Classic -**Feature status**: Early Access. Enabled by default if Spotter 3 is enabled on the instance. +**Feature status**: Enabled by default if Spotter 3 is enabled on the instance. **Required settings**: Spotter 3 experience and the *Chat history* feature must be enabled at the instance level. + **Embed SDK component**: Use `SpotterEmbed`. + -**Default state in embed**: Disabled by default. To enable this feature in the embed mode, set `enablePastConversationsSidebar` to `true` in the SDK. +**Default state in embed**: Disabled by default. To enable chat history, use `enablePastConversationsSidebar` within the `spotterSidebarConfig` object. + + +[NOTE] +==== +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use `enablePastConversationsSidebar` within the `spotterSidebarConfig` object instead. When both are defined, the `spotterSidebarConfig` value takes precedence. +==== |link:https://docs.thoughtspot.com/cloud/latest/spotter-connectors-use[Third-party connectors and MCP tools, window=_blank] + Third-party tools and services that Spotter can connect to and interact with via Model Context Protocol (MCP). +|MCP connector controls in Spotter chat interface + -|**Supported Spotter version**: + +Action IDs to show or hide the MCP connector panel, connector resources section, and chat mode switcher in the embedded Spotter 3 interface. +|**Supported Spotter version**: + [tag greenBackground tick]#✓# Spotter 3 + [tag redBackground tick]#x# Spotter 2 + [tag redBackground tick]#x# Spotter Classic -**Feature status**: Early Access. Enabled by default if Spotter 3 is enabled on the instance. +**Feature status**: Available from SDK v1.48.0 and ThoughtSpot Cloud 26.5.0.cl. + -**Required settings**: Spotter 3 experience and Spotter connectors feature must be enabled on the instance. For connectors to be available in the embed mode, ThoughtSpot administrators must configure Spotter connectors. +**Required settings**: Spotter 3 must be enabled at the instance level. + -**Embed SDK component**: Use `SpotterEmbed`. + +**Embed SDK component**: Use `SpotterEmbed` + + +**Default state in embed**: Visible by default. Use the following action IDs to control visibility: + +* `Action.SpotterChatConnectorResources` +* `Action.SpotterChatConnectors` +* `Action.SpotterChatModeSwitcher` -**Default state in embed**: Visible by default if the `updatedSpotterChatPrompt` attribute is set to `true`. We do not recommend using this feature in your production environment. You can hide this option using the CSS selectors. For more information, see xref:embed-spotter.adoc#_mcp_connectors_and_resource_selection_icon[MCP connectors in Spotter embedding]. || |==== diff --git a/modules/ROOT/pages/embed-authentication.adoc b/modules/ROOT/pages/embed-authentication.adoc index 990b76ab3..e4b05cc3c 100644 --- a/modules/ROOT/pages/embed-authentication.adoc +++ b/modules/ROOT/pages/embed-authentication.adoc @@ -15,7 +15,7 @@ This section describes the authentication methods supported in the SDK and when The following figure shows the authentication methods best suited for production use cases: [.widthAuto] -image:./images/auth-type-embed.png[Embed authentication types] +image::./images/auth-type-embed.png[Embed authentication types] The following table lists the general recommendations for choosing an authentication method to authenticate embedded application users. @@ -73,7 +73,7 @@ a| Do not use this method if you don’t want the SDK to redirect your entire ap [NOTE] ==== -xref:orgs.adoc#per-org-subdomain[Per Org Subdomain] can be enabled to allow Orgs with different IdPs to be identified properly within the authentication flows triggered by the Visual Embed SDK. +xref:orgs.adoc#_per_org_subdomain[Per Org Subdomain] can be enabled to allow Orgs with different IdPs to be identified properly within the authentication flows triggered by the Visual Embed SDK. ==== == User accounts @@ -107,7 +107,7 @@ init({ == SAMLRedirect authentication If your IdP supports SAML SSO to authenticate and does not support iFrame redirects, you can configure the `SAMLRedirect` auth type to authenticate your embedded application users. If this authentication method is enabled, the SDK redirects your app to the IdP login page for user authentication when the embedded content loads. -To use SAML SSO authentication, the administrator must enable SAML authentication on ThoughtSpot and xref:configure-saml.adoc#saml-redirect[add the SAML redirect domains to the allowed list] on the *Security Settings* page in the *Develop* tab. For more information, see xref:configure-saml.adoc#_saml_authentication_workflow_for_a_thoughtspot_embedded_instance[SAML authentication workflow for a ThoughtSpot embedded instance]. +To use SAML SSO authentication, the administrator must enable SAML authentication on ThoughtSpot and xref:configure-saml.adoc#saml-redirect[add the SAML redirect domains to the allowed list] on the *Security Settings* page in the *Develop* tab. For more information, see xref:configure-saml.adoc#_saml_authentication_workflow_on_an_embedded_instance[SAML authentication workflow for a ThoughtSpot embedded instance]. === Enable SAMLRedirect authentication in Visual Embed SDK diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 4d3096580..79715ec88 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -259,11 +259,23 @@ For more information and examples, see xref:filters_overview.adoc[Filter types a Embedding application users can download Liveboards in the PDF, XLSX, and CSV formats. If the `isContinuousLiveboardPDFEnabled` is set to `true`, users can download the PDF with a continuous layout as seen in the UI, with each tab on a single page. When this parameter is set to `false`, users can download the Liveboard PDF in the A4 format with a paginated view. + [NOTE] ==== -Starting with the 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. +Starting with the 26.5.0.cl and Visual Embed SDK version 1.48.x, the new multi-format download experience is available on embedded Liveboards and can be enabled using the `isContinuousLiveboardPDFEnabled` and `isLiveboardXLSXCSVDownloadEnabled` parameters. The `Download` action in the Liveboard's more options menu is controlled by `Action.DownloadLiveboard` instead of `Action.Download` and `Action.DownloadAsPdf`. `Action.DownloadAsPdf` remains valid for controlling PDF download on individual visualizations (chart and table tiles) within a Liveboard. ==== +=== XLSX and CSV in Liveboard scheduled exports +To enable Liveboard scheduled exports in XLSX and CSV format from the embed view, ensure that `isGranularXLSXCSVSchedulesEnabled` to `true`. + +[source,javascript] +---- +const embed = new LiveboardEmbed('#tsEmbed', { + //... + isGranularXLSXCSVSchedulesEnabled: true, // enable scope selection for XLSX and CSV Liveboard scheduled jobs. +}); +---- + === Download actions and behavior [width=100%, cols="2,2,4"] @@ -289,6 +301,10 @@ a|`Action.DownloadLiveboardAsXlsx` - action ID to show or hide the XLSX option i a| `isLiveboardXLSXCSVDownloadEnabled` + Enables the XLSX and CSV download options in the Download modal. a|`Action.DownloadLiveboardAsCsv` - action ID to show, hide, or disable the CSV option in the **Download** modal. + +| PDF cover and filter pages +| None. UI options in PDF modal only. +a| Use `Action.CoverAndFilterOptionInPDF` to hide the checkboxes for including or excluding cover and filter pages in the Liveboard PDF download dialog. |===== === Example @@ -344,7 +360,7 @@ Use the HostEvent IDs to trigger download actions on an embedded Liveboard. * `HostEvent.DownloadLiveboardAsContinuousPDF` + To open the **Download** modal with the continuous PDF download option selected. * `HostEvent.DownloadAsPdf` + -To trigger the standard PDF (A4) download action. +To trigger the standard PDF (A4) download action. To download a specific Liveboard visualization, specify the GUID of visualization in the `vizId` key. * `HostEvent.DownloadAsXlsx` + To open the **Download** modal with the XLSX option selected when the `isLiveboardXLSXCSVDownloadEnabled` is enabled in the embed view. * `HostEvent.DownloadAsCsv` + diff --git a/modules/ROOT/pages/embed-search.adoc b/modules/ROOT/pages/embed-search.adoc index ffa6e9468..54b163875 100644 --- a/modules/ROOT/pages/embed-search.adoc +++ b/modules/ROOT/pages/embed-search.adoc @@ -204,7 +204,7 @@ enableSearchAssist _optional_:: _Boolean_. When set to true, it enables Search Assist. Search Assist allows you to create a custom onboarding experience for your users by demonstrating how to search data from the example queries created on your Worksheet. + -Search Assist uses the predefined queries and answers from the Worksheet. Users with edit permissions to a Worksheet can define Search Assist queries and answers to assist users with search. For more information, see xref:search-assist-tse.adoc[Enable Search Assist]. +Search Assist uses the predefined queries and answers from the Worksheet. Users with edit permissions to a Worksheet can define Search Assist queries and answers to assist users with search. + ++++ diff --git a/modules/ROOT/pages/embed-spotter-agent.adoc b/modules/ROOT/pages/embed-spotter-agent.adoc index 3dbd95cf8..aeaeb8ffc 100644 --- a/modules/ROOT/pages/embed-spotter-agent.adoc +++ b/modules/ROOT/pages/embed-spotter-agent.adoc @@ -13,7 +13,7 @@ Spotter Agent is an embeddable AI analyst component from ThoughtSpot that enable Before you begin, check the following: * You have a ThoughtSpot instance with Spotter Agent enabled. -* You have access to the latest version of the Visual Embed SDK or at least v1.33.1. +* You have access to the latest version of the Visual Embed SDK v1.33.1 or later. * Your host application domain is added to ThoughtSpot CSP and CORS allowlists. == Import the SDK package @@ -62,9 +62,9 @@ init({ }); ---- -== Create an instance of the SpotterEmbed object +== Create an instance of the SpotterAgentEmbed object -Create an instance of the `SpotterEmbed` object and specify the data source ID. Optionally, you can specify the search query string to generate a chart or table at load time. +Create an instance of the `SpotterAgentEmbed` object and specify the data source ID. Optionally, the search query string to generate a chart or table at load time. [source,JavaScript] ---- @@ -77,6 +77,7 @@ const spotterAgentEmbed = new SpotterAgentEmbed(document.getElementById('ts-embe }); ---- + == Customization controls for the embed view (Optional) The embed package for Spotter includes the additional configuration flags to customize the Spotter Agent. Spotter Agent includes only the AI search experience with the Search bar by default. The interface design and styling is controlled by your host app. However, the SDK provides a few controls to customize search experience and app interactions. diff --git a/modules/ROOT/pages/embed-spotter.adoc b/modules/ROOT/pages/embed-spotter.adoc index d9221e1f8..e5c42876d 100644 --- a/modules/ROOT/pages/embed-spotter.adoc +++ b/modules/ROOT/pages/embed-spotter.adoc @@ -14,7 +14,7 @@ To embed Spotter, you need the following access and setup: * Access to a ThoughtSpot instance with the Spotter feature. If you want a specific version of Spotter enabled, work with your ThoughtSpot administrator to enable the xref:embed-ai-analytics.adoc#_feature_status_and_availability_in_embed_mode[required features and settings] on your instance. * Your host application domain is added to xref:security-settings.adoc[ThoughtSpot CSP and CORS allowlists]. -* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK]. + +* Your application project has access to the xref:api-changelog.adoc[latest version of the Visual Embed SDK]. [NOTE] ==== @@ -110,7 +110,7 @@ For more information and examples, see xref:embed-spotter.adoc#configControls[Cu === Register event listeners -To listen to the events emitted by the embedded ThoughtSpot component, register xref:embed-events.adoc#embed-events[embed event] handlers. +To listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers. The following example shows how to register xref:EmbedEvent.adoc#_init[EmbedEvent.Init] and xref:EmbedEvent.adoc#_load[EmbedEvent.Load] listeners. @@ -121,6 +121,18 @@ spotterEmbed.on(EmbedEvent.Init, showLoader); // Show loader when initialization spotterEmbed.on(EmbedEvent.Load, hideLoader); // Hide loader when embed is fully loaded ---- + +[source,JavaScript] +---- +// Use EmbedEvent.Subscribed to safely trigger a HostEvent on initial load +spotterEmbed.on(EmbedEvent.Subscribed, (eventData) => { + if (eventData.data.hostEventType === 'ResetSpotterConversation') { + spotterEmbed.trigger(HostEvent.ResetSpotterConversation); + } +}); +---- + + To trigger actions on the embedded interface, use the xref:HostEvent.adoc[Host events]. The following example shows the host event to reset a Spotter conversation session: @@ -205,7 +217,7 @@ image::./images/spotter3-new-interface.png[Spotter 3 new interface] You can also include the *Chat history* panel to allow your users to access the chat history from their previous sessions. -To enable chat history features, set the `enablePastConversationsSidebar` attributes to `true`. Additionally, you can also customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig#_spottersidebarconfig[spotterSidebarConfig] object. +To enable chat history features, set the `enablePastConversationsSidebar` attributes to `true`. Additionally, you can also customize the appearance and contents of the chat history panel using the configuration parameters available in the xref:SpotterSidebarViewConfig.adoc[`SpotterSidebarViewConfig`] interface and the xref:SpotterEmbedViewConfig.adoc#_spottersidebarconfig[spotterSidebarConfig] object. [source,JavaScript] ---- @@ -232,6 +244,34 @@ The standalone `enablePastConversationsSidebar` attribute is deprecated in v1.47 ==== +==== Chat history panel + +To enable and customize the chat history sidebar, configure the chat history properties in the `spotterSidebarConfig` object: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed(document.getElementById('ts-embed'), { + // ... + worksheetId: '<%=datasourceGUID%>', + spotterSidebarConfig: { + enablePastConversationsSidebar: true, // Enable the chat history sidebar + spotterSidebarDefaultExpanded: true, // Expand the sidebar by default + spotterSidebarTitle: 'Chat History', // Custom sidebar header text + spotterNewChatButtonTitle: 'New Conversation', // Custom label for the New chat button + spotterChatRenameLabel: 'Rename session', // Custom label for the Rename action + spotterChatDeleteLabel: 'Delete session', // Custom label for the Delete action + spotterConversationsBatchSize: 20, // Conversations fetched per batch (default: 30) + spotterDocumentationUrl: 'https://your-help-center-url', // Custom best practices link + }, +}); +---- + +[NOTE] +==== +The standalone `enablePastConversationsSidebar` property on `SpotterEmbedViewConfig` is deprecated from Visual Embed SDK v1.47.0. Use the `enablePastConversationsSidebar` property within the `spotterSidebarConfig` object instead. When both properties are defined, the value in `spotterSidebarConfig` takes precedence. +==== + + ==== MCP connectors and resource selection icon A connector is an external MCP server or tool, such as Google Drive, Slack, Notion, Confluence, or Jira, which can be used as a data source in Spotter sessions. ThoughtSpot administrators can configure connectors to enable Spotter users to include both structured and unstructured data in their conversation sessions. @@ -365,7 +405,7 @@ import { } from '@thoughtspot/visual-embed-sdk'; spotterChatConfig: { - //Hide the default logo and label on tool response cards in Spotter chat UI + // Hide the default logo and label on tool response cards in Spotter chat UI hideToolResponseCardBranding: true, // Set a custom label to display as the branding on tool response cards toolResponseCardBrandingLabel: 'CompanyName', diff --git a/modules/ROOT/pages/embed-ts-react-app.adoc b/modules/ROOT/pages/embed-ts-react-app.adoc index f0bf63313..22f191e43 100644 --- a/modules/ROOT/pages/embed-ts-react-app.adoc +++ b/modules/ROOT/pages/embed-ts-react-app.adoc @@ -83,7 +83,7 @@ You will require GUIDs of the following objects to embed ThoughtSpot components. * Liveboard GUID to embed a Liveboard * Liveboard and visualization GUIDs to embed a visualization from a Liveboard -You can find the GUIDs of these objects in the UI, the developer Playground on your ThoughtSpot instance, or through the xref:metadata-api.adoc#metadata-list[metadata/list] and xref:metadata-api#object-header[metadata/listobjectheaders] REST API endpoints. +You can find the GUIDs of these objects in the UI, the developer Playground on your ThoughtSpot instance, or through the xref:metadata-api.adoc#metadata-list[metadata/list] and xref:metadata-api.adoc#object-header[metadata/listobjectheaders] REST API endpoints. == Embed a Liveboard diff --git a/modules/ROOT/pages/embed-without-sdk.adoc b/modules/ROOT/pages/embed-without-sdk.adoc index f2298e50f..198d6f4c0 100644 --- a/modules/ROOT/pages/embed-without-sdk.adoc +++ b/modules/ROOT/pages/embed-without-sdk.adoc @@ -67,7 +67,7 @@ Note the URL format to embed a Liveboard in an iFrame: `\https://{ThoughtSpot-Host}/?embedApp=true#/embed/viz/{Liveboard_id}` -You can also add xref:embed-without-sdk.adoc#_additional_flags_to_customize_the_embedded_view[additional flags] and xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters and parameter overrides] as query parameters in the embed URL. +You can also add xref:embed-without-sdk.adoc#_feature_flags_and_query_parameters_to_customize_the_embedded_view[additional flags] and xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters and parameter overrides] as query parameters in the embed URL. == Embed a visualization in an iFrame @@ -97,7 +97,7 @@ The URL format to embed a visualization in an iFrame is: `\https://{ThoughtSpot-Host}/?embedApp=true#/embed/viz/{Liveboard_id}/{visualization_id}` -You can also add xref:embed-without-sdk.adoc#_additional_flags_to_customize_the_embedded_view[additional flags], xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters, and Parameter overrides] as query parameters in the embed URL. +You can also add xref:embed-without-sdk.adoc#_feature_flags_and_query_parameters_to_customize_the_embedded_view[additional flags], xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters, and Parameter overrides] as query parameters in the embed URL. //// If you have access to the *Develop* tab in the ThoughtSpot UI, you can use the Playground to obtain the URL for iFrame embed. @@ -143,7 +143,7 @@ If you want to pre-define the search criteria, you can specify the search token `\https://{ThoughtSpot-Host}/?embedApp=true&dataSources=["cd252e5c-b552-49a8-821d-3eadaa049cca"]&searchTokenString=[sales][region]&executeSearch=true&isSearchEmbed=true#/answer` -You can also add xref:embed-without-sdk.adoc#_additional_flags_to_customize_the_embedded_view[additional flags], xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters, and Parameter overrides] as query parameters in the embed URL. +You can also add xref:embed-without-sdk.adoc#_feature_flags_and_query_parameters_to_customize_the_embedded_view[additional flags], xref:embed-without-sdk.adoc#rtOverridesIframe[runtime filters, and Parameter overrides] as query parameters in the embed URL. === URL format for Natural Language Search embed @@ -159,7 +159,7 @@ To load the object with a pre-defined query to fetch data from a specific Model, `\https://{ThoughtSpot-Host}/?embedApp=true&query={query-string}&worksheet={worksheet_id}&executeSearch=true#/embed/insights/create-ai-answer` -See also xref:embed-without-sdk.adoc#_additional_flags_to_customize_the_embedded_view[Additional flags to customize the embedded view]. +See also xref:embed-without-sdk.adoc#_feature_flags_and_query_parameters_to_customize_the_embedded_view[Additional flags to customize the embedded view]. == Embed full application in an iFrame @@ -189,7 +189,7 @@ To embed a ThoughtSpot application page, specify the page ID. + `\https://{ThoughtSpot-Host}/?embedApp=true&primaryNavHidden=false&profileAndHelpInNavBarHidden=true#/home` -See also xref:embed-without-sdk.adoc#_additional_flags_to_customize_the_embedded_view[Additional flags to customize the embedded view]. +See also xref:embed-without-sdk.adoc#_feature_flags_and_query_parameters_to_customize_the_embedded_view[Additional flags to customize the embedded view]. [#rtOverridesIframe] == Apply runtime overrides (Optional) diff --git a/modules/ROOT/pages/event-embedEvents.adoc b/modules/ROOT/pages/event-embedEvents.adoc index affe8edaf..6b7655f0f 100644 --- a/modules/ROOT/pages/event-embedEvents.adoc +++ b/modules/ROOT/pages/event-embedEvents.adoc @@ -103,7 +103,7 @@ Fires when the SSO process is completed correctly. The event does not fire when Fires when an error occurs in the embedded app. . `Load` + -Fires as soon as the area for embedding is created, not when the content has begun or finished loading. +Fires when the area for embedding is created, not when the content has begun or finished loading. . `LiveboardRendered` + Fires only on `LiveboardEmbed` components when the Liveboard or visualization container loads. diff --git a/modules/ROOT/pages/events-context-aware-routing.adoc b/modules/ROOT/pages/events-context-aware-routing.adoc index 61dfc9353..110116d33 100644 --- a/modules/ROOT/pages/events-context-aware-routing.adoc +++ b/modules/ROOT/pages/events-context-aware-routing.adoc @@ -319,7 +319,7 @@ a| *Event routing*: Does not support active layer detection or context resolutio | V2 host events framework + (without explicit target context) -a| *Event routing*: The event is routed to the active layer in the user’s current context. Because this scenario has only one surface, the context resolves to the current page in the embed. + +a| *Event routing*: The event is routed to the active layer in the user’s current context. Because this scenario has only one surface, the context resolves to the current page in the embed. + *Outcome*: The event executes the intended action if a matching handler is found in the active layer; otherwise, it returns an error. a| *Event routing*: The event is routed to the top-most active layer in the user’s current context. + *Outcome*: Only the top-most active layer handles the event. Background or underlying layers are ignored. The event executes the intended action if a matching handler is found in this layer; otherwise, it returns an error. @@ -484,7 +484,7 @@ appEmbed.trigger( == Validation and error handling Ensure that you subscribe to xref:EmbedEvent.adoc#_error[EmbedEvent.Error] in your embed. This enables your embed to emit an event when an error occurs. Error events will be emitted via `EmbedEvent.Error` instead of silent failures, regardless of whether the Host Events V2 framework is enabled. + -Verify the error type and code for host event validation errors.For more information, see xref:EmbedErrorDetailsEvent.adoc[EmbedErrorDetailsEvent]. +Verify the error type and code for host event validation errors. For more information, see xref:EmbedErrorDetailsEvent.adoc[EmbedErrorDetailsEvent]. When the Host Events v2 framework is enabled, the event execution returns errors in the following scenarios: diff --git a/modules/ROOT/pages/full-embed.adoc b/modules/ROOT/pages/full-embed.adoc index 02f4af538..1a6aadcc8 100644 --- a/modules/ROOT/pages/full-embed.adoc +++ b/modules/ROOT/pages/full-embed.adoc @@ -252,7 +252,7 @@ enableSearchAssist _optional_:: _Boolean_. When set to true, it enables Search Assist. Search Assist allows you to create a custom onboarding experience for your users by demonstrating how to search data from the example queries created on your worksheet. + -Search Assist uses predefined queries and answers from the worksheet. Users with edit permissions to a worksheet can define Search Assist queries and answers to assist users with search. For more information, see xref:search-assist-tse.adoc[Enable Search Assist]. +Search Assist uses predefined queries and answers from the worksheet. Users with edit permissions to a worksheet can define Search Assist queries and answers to assist users with search. + ++++ diff --git a/modules/ROOT/pages/git-configuration.adoc b/modules/ROOT/pages/git-configuration.adoc index dbbf1bf12..704792b67 100644 --- a/modules/ROOT/pages/git-configuration.adoc +++ b/modules/ROOT/pages/git-configuration.adoc @@ -77,7 +77,7 @@ Updates can be sent via `xref:git-configuration.adoc#update-git-config[/vcs/git/ === Configuration options The simplest deployment pattern enables *one Git branch* using the `branch_names` parameter, with the same branch as the `commit_branch_name`. The `configuration_branch_name` should be the same for all Orgs related to the same project. This will centralize all the xref:git-configuration.adoc#guid-map-and-config-files[commit and GUID mapping files] for all environments into one branch. -For more advanced Git development patterns, list multiple `branch_names` in the configuration, which will allow you to specify any of the configured branches when using the xref:git-rest-api-guide.adoc#commit-files[commit files] endpoint. +For more advanced Git development patterns, list multiple `branch_names` in the configuration, which will allow you to specify any of the configured branches when using the xref:git-rest-api-guide.adoc#_commit_files[commit files] endpoint. === Request parameters [width="100%" cols="2,6"] @@ -136,7 +136,7 @@ Go into each Org and issue the `config/create` call to link the appropriate bran The following example shows the API request parameters to connect a ThoughtSpot `Prod` Org to the Git repo. Note that GUID mapping is enabled in the API request. -The `Bearer_token` value must be requested for the desired Org, specified through the `org_id` value of the xref:authentication.adoc#get-a-token-for-full-access[full access token] REST API request. +The `Bearer_token` value must be requested for the desired Org, specified through the `org_id` value of the xref:authentication.adoc#_generating_a_full_access_token[full access token] REST API request. [source, cURL] ---- @@ -164,7 +164,7 @@ curl -X POST \ === Initialize .mapping and .config files Version control and xref:guid-mapping.adoc[GUID mapping] utilize files stored in the `configuration_branch`. -You can initialize these files by immediately using the xref:git-rest-api-guide.adoc#deploy-commits[deploy commits REST API] after configuring the Org for Git. +You can initialize these files by immediately using the xref:git-rest-api-guide.adoc#_deploy_commits[deploy commits REST API] after configuring the Org for Git. See the link:https://github.com/thoughtspot/thoughtspot_rest_api_v1_python/blob/main/examples_v2/create_orgs_with_linked_git_branch.py[create_orgs_with_linked_git_branch.py script, window=_blank] for an example of deploying a full Orgs or branches setup for structured development and deployment. diff --git a/modules/ROOT/pages/git-rest-api-guide.adoc b/modules/ROOT/pages/git-rest-api-guide.adoc index 499b6656b..4df14bb53 100644 --- a/modules/ROOT/pages/git-rest-api-guide.adoc +++ b/modules/ROOT/pages/git-rest-api-guide.adoc @@ -13,11 +13,11 @@ The legacy GitHub REST APIs referenced here are tied to GitHub exclusively. The The `/vcs/git/` endpoints of the v2.0 REST API provide all the functionality necessary to xref:git-configuration.adoc[configure], perform version control, and deploy changes to different ThoughtSpot environments, other than xref:guid-mapping.adoc#connection_variations[configuring connections]. -The xref:version_control.adoc#moving-tml-changes-between-environments[basic process] involves the following steps: +The xref:version_control.adoc#_moving_tml_changes_between_environments[basic process] involves the following steps: -1. xref:git-rest-api-guide.adoc#commit-files[Commit changes] into a "dev" branch from the "dev" Org -2. xref:version_control.adoc#moving-changes-from-one-branch-to-another[Move those changes] to other branches via Git -3. xref:git-rest-api-guide.adoc#deploy-commits[Deploy commits] into the *destination Org* (eventually "main" or "prod") +1. xref:git-rest-api-guide.adoc#_commit_files[Commit changes] into a "dev" branch from the "dev" Org +2. xref:version_control.adoc#_moving_changes_from_one_branch_to_another[Move those changes] to other branches via Git +3. xref:git-rest-api-guide.adoc#_deploy_commits[Deploy commits] into the *destination Org* (eventually "main" or "prod") The following sections describe how to use the version control REST APIs after completing xref:git-configuration.adoc[Git configuration] for a ThoughtSpot instance. @@ -30,7 +30,7 @@ You must specify each object to commit within the `metadata` parameter, with eit To get the list of objects to commit, either use the GUID visible in the ThoughtSpot UI URL or use the xref:rest-api-v2-metadata-search.adoc[/metadata/search endpoint] to retrieve a filtered list of objects within ThoughtSpot. -If you do not specify the `branch_name` argument, the commit will be pushed to the `commit_branch_name` defined for the xref:version_control.adoc#connectTS[Git connection configuration]. +If you do not specify the `branch_name` argument, the commit will be pushed to the `commit_branch_name` defined for the xref:git-configuration.adoc#connectTS[Git connection configuration]. Note that you can only specify a *branch_name* that has been xref:git-configuration.adoc[configured for the Org]. @@ -47,7 +47,7 @@ The `delete_aware` property requires you to associate one ThoughtSpot environmen ==== |`branch_name` + -__Optional__|__String__. Name of the branch in the Git repository to which you want to push the commit. If you do not specify the branch name, the commit will be pushed to the `commit_branch_name` defined for the xref:version_control.adoc#connectTS[Git connection configuration]. +__Optional__|__String__. Name of the branch in the Git repository to which you want to push the commit. If you do not specify the branch name, the commit will be pushed to the `commit_branch_name` defined for the xref:git-configuration.adoc#connectTS[Git connection configuration]. |`comment`|__String__. Add a comment to the commit. || |=== diff --git a/modules/ROOT/pages/guid-mapping.adoc b/modules/ROOT/pages/guid-mapping.adoc index 4b1dc362d..a2a14cca8 100644 --- a/modules/ROOT/pages/guid-mapping.adoc +++ b/modules/ROOT/pages/guid-mapping.adoc @@ -6,7 +6,7 @@ :page-pageid: guid-mapping :page-description: Deploying TML involves GUID mapping, handled automatically by the deploy API -The xref:git-rest-api-guide.adoc#deploy-commits[deploy API endpoint] automatically generates and maintains a GUID mapping file in the xref:git-configuration[`config` Git branch] that records the GUID of the objects deployed from a Source Org (dev) to a Destination Org. +The xref:git-rest-api-guide.adoc#_deploy_commits[deploy API endpoint] automatically generates and maintains a GUID mapping file in the xref:git-configuration[`config` Git branch] that records the GUID of the objects deployed from a Source Org (dev) to a Destination Org. [NOTE] ==== @@ -119,8 +119,8 @@ While the best practice is to create a separate `dev Org` and `prod Org` from th You can accomplish this in phases using the Git APIs: 1. Create a temporary Git branch and xref:git-configuration.adoc#update-git-config[update the configuration] to add *Primary*/`prod` Org to make it available to the `commit` operations. -2. Use the xref:git-rest-api-guide.adoc#commit-files[Commit API] to export all desired objects from the *Primary*/`prod` Org into the temporary Git branch (not the xref:git-configuration.adoc#configuration-options[commit branch] that you will use for deployment to the `prod` Org) -3. Use the xref:git-rest-api-guide.adoc#deploy-commits[Deploy API] into the new `dev` Org from the temporary branch to bring all the content into the `dev` Org. This will create the GUID mapping file for the `dev` Org. +2. Use the xref:git-rest-api-guide.adoc#_commit_files[Commit API] to export all desired objects from the *Primary*/`prod` Org into the temporary Git branch (not the xref:git-configuration.adoc#configuration-options[commit branch] that you will use for deployment to the `prod` Org) +3. Use the xref:git-rest-api-guide.adoc#_deploy_commits[Deploy API] into the new `dev` Org from the temporary branch to bring all the content into the `dev` Org. This will create the GUID mapping file for the `dev` Org. 4. Take the JSON structure of the GUID mapping file from the `dev` Org, copy it, swap the keys and values, and then save the result in the GUID Mapping file of the `prod`. === Swap keys and values in the GUID Mapping file diff --git a/modules/ROOT/pages/home.adoc b/modules/ROOT/pages/home.adoc index 6e1d31b51..59849dca6 100644 --- a/modules/ROOT/pages/home.adoc +++ b/modules/ROOT/pages/home.adoc @@ -141,8 +141,8 @@
-
MCP Server
-

Integrate ThoughtSpot analytics into any AI-native application and custom chatbot using ThoughtSpot MCP Server.

+
Spotter MCP Server
+

Integrate ThoughtSpot analytics into any AI-native application and custom chatbot using ThoughtSpot Spotter MCP Server.

diff --git a/modules/ROOT/pages/jwt-migration.adoc b/modules/ROOT/pages/jwt-migration.adoc index 8ca62d9d3..604cbf441 100644 --- a/modules/ROOT/pages/jwt-migration.adoc +++ b/modules/ROOT/pages/jwt-migration.adoc @@ -76,7 +76,8 @@ Migrating your ABAC implementation to the custom token endpoint involves the fol Use the +++REST API v2 Playground+++ test and build requests for the `/api/rest/2.0/auth/token/custom` endpoint. -For more information about the API request and response, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[Get tokens with custom rules and filter conditions]. +For more information about the API request and response, see xref:authentication.adoc#_generate_a_custom_token_for_abac_implementation[Get tokens with custom rules and filter conditions]. + === Step 2: Set column flags In your Worksheet/Model, set `is_mandatory_token_filter` to `true` on columns you want to secure. In Worksheets/Models, set `is_mandatory_token_filter` to `true` on the columns you want to secure. diff --git a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc index 9f24f78e6..2b78d3cf7 100644 --- a/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc +++ b/modules/ROOT/pages/mcp-connect-custom-chatbot.adoc @@ -1,12 +1,12 @@ -= Integrating MCP Server in a custom application or chatbot += Integrating Spotter MCP Server in a custom application or chatbot :toc: true :toclevels: 3 -:page-title: Integrating MCP Server in a custom application or chatbot +:page-title: Integrating Spotter MCP Server in a custom application or chatbot :page-pageid: custom-chatbot-integration-mcp -:page-description: Learn how to build custom applications and chatbots that use ThoughtSpot MCP Server. +:page-description: Learn how to build custom applications and chatbots that use ThoughtSpot Spotter Spotter MCP Server. -If you are building a chatbot client with your own agent and orchestration logic, you can use the MCP Server to call MCP tools behind a custom web experience and integrate it with other systems or services as needed. +If you are building a chatbot client with your own agent and orchestration logic, you can use the Spotter MCP Server to call MCP tools behind a custom web experience and integrate it with other systems or services as needed. When integrated, the agent in your custom application can: @@ -18,7 +18,7 @@ When integrated, the agent in your custom application can: Before you begin, review the following prerequisites: * Node.js version 22 or later is installed and available in your environment. -* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later. +* Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For Spotter MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later. * Ensure that the users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing RLS/CLS rules on tables are enforced automatically in data source responses. To create charts or Liveboards from a conversation session, data download and content creation privileges are required. == Authenticating users @@ -30,7 +30,7 @@ In a typical trusted authentication flow, your backend service calls the `/api/r The token generated for the user session is used as a bearer token when your backend calls ThoughtSpot APIs or when it brokers MCP tool calls. == Connecting clients -If your custom chatbot implementation uses Claude, OpenAI, or Gemini LLM APIs to call MCP tools, ensure that your MCP Server endpoint, authentication token, and ThoughtSpot host are included in the API request. +If your custom chatbot implementation uses Claude, OpenAI, or Gemini LLM APIs to call MCP tools, ensure that your Spotter MCP Server endpoint, authentication token, and ThoughtSpot host are included in the API request. When integrating with apps using custom workflows, ThoughtSpot recommends using the MCP server URL with the date-based `api-version` parameter. This allows you to pin a specific version and avoid introducing unintended changes to custom workflows that rely on tool responses. @@ -104,14 +104,14 @@ curl https://api.openai.com/v1/responses \ In the above example, the API call includes the following parameters: * MCP as the tool type. -* ThoughtSpot MCP Server URL. Replace `YYYY-MM-DD` in the URL with an actual date string. +* ThoughtSpot Spotter MCP Server URL. Replace `YYYY-MM-DD` in the URL with an actual date string. * Authentication token and ThoughtSpot host URL. The OpenAI LLM uses the configured MCP Server, sends the provided headers on each MCP tool call, and gets the requested data from your ThoughtSpot instance under that token's identity. === Gemini API -If your application is the MCP host and Gemini is the LLM provider, use the following code example to connect Gemini to the ThoughtSpot MCP Server. +If your application is the MCP host and Gemini is the LLM provider, use the following code example to connect Gemini to the ThoughtSpot Spotter MCP Server. [source,typescript] ---- @@ -157,7 +157,7 @@ await mcpClient.close(); The above example: -* Creates an MCP client and connects it to the ThoughtSpot MCP Server using `StreamableHTTPClientTransport`. Ensure that you replace `YYYY-MM-DD` in the URL with an actual date string. +* Creates an MCP client and connects it to the ThoughtSpot Spotter MCP Server using `StreamableHTTPClientTransport`. Ensure that you replace `YYYY-MM-DD` in the URL with an actual date string. * Sends the required headers with the authentication token and ThoughtSpot host URL in MCP requests. * Wraps the MCP client as a tool and passes it into `GoogleGenAI` so Gemini can call ThoughtSpot tools as part of answering a user's query. diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 82424a00e..f95b1147f 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -1,15 +1,15 @@ -= ThoughtSpot MCP Server += ThoughtSpot Spotter MCP Server :toc: true :toclevels: 3 :page-title: MCP integration :page-pageid: mcp-integration -:page-description: Learn what ThoughtSpot MCP Server is, when to use it, and how it fits into your AI and analytics architecture. +:page-description: Learn what ThoughtSpot Spotter MCP Server is, when to use it, and how it fits into your AI and analytics architecture. -ThoughtSpot’s Model Context Protocol (MCP) Server enables integration of ThoughtSpot analytics into any AI-native application, custom chatbot, or LLM platform that supports MCP. Instead of rebuilding analytics logic yourself, you connect an LLM/AI agent to the ThoughtSpot MCP Server. +ThoughtSpot’s Model Context Protocol (MCP) Server enables integration of ThoughtSpot analytics into any AI-native application, custom chatbot, or LLM platform that supports MCP. Instead of rebuilding analytics logic yourself, you connect an LLM/AI agent to the ThoughtSpot Spotter MCP Server. == Overview -ThoughtSpot MCP Server exposes ThoughtSpot analytics as tools and resources that MCP-compatible agents can discover and use. When integrated, the MCP Server provides your AI agent or LLM with the following capabilities: +ThoughtSpot Spotter MCP Server exposes ThoughtSpot analytics as tools and resources that MCP-compatible agents can discover and use. When integrated, the MCP Server provides your AI agent or LLM with the following capabilities: * Automatic discovery of ThoughtSpot MCP tools * Natural language queries and responses @@ -17,20 +17,20 @@ ThoughtSpot MCP Server exposes ThoughtSpot analytics as tools and resources that * Generating embeddable visualizations === Supported integrations -ThoughtSpot MCP Server supports two primary integration options: +ThoughtSpot Spotter MCP Server supports two primary integration options: [cols="2,6", options="header"] |=== | Integration option | Description | xref:mcp-server-client-connection.adoc[Plug-and-play clients] -|This integration works with agents or LLMs that natively support MCP, such as Claude, OpenAI, Gemini, or custom MCP clients. It allows your AI agent to call tools directly and leverage ThoughtSpot’s governed analytics, business semantic layer, data context, and row-level/object-level security, without the need to build your analytics logic. +|This integration works with agents or LLMs that natively support MCP, such as Claude, ChatGPT, Gemini, or custom MCP clients. It allows your AI agent to call tools directly and leverage ThoughtSpot’s governed analytics, business semantic layer, data context, and row-level/object-level security, without the need to build your analytics logic. **When to use**: If your application already has an AI chat interface or agentic experience, you can quickly add analytics to your existing setup without custom development. |xref:mcp-connect-custom-chatbot.adoc[Custom chatbot integration] -|If you are building your own MCP-based chatbot or application with custom orchestration logic or LLM, you can integrate the ThoughtSpot MCP Server to call ThoughtSpot tools behind your own web experience. +|If you are building your own MCP-based chatbot or application with custom orchestration logic or LLM, you can integrate the ThoughtSpot Spotter MCP Server to call ThoughtSpot tools behind your own web experience. **When to use**: Use this option if your organization requires a custom conversation flow, backend orchestration, and a tailored analytics experience for your users. @@ -38,8 +38,8 @@ Use this option if your organization requires a custom conversation flow, backen Regardless of integration mode, ThoughtSpot’s semantic layer, data context, and security features ensure trusted and governed analytics for all users. -=== MCP Server license -ThoughtSpot MCP Server is available as an add-on with the following link:https://www.thoughtspot.com/pricing[license plans]: +=== Spotter MCP Server license +ThoughtSpot Spotter MCP Server is available as an add-on with the following link:https://www.thoughtspot.com/pricing[license plans]: * ThoughtSpot Enterprise Edition * ThoughtSpot Embedded @@ -47,19 +47,18 @@ ThoughtSpot MCP Server is available as an add-on with the following link:https:/ To learn more about subscription options, contact your ThoughtSpot sales representative. == Core components and roles -The MCP Server integration and orchestration layers include the following core components: +The Spotter MCP Server integration and orchestration layers include the following core components: -[width="100%" cols="2,6"] -[options='header'] +[cols="2,6", options="header"] |=== |Component|Role |**Host application** | The AI platform or AI-native app that renders chat, responses, and charts, and manages user-facing conversation. For example, Claude AI web app, Claude Desktop, ChatGPT, OpenAI-based integrations, Gemini-based agents, custom web applications, or internal tools. |**MCP client** -a|The MCP client discovers available tools, manages the MCP connection to the server, and passes tool calls between the LLM and the MCP Server. +a|The MCP client discovers available tools, manages the MCP connection to the server, and passes tool calls between the LLM and the Spotter MCP Server. -|**ThoughtSpot MCP Server** a| +|**ThoughtSpot Spotter MCP Server** a| The remote MCP server hosted by ThoughtSpot. - Acts as a gateway between the MCP client and ThoughtSpot. @@ -74,7 +73,7 @@ The remote MCP server hosted by ThoughtSpot. - In integrations using the MCP Server with Spotter 3 support, it provides additional capabilities such as advanced analytics, reasoning, forecasting, automatic data source selection, and deep research. |=== -The following figure illustrates the interaction between the user, agent, and MCP Server: +The following figure illustrates the interaction between the user, agent, and Spotter MCP Server: [.widthAuto] image::./images/agents-mcp-server-arch.png[MCP integration] @@ -145,7 +144,7 @@ Creates a dashboard from `answer_id` values collected from the session update ty == MCP Server URL -ThoughtSpot MCP Server now uses date-based API versioning in the URL. New versions are identified using the `?api-version=YYYY-MM-DD` parameter, which you can append to the MCP Server URL to pin your integration to a specific version. Each new version may introduce tool changes, enhancements, or bug fixes. +ThoughtSpot Spotter MCP Server now uses date-based API versioning in the URL. New versions are identified using the `?api-version=YYYY-MM-DD` parameter, which you can append to the MCP Server URL to pin your integration to a specific version. Each new version may introduce tool changes, enhancements, or bug fixes. When you set the `api-version` to a specific date string, the server returns the version released on the specified date. If no new version of MCP Server is released on the date specified in the URL, the server returns the closest earlier version. For example, if you request `?api-version=2026-06-01` and no new version has been released since `2026-05-01`, the server returns the 2026-05-01 version. This means your integration continues to work without breaking, and you only need to update your pinned date if you want to opt in for a newer version. @@ -179,7 +178,7 @@ ThoughtSpot recommends migrating your existing MCP Server integration setup to t ==== == Next steps -* To learn how to connect existing MCP-aware tools such as Claude, ChatGPT, and Gemini, see the xref:mcp-server-client-connection.adoc[Connecting MCP clients to ThoughtSpot MCP Server] documentation. +* To learn how to connect existing MCP-aware tools such as Claude, ChatGPT, and Gemini, see the xref:mcp-server-client-connection.adoc[Connecting MCP clients to ThoughtSpot Spotter MCP Server] documentation. * To learn how to integrate MCP Server with a custom chatbot or application, see the xref:mcp-connect-custom-chatbot.adoc[Integrating MCP Server in a custom chatbot] documentation. == Additional resources diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index ce53f8fe9..28b2d30c9 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -1,13 +1,13 @@ -= ThoughtSpot MCP Server changelog += ThoughtSpot Spotter MCP Server changelog :toc: true :toclevels: 2 -:page-title: MCP Server Changelog +:page-title: Spotter MCP Server Changelog :page-pageid: mcp-server-changelog -:page-description: Release history for the ThoughtSpot MCP Server, including new tools, breaking changes, deprecations, and bug fixes. +:page-description: Release history for the ThoughtSpot Spotter MCP Server, including new tools, breaking changes, deprecations, and bug fixes. :keywords: MCP Server, changelog, release notes, api-version, breaking changes, deprecation -This changelog lists the new features, enhancements, and other changes introduced in the released versions of the ThoughtSpot MCP Server. For information about MCP Server integration, see the xref:mcp-integration.adoc[MCP Server integration guide]. +This changelog lists the new features, enhancements, and other changes introduced in the released versions of the ThoughtSpot Spotter MCP Server. For information about Spotter MCP Server integration, see the xref:mcp-integration.adoc[MCP Server integration guide]. // ============================================================ // VERSION TEMPLATE — copy this block for each new release @@ -40,14 +40,14 @@ a| [discrete] ==== Support for Spotter 3 -ThoughtSpot MCP Server now supports Spotter 3, enabling advanced analytics, forecasting, multi-step reasoning, and deep research. The new MCP tools support real-time streaming, session-based conversations, richer interactions, and direct embedding of visualizations in MCP-aware apps. + +ThoughtSpot Spotter MCP Server now supports Spotter 3, enabling advanced analytics, forecasting, multi-step reasoning, and deep research. The new MCP tools support real-time streaming, session-based conversations, richer interactions, and direct embedding of visualizations in MCP-aware apps. + For more information, see xref:mcp-server-spotter3.adoc[MCP Server with Spotter 3]. --- [discrete] ==== MCP Server URL changes and API versioning [.version-badge.breaking]#Breaking# -MCP Server URLs now support date-based versioning, defined using the `?api-version=YYYY-MM-DD` parameter. Ensure that you update the xref:mcp-integration.adoc#_mcp_server_url[MCP Server URL] in your integrations as needed. +Spotter MCP Server URLs now support date-based versioning, defined using the `?api-version=YYYY-MM-DD` parameter. Ensure that you update the xref:mcp-integration.adoc#_mcp_server_url[MCP Server URL] in your integrations as needed. [NOTE] ==== @@ -86,7 +86,7 @@ a| [discrete] ==== MCP tools, processing model, and answer retrieval -Supports the following MCP tools released in the initial version of ThoughtSpot MCP Server. +Supports the following MCP tools released in the initial version of ThoughtSpot Spotter MCP Server. * `ping`: Tests connectivity and authentication. * `getDataSourceSuggestions`: Returns available data source suggestions diff --git a/modules/ROOT/pages/mcp-server-client-connection.adoc b/modules/ROOT/pages/mcp-server-client-connection.adoc index 748c30855..e23efaa30 100644 --- a/modules/ROOT/pages/mcp-server-client-connection.adoc +++ b/modules/ROOT/pages/mcp-server-client-connection.adoc @@ -1,16 +1,16 @@ -= Connecting MCP Server to MCP clients += Connecting MCP Server to clients :toc: true :toclevels: 3 :page-title: Connecting MCP Server to MCP clients :page-pageid: connect-mcp-server-to-clients -:page-description: Learn how to connect Claude, ChatGPT, Gemini, and other MCP-aware clients to ThoughtSpot MCP Server with minimal configuration. +:page-description: Learn how to connect Claude, ChatGPT, Gemini, and other MCP-aware clients to ThoughtSpot Spotter MCP Server with minimal configuration. -If your application already has an AI-native experience or supports MCP-aware agents and LLMs, you can integrate ThoughtSpot analytics directly into your app's agentic experience by connecting the MCP Server to your client. +If your application already has an AI-native experience or supports MCP-aware agents and LLMs, you can integrate ThoughtSpot analytics directly into your app's agentic experience by connecting the ThoughtSpot Spotter MCP Server to your client. In this plug-and-play integration, your application's chat interface and LLM orchestrate conversation sessions. The MCP Server exposes ThoughtSpot's analytics capabilities as tools, which your agent or LLM can invoke as needed. This approach allows you to bring ThoughtSpot analytics into your own AI-native experience and use it as a data and analytics provider through the MCP Server, while your system controls user interaction and orchestration logic. -When your MCP client is connected to the ThoughtSpot MCP Server, the AI agent/LLM can: +When your MCP client is connected to the ThoughtSpot Spotter MCP Server, the AI agent/LLM can: * Automatically discover ThoughtSpot MCP tools. * Call the MCP tools to determine the data context and answer data questions. @@ -31,6 +31,19 @@ Before you begin, review the following prerequisites: * Ensure that your setup has access to a ThoughtSpot application instance with 10.11.0.cl or a later release. For MCP Server with Spotter 3 capabilities, ensure that your ThoughtSpot instance is 26.2.0.cl or later. * Ensure that the users have the necessary permissions to view data from relevant models and tables in ThoughtSpot. Existing RLS/CLS rules on tables are enforced automatically in data source responses. To create charts or Liveboards from a conversation session, data download and content creation privileges are required. +== Using ThoughtSpot Spotter with ChatGPT and Claude +The ThoughtSpot Spotter MCP Server is available directly from the ChatGPT and Claude marketplaces. If you want to use ThoughtSpot Spotter with ChatGPT or Claude, you can install it directly from these marketplaces instead of manually configuring it. + +Installation differs by platform: + +ChatGPT:: +ThoughtSpot Spotter is available as an App in the ChatGPT App Store. Search for *ThoughtSpot Spotter* in the ChatGPT App Store and follow ChatGPT's installation instructions. + +Claude:: +ThoughtSpot Spotter is available as a Connector in Claude's Connectors marketplace. Search for *ThoughtSpot Spotter* in Claude's Connectors marketplace and follow Claude's installation instructions. + +Once installed, you can use ThoughtSpot Spotter to query your ThoughtSpot instance directly within ChatGPT or Claude. + === Connecting clients that support remote MCP servers To connect a client that supports remote MCP servers natively, add the MCP Server endpoint to your client's configuration settings. @@ -99,9 +112,9 @@ In a plug-and-play integration, the most common way to authenticate users is thr === OAuth flow In a typical OAuth flow: -* The ThoughtSpot MCP Server is configured as a connector/tool in the MCP client. +* The ThoughtSpot Spotter MCP Server is configured as a connector/tool in the MCP client. * When the user connects, the client redirects the user to ThoughtSpot to sign in. -* After successful login, the client stores the issued OAuth tokens and includes them with each MCP tool call to the ThoughtSpot MCP Server, which then calls ThoughtSpot on behalf of that user. +* After successful login, the client stores the issued OAuth tokens and includes them with each MCP tool call to the ThoughtSpot Spotter MCP Server, which then calls ThoughtSpot on behalf of that user. === OAuth client registration OAuth clients can be registered in one of the following ways: @@ -136,6 +149,29 @@ If user authentication fails, or if the server returns HTTP 500, 401, or 403 sta * Check whether the user session has expired. Log in to your ThoughtSpot application to start a new session. * Verify whether the user has the necessary privileges to view data or create content. +== Switching between Orgs + +If you have access to multiple ThoughtSpot Orgs, the ThoughtSpot Spotter MCP Server defaults to the last Org you were logged into. To switch to a different Org, switch to the Org in ThoughtSpot and re-authenticate with your MCP client. + +To switch Orgs: + +. Log in to your ThoughtSpot instance. +. Select the Org you want to work with using the *Org switcher* in the top navigation bar, next to the help icon. For example, Org A. +. Return to your MCP client and authenticate with your ThoughtSpot credentials. +The MCP Server connects to the Org you selected for all subsequent requests. + +To switch to a different Org later: + +. Log out of ThoughtSpot. +. Log in to your ThoughtSpot instance. +. Select the new Org using the *Org switcher*. For example, Org B. +. Return to your MCP client and re-authenticate with your ThoughtSpot credentials. + +[NOTE] +==== +You must repeat this process each time you want to change Orgs. Currently, the ThoughtSpot Spotter MCP Server cannot switch Orgs mid-session without re-authentication. +==== + == Additional resources * For information about the MCP Server features and architecture, see xref:mcp-integration.adoc[MCP Server integration]. * To view the MCP Server code, go to the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. \ No newline at end of file diff --git a/modules/ROOT/pages/mcp-server-legacy.adoc b/modules/ROOT/pages/mcp-server-legacy.adoc index d10e0fbfd..ce7974a1c 100644 --- a/modules/ROOT/pages/mcp-server-legacy.adoc +++ b/modules/ROOT/pages/mcp-server-legacy.adoc @@ -4,9 +4,9 @@ :page-title: Legacy MCP Server architecture and tools :page-pageid: mcp-server-legacy -:page-description: Learn about the legacy MCP Server architecture and how it fits into your AI and analytics architecture. +:page-description: Learn about the legacy Spotter MCP Server architecture and how it fits into your AI and analytics architecture. -The legacy MCP server setup uses synchronous architecture. It does not support advanced analytics, session context retention, automatic data source selection, streaming responses, and the full answer is always returned inline. All context and data source management must be handled by the client on every request. +The legacy ThoughtSpot Spotter Model Context Protocol (MCP) Server setup uses synchronous architecture. It does not support advanced analytics, session context retention, automatic data source selection, streaming responses, and the full answer is always returned inline. All context and data source management must be handled by the client on every request. Functional capabilities:: Limited capabilities for complex analysis and context integration. @@ -28,7 +28,7 @@ Every follow-up call requires the prior context to be manually included, as the image::./images/mcp-architecture-legacy.png[MCP architecture legacy] == Tool calls and workflow processing -The workflow in the legacy MCP Server setup typically includes the following stages: +The workflow in the legacy Spotter MCP Server setup typically includes the following stages: . *User asks a question* + A user sends a query in the chat interface to get data. For example, `What were the total sales of Jackets and Bags in the Northeast last year?` + @@ -51,7 +51,7 @@ For each suggested or chosen question, the agent calls `getAnswer`. ThoughtSpot To save answers from the conversation sessions in a ThoughtSpot Liveboard, the agent extracts the `question`, `session_identifier`, and `generation_number` from each `getAnswer` response and calls `createLiveboard`. + ThoughtSpot creates a persistent Liveboard from the session's answers and returns identifiers and a `frame_url` for the Liveboard. -In the legacy MCP Server setup, to ask a follow-up question, the agent calls the `getRelevantQuestions` again, because the server doesn't retain context. For follow-up questions, the agent must pass the context explicitly via `additionalContext`. +In the legacy Spotter MCP Server setup, to ask a follow-up question, the agent calls `getRelevantQuestions` again, because the server doesn't retain context. For follow-up questions, the agent must pass the context explicitly via `additionalContext`. For more information about the tool calls, input parameters, and response output, see xref:mcp-tool-reference-guide.adoc#_legacy_mcp_server_setup[MCP tool reference guide]. diff --git a/modules/ROOT/pages/mcp-server-spotter3.adoc b/modules/ROOT/pages/mcp-server-spotter3.adoc index aaa0ae0d7..56d5ee302 100644 --- a/modules/ROOT/pages/mcp-server-spotter3.adoc +++ b/modules/ROOT/pages/mcp-server-spotter3.adoc @@ -6,7 +6,7 @@ :page-pageid: mcp-server-spotter3 :page-description: Learn about the MCP Server with Spotter 3 capabilities, including advanced analytics, streaming responses, and session-based conversations. -ThoughtSpot MCP Server supports link:https://docs.thoughtspot.com/cloud/latest/spotter-versions[Spotter 3, window=_blank], which enables advanced analytics, forecasting, multi-step reasoning and analysis, and deep research capabilities. +ThoughtSpot Spotter MCP Server supports link:https://docs.thoughtspot.com/cloud/latest/spotter-versions[Spotter 3, window=_blank], which enables advanced analytics, forecasting, multi-step reasoning and analysis, and deep research capabilities. The MCP Server with Spotter 3 introduces new MCP tools, real-time streaming responses, session-based conversations, and richer interactions. [cols="2,4,4", options="header"] diff --git a/modules/ROOT/pages/mcp-tool-reference-guide.adoc b/modules/ROOT/pages/mcp-tool-reference-guide.adoc index c9fb5b1dc..9708121bc 100644 --- a/modules/ROOT/pages/mcp-tool-reference-guide.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-guide.adoc @@ -6,7 +6,7 @@ :page-pageid: mcp-tool-reference :page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. -ThoughtSpot MCP Server provides specialized tools that enable the AI agent in your application to access ThoughtSpot analytics. This page lists all supported MCP tools and describes how to call these tools and analyze responses. Refer to the following sections for more information: +ThoughtSpot Spotter MCP Server provides specialized tools that enable the AI agent in your application to access ThoughtSpot analytics. This page lists all supported MCP tools and describes how to call these tools and analyze responses. Refer to the following sections for more information: * xref:mcp-tool-reference-spotter3.adoc[MCP Server version with Spotter 3] [.version-badge.new]#New# * xref:mcp-tool-reference-legacy.adoc[MCP Server with legacy tools] diff --git a/modules/ROOT/pages/mcp-tool-reference-legacy.adoc b/modules/ROOT/pages/mcp-tool-reference-legacy.adoc index f2a98be63..dc764fc25 100644 --- a/modules/ROOT/pages/mcp-tool-reference-legacy.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-legacy.adoc @@ -168,6 +168,3 @@ Key fields are: * `name`: Name of the Liveboard. * `frame_url`: URL that can be embedded to display the Liveboard. - - - diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index 997c9905b..509fb4d6b 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -6,8 +6,20 @@ :page-pageid: mcp-tool-reference-spotter3 :page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. -The new ThoughtSpot MCP integration exposes a session-based workflow for running natural language analytics queries against your ThoughtSpot data sources. The pattern is always: **create a session** → **send a message** → **poll for updates**. - +The ThoughtSpot Spotter Model Context Protocol (MCP) Server integration exposes a session-based workflow for running natural language analytics queries against your ThoughtSpot data sources. The pattern is always: **create a session** → **send a message** → **poll for updates**. + +* <> + +Start an analytical session. +* <> + +Send a natural language question or follow-up. +* <> + +Poll for streamed responses. +* <> + +Create a Liveboard from session answers. +* <> + +Verify that the MCP Server is reachable. + +[#create_analysis_session] == create_analysis_session Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. @@ -43,7 +55,7 @@ call_mcp_tool( [source,json] ---- { -"analytical_session_id": "session-guid-abc123" + "analytical_session_id": "session-guid-abc123" } ---- @@ -51,6 +63,7 @@ call_mcp_tool( * Always capture the returned `analytical_session_id`. It is required for all subsequent calls. +[#send_session_message] == send_session_message Send a natural language analytical question or follow-up to an existing session. The agent processes requests asynchronously, so this tool does not return the answer directly; use `get_session_updates` to retrieve the response. @@ -114,8 +127,8 @@ call_mcp_tool( * To ask a follow-up question, reuse the same `analytical_session_id`. There is no need to create a new session. ==== +[#get_session_updates] == get_session_updates - Poll for the latest response from a ThoughtSpot analytics session. Call this repeatedly after `send_session_message` until `is_done` is `true`. **Important**: A single call to `get_session_updates` will rarely contain the full response. Spotter streams its work incrementally, including intermediate thinking steps, across multiple polling calls. You must accumulate updates from every poll and combine them to get the complete picture. @@ -153,10 +166,10 @@ Poll returning intermediate updates with the "is_thinking" response: "is_done": false, "session_updates": [ { - "is_thinking":true, - "type":"text_chunk", - "text":"Let me look at your sales data by region...", - }, + "is_thinking": true, + "type": "text-chunk", + "text": "Let me look at your sales data by region..." + } ] } ---- @@ -166,27 +179,27 @@ Poll returning final updates: [source,json] ---- { - "is_done": true, - "session_updates":[ - { - "is_thinking":false, - "type":"text-chunk", - "text":"Data broken down by region..." - }, - { - "is_thinking":false, - "type":"text", - "text":"I'm interpreting 'last quarter' as Q4 2025 (October–December), based on a fiscal year starting in April." - }, - { - "is_thinking":false, - "type":"answer", - "answer_title":"Total Sales by Region — Q4 2025", - "answer_query":"total sales by region last quarter", - "iframe_url":"https://your-instance.thoughtspot.cloud/embed/...", - "answer_id":"answer-guid-xyz789" - } - ] + "is_done": true, + "session_updates": [ + { + "is_thinking": false, + "type": "text-chunk", + "text": "Data broken down by region..." + }, + { + "is_thinking": false, + "type": "text", + "text": "I'm interpreting 'last quarter' as Q4 2025 (October–December), based on a fiscal year starting in April." + }, + { + "is_thinking": false, + "type": "answer", + "answer_title": "Total Sales by Region — Q4 2025", + "answer_query": "total sales by region last quarter", + "iframe_url": "https://your-instance.thoughtspot.cloud/embed/...", + "answer_id": "answer-guid-xyz789" + } + ] } ---- @@ -202,7 +215,7 @@ A typical response sequence might look like: . Intermediate conclusions: partial results or contextual notes before the final answer. . The final answer: one or more `answer` updates containing the visualization title, the underlying query, and the embeddable iframe URL. -This means a complete response might span between 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content — the thinking, the narration, and the final answer — should be accumulated and presented together to give the user the full picture. +This means a complete response might span 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content — the thinking, the narration, and the final answer — should be accumulated and presented together to give the user the full picture. === Type definition: session_update @@ -221,9 +234,8 @@ Each item in the `session_updates` list is a `session_update` object. The `type` |`iframe_url`|__String__|An embeddable URL for rendering the answer as an interactive visualization. Present only when `type` is `"answer"`. Use this to display a live chart or table if your environment supports iframes. |==== - +[#create_dashboard] == create_dashboard - Create a ThoughtSpot dashboard from answers generated in an analysis session. * Call this only after `get_session_updates` returns `is_done: true`, because you need the `answer_id` values from completed answer updates. @@ -298,7 +310,7 @@ dashboard = call_mcp_tool( [cols="2,4", options="header"] |==== -|*Field*|*Description* +|Field|Description |`dashboard_id`|The unique identifier of the created dashboard. |`dashboard_url`|A link to the newly created dashboard in ThoughtSpot. @@ -362,6 +374,41 @@ The following features are not supported directly. However, you can use the *Mak * Show underlying data, view query SQL or query visualizer * SpotIQ analysis +[#check_connectivity] +== check_connectivity +Runs a basic health check to verify that the ThoughtSpot Spotter MCP Server is reachable and responding. Use this tool to confirm your connection before starting an analytical session. + +[NOTE] +==== +`check_connectivity` is the Spotter 3 equivalent of the `ping` tool in the legacy MCP version. +==== + +=== Example call + +[div tabbed-code] +-- +[source,javascript] +---- +const result = await callMCPTool("check_connectivity", {}); +---- + +[source,python] +---- +call_mcp_tool("check_connectivity", {}) +---- +-- + +=== Response + +[source,json] +---- +{ + "success": true +} +---- + +* `success`: Returns `true` if the Spotter MCP Server is reachable and operational. + == Additional resources * For a chat client example, see link:https://github.com/thoughtspot/developer-examples/tree/main/mcp/python-react-agent-simple-ui[Python Agent with Simple React UI, window=_blank]. diff --git a/modules/ROOT/pages/metadata-parameterization.adoc b/modules/ROOT/pages/metadata-parameterization.adoc index 603d17164..f8d9b9e0f 100644 --- a/modules/ROOT/pages/metadata-parameterization.adoc +++ b/modules/ROOT/pages/metadata-parameterization.adoc @@ -12,7 +12,7 @@ Metadata parameterization with variables allows administrators to reuse and prop == Before you begin -* Ensure that that xref:variables.adoc[variables are available] on your instance. You can use the xref:variables.adoc#_get_details_of_variables[variable search API] to get a list of variables. +* Ensure that xref:variables.adoc[variables are available] on your instance. You can use the xref:variables.adoc#_get_details_of_variables[variable search API] to get a list of variables. * Ensure that you have edit access to the Connections and Tables to which you want to assign variables. == How to parameterize objects diff --git a/modules/ROOT/pages/mobile-embed-android.adoc b/modules/ROOT/pages/mobile-embed-android.adoc index b7a3a6ad4..31bb20822 100644 --- a/modules/ROOT/pages/mobile-embed-android.adoc +++ b/modules/ROOT/pages/mobile-embed-android.adoc @@ -247,7 +247,7 @@ Define CSS variables to apply custom styles. === Handle events and app interactions -To listen to the events emitted by the embedded ThoughtSpot component, register xref:embed-events.adoc#embed-events[embed event] listeners. +To listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] listeners. [source,Kotlin] ---- @@ -257,7 +257,7 @@ embedView.getController()?.on(EmbedEvent.AuthInit) { payload -> } ---- -To trigger actions on the embedded ThoughtSpot interface, use xref:embed-events.adoc#host-events[Host events]. +To trigger actions on the embedded ThoughtSpot interface, use xref:events-hostEvents.adoc[Host events]. [source,Kotlin] ---- diff --git a/modules/ROOT/pages/mobile-embed-qs-swift.adoc b/modules/ROOT/pages/mobile-embed-qs-swift.adoc index 105fe8e4c..cb5a1ac90 100644 --- a/modules/ROOT/pages/mobile-embed-qs-swift.adoc +++ b/modules/ROOT/pages/mobile-embed-qs-swift.adoc @@ -266,7 +266,7 @@ let embedConfig = EmbedConfig( === Handle events and app interactions -To listen to the events emitted by the embedded ThoughtSpot component, register xref:embed-events.adoc#embed-events[embed event] handlers. +To listen to the events emitted by the embedded ThoughtSpot component, register xref:event-embedEvents.adoc[embed event] handlers. The following example shows how to register event listeners for xref:EmbedEvent.adoc#_liveboardrendered[EmbedEvent.LiveboardRendered], xref:EmbedEvent.adoc#_authinit[EmbedEvent.AuthInit], xref:EmbedEvent.adoc#_error[EmbedEvent.Error], and xref:EmbedEvent.adoc#_authinit[EmbedEvent.AuthInit]: @@ -293,7 +293,7 @@ print("Authentication initialized. Payload: \(payload ?? "nil")") } ---- -To trigger actions on the embedded ThoughtSpot interface, use xref:embed-events.adoc#host-events[Host events] as shown in this example: +To trigger actions on the embedded ThoughtSpot interface, use xref:events-hostEvents.adoc[Host events] as shown in this example: [source,Swift] ---- diff --git a/modules/ROOT/pages/multi-tenancy-best-practices.adoc b/modules/ROOT/pages/multi-tenancy-best-practices.adoc index b8315c099..5e3401841 100644 --- a/modules/ROOT/pages/multi-tenancy-best-practices.adoc +++ b/modules/ROOT/pages/multi-tenancy-best-practices.adoc @@ -50,7 +50,7 @@ There are two aspects of groups which interact to create the “wall” between //// == Multi-tenancy at the user level -Whether users can see each other is controlled by group membership and a property called *shareability*. Please see the documentation on xref:access-control-sharing#_sharing_visibility[access control and sharing] to learn how to configure the shareability properties for users and groups to achieve separation within a single Org. +Whether users can see each other is controlled by group membership and a property called *shareability*. Please see the documentation on xref:access-control-sharing.adoc#_sharing_visibility[access control and sharing] to learn how to configure the shareability properties for users and groups to achieve separation within a single Org. == Multi-Tenancy at the data level In a multi-tenanted database, there is typically a column named “customer_id” or “tenant_id” on every row of data within the database; we’ll call it the tenant key. diff --git a/modules/ROOT/pages/open-issues.adoc b/modules/ROOT/pages/open-issues.adoc index 4f521791d..37d91ef2c 100644 --- a/modules/ROOT/pages/open-issues.adoc +++ b/modules/ROOT/pages/open-issues.adoc @@ -169,7 +169,7 @@ a|To resolve this issue, add an escape character (`\`) after the wildcard in the *Workaround*: Use one of the following options: + -* Use the `/api/rest/2.0/auth/token/full` API endpoint xref:authentication.adoc#bearerToken[to get a bearer token] and use it in the `Authorization` header to authorize your subsequent API requests. +* Use the `/api/rest/2.0/auth/token/full` API endpoint xref:authentication.adoc[to get a bearer token] and use it in the `Authorization` header to authorize your subsequent API requests. * Use the REST API v1 endpoint `/tspublic/v1/session/login` to log in to ThoughtSpot and obtain session cookies. |=== diff --git a/modules/ROOT/pages/orgs.adoc b/modules/ROOT/pages/orgs.adoc index 79fe7ce9b..d83d63f0b 100644 --- a/modules/ROOT/pages/orgs.adoc +++ b/modules/ROOT/pages/orgs.adoc @@ -331,7 +331,7 @@ The following conditions apply to OIDC authentication on a multi-tenant setup: ** If the user does not exist in ThoughtSpot, the user is assigned to the Orgs sent in the OIDC assertion if *Auto create user (JIT)* is enabled. ** If the user is already created in ThoughtSpot and assigned to Orgs and the OIDC assertion has different Org names, the user is assigned to only the Orgs sent in the OIDC assertion. For example, if a user belongs to Org A and Org B and the OIDC assertion includes Org C and Org D, the user is assigned to Org C and Org D and removed from Org A and Org B. * If the Org objects are not configured on ThoughtSpot, the Orgs mapping with OIDC authentication process returns an error. -* If the Orgs mapping with OIDC authentication is not enabled on ThoughtSpot, and Org objects are not configured, the user is assigned to the default Org (Primary Org). +* If the Orgs mapping with OIDC authentication is not enabled on ThoughtSpot, and Org objects are not configured, the user is assigned to the default Org (Primary Org). //// * OIDC per Org configuration is not supported. diff --git a/modules/ROOT/pages/partials/auth-token-api.adoc b/modules/ROOT/pages/partials/auth-token-api.adoc index 5114d57c1..1487121b4 100644 --- a/modules/ROOT/pages/partials/auth-token-api.adoc +++ b/modules/ROOT/pages/partials/auth-token-api.adoc @@ -1,4 +1,4 @@ -If you have enabled xref:trusted-authentication.adoc#trusted-auth-enable[trusted authentication] on ThoughtSpot and have access to the `secret key`, you can send an API request to the `/tspublic/v1/session/auth/token` endpoint and get a login token for a ThoughtSpot user. +If you have enabled xref:trusted-auth-secret-key.adoc#trusted-auth-enable[trusted authentication] on ThoughtSpot and have access to the `secret key`, you can send an API request to the `/tspublic/v1/session/auth/token` endpoint and get a login token for a ThoughtSpot user. After you get the authentication token from ThoughtSpot via a REST API call to the `/tspublic/v1/session/auth/token` endpoint, use this token in your API request to the `/tspublic/v1/session/login/token` endpoint to authenticate and log in a user. diff --git a/modules/ROOT/pages/partials/group-api-list.adoc b/modules/ROOT/pages/partials/group-api-list.adoc index ef85a0304..da18e7659 100644 --- a/modules/ROOT/pages/partials/group-api-list.adoc +++ b/modules/ROOT/pages/partials/group-api-list.adoc @@ -39,7 +39,7 @@ ThoughtSpot Software [version noBackground]#Not available# |`xref:group-api.adoc#add-privilege[**POST** /tspublic/v1/group/addprivilege]` + Assigns a privilege to a user group.|ThoughtSpot Cloud [version noBackground]#ts7.may.cl# + ThoughtSpot Software [version noBackground]#6.0.x# -|`xref:group-api.adoc##removeRole[**POST** /tspublic/v1/group/removerole]` + +|`xref:group-api.adoc#removeRole[**POST** /tspublic/v1/group/removerole]` + Removes the Role assigned to a group.|ThoughtSpot Cloud [version noBackground]#9.7.0.cl# + ThoughtSpot Software [version noBackground]#Not available# |`xref:group-api.adoc#remove-privilege[**POST** /tspublic/v1/group/removeprivilege]` + diff --git a/modules/ROOT/pages/prerender.adoc b/modules/ROOT/pages/prerender.adoc index 32b4035d5..bff01953b 100644 --- a/modules/ROOT/pages/prerender.adoc +++ b/modules/ROOT/pages/prerender.adoc @@ -217,7 +217,6 @@ embed.render(); This approach is more efficient than the previous one, but it does not load the Liveboard data and metadata until the end user actually navigates to the analytics page. So users might see a loading state for a few seconds before the Liveboard is loaded. - === Pre-render on demand If you do not want your host app to fetch any ThoughtSpot resources during its initial load, this approach is ideal. diff --git a/modules/ROOT/pages/rest-api-getstarted.adoc b/modules/ROOT/pages/rest-api-getstarted.adoc index 387fd1981..ec4857c80 100644 --- a/modules/ROOT/pages/rest-api-getstarted.adoc +++ b/modules/ROOT/pages/rest-api-getstarted.adoc @@ -6,6 +6,12 @@ :page-pageid: rest-api-getstarted :page-description: Get started with REST API to access, create, and manage ThoughtSpot resources programmatically. +[IMPORTANT] +==== +The REST API v1 framework has been deprecated and replaced by REST API v2 endpoints. +Existing integrations that use REST API v1 endpoints will continue to function without disruption. However, ThoughtSpot strongly recommends updating your integrations to use REST API v2 endpoints and workflows. For more information about REST API v2 endpoints, see xref:rest-api-v2-reference.adoc[REST API v2 Reference]. +==== + Before you start using REST APIs, perform the following checks: * Your client application domain is added as a xref:security-settings.adoc[Cross-Origin Resource Sharing (CORS) host] in the ThoughtSpot Developer portal. diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index 3fa7aa2e9..9042d1d51 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -216,7 +216,7 @@ public class Example { Make a test API call to test the integration and verify the response. -In this example, we'll use the `CreateUserRequest` object to create a user. +This example uses the `CreateUserRequest` object to create a user. [source, Java] ---- @@ -281,6 +281,8 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later +a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later a|ThoughtSpot Cloud: 26.4.0.cl | v2.23.0 or later a|ThoughtSpot Cloud: 26.3.0.cl | v2.22.0 or later a|ThoughtSpot Cloud: 26.2.0.cl | v2.21.0 or later diff --git a/modules/ROOT/pages/rest-api-reference.adoc b/modules/ROOT/pages/rest-api-reference.adoc index f01593889..47ae5f42a 100644 --- a/modules/ROOT/pages/rest-api-reference.adoc +++ b/modules/ROOT/pages/rest-api-reference.adoc @@ -5,12 +5,12 @@ :page-pageid: rest-api-reference :page-description: REST API Reference +[IMPORTANT] +==== +The REST API v1 framework has been deprecated and replaced by REST API v2 endpoints. +Existing integrations that use REST API v1 endpoints will continue to function without disruption. However, ThoughtSpot strongly recommends updating your integrations to use REST API v2 endpoints and workflows. For more information about REST API v2 endpoints, see xref:rest-api-v2-reference.adoc[REST API v2 Reference]. +==== -[div announcementBlock] --- -Starting from the ThoughtSpot Cloud ts8.nov.cl and ThoughtSpot Software 8.4.1.sw releases, pinboards are rebranded as *Liveboards* in ThoughtSpot UI, documentation, and learning resources. -Note that the `pinboard` and `PINBOARD_ANSWER_BOOK` terminology in REST API v1 endpoint URLs, request and response workflows are not rebranded. --- == Orgs management diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index e37f8da4b..ccb55b8ca 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -203,6 +203,8 @@ Note the version recommendations for your ThoughtSpot instances: [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 26.6.0.cl | v2.25.0 or later +a|ThoughtSpot Cloud: 26.5.0.cl | v2.24.0 or later a|ThoughtSpot Cloud: 26.4.0.cl | v2.23.0 or later a|ThoughtSpot Cloud: 26.3.0.cl | v2.22.0 or later a|ThoughtSpot Cloud: 26.2.0.cl | v2.21.0 or later diff --git a/modules/ROOT/pages/rest-api-v1v2-comparison.adoc b/modules/ROOT/pages/rest-api-v1v2-comparison.adoc index 942e17375..5b3352167 100644 --- a/modules/ROOT/pages/rest-api-v1v2-comparison.adoc +++ b/modules/ROOT/pages/rest-api-v1v2-comparison.adoc @@ -2,12 +2,16 @@ :toc: true :toclevels: 1 - :page-title: Difference between REST API v1 and v2.0 :page-pageid: v1v2-comparison :page-description: Difference between REST API v1 and v2.0 -Both v1 and v2 REST API frameworks allow you to access, retrieve, create, and manage ThoughtSpot objects and resources. REST API v2.0 is a new framework that expands the core API functionality with additional features and improved user experience. +[IMPORTANT] +==== +The REST API v1 framework has been deprecated and replaced by REST API v2 endpoints. The REST API v1 Playground link has also been removed from the **Develop** page in the ThoughtSpot UI in 26.6.0.cl and later versions. Existing integrations that use REST API v1 endpoints will continue to function without disruption. However, ThoughtSpot strongly recommends updating your integrations to use REST API v2 endpoints and workflows. For more information about REST API v2 endpoints, see xref:rest-api-v2-reference.adoc[REST API v2 Reference]. +==== + +Both REST API v1 and REST API v2.0 let you access, retrieve, create, and manage ThoughtSpot objects and resources programmatically. However, the REST API v2.0 framework offers standardized request and response structures, bearer token authentication, and richer capabilities. This document lists the differences between the two versions. == Feature comparison [div tableContainer tableStyle1] @@ -15,12 +19,12 @@ Both v1 and v2 REST API frameworks allow you to access, retrieve, create, and ma [width="100%" cols="4,^5,^5"] [options='header'] |===== -|Feature|REST API v1| REST API v2.0 +|Feature|REST API v1|REST API v2.0 |API Playground|Go to *Develop* > *REST API* > *REST API v1 Playground*. REST API v1 endpoints can be accessed via Swagger API explorer. + -| Go to *Develop* > *REST API* > *REST API v2.0 Playground*. -|Playground access|Requires admin or developer privilege + +|Go to *Develop* > *REST API* > *REST API v2.0 Playground*. +|Playground access|Requires admin or developer privilege |Requires admin or developer privilege |Downloadable code samples| [tag greyBackground tick]#–# | [tag greenBackground tick]#✓# |API documentation| [tag greenBackground tick]#✓# xref:rest-api-reference.adoc[Developer Documentation] a| @@ -32,135 +36,31 @@ REST API v1 endpoints can be accessed via Swagger API explorer. + [tag greenBackground tick]#✓# Trusted authentication -a| [tag greenBackground tick]#✓# Basic authentication + +a|[tag greenBackground tick]#✓# Basic authentication + -[tag greenBackground tick]#✓# Bearer token authentication + +[tag greenBackground tick]#✓# Bearer token authentication + [tag greenBackground tick]#✓# Trusted authentication +[tag greenBackground tick]#✓# JWT for ABAC + |Request and Response structure| Not fully standardized |Standardized -|API services a| See xref:rest-api-v1v2-comparison.adoc##apiOps[Supported API operations] -a| See xref:rest-api-v1v2-comparison.adoc##apiOps[Supported API operations] +|API services a| See xref:rest-api-reference.adoc[Supported REST API v1 operations] +a| See xref:rest-api-v2-reference.adoc[Supported REST API v2 operations] +|Resource URL a| -Resource URL a| *Base URI* + `\https://{your-thoughtspot-hostname}/callosum/v1/` + *Resource path* + `tspublic/v1/{resource-group}/{resource}/` -|*Base URI* + +a| +*Base URI* + `\https://{your-thoughtspot-hostname}/` + *Resource path* + `/api/rest/2.0/{resource-group}/{resource}` -|==== --- - - -[#apiOps] - -//// -== Supported API operations -[div tableContainer] --- -[width="100%" cols="5,4,4"] -[options='header'] -|===== -|API service|REST API v1| REST API v2.0 -a|*Admin services* + -API endpoints for cluster-level administration | [tag greenBackground tick]#✓# Available a| [tag greenBackground tick]#✓# Available + - -__Available under *system* __ + -__Includes query APIs only__ - -|*Authentication* + -API endpoints for user login, authentication, and session management a|[tag greenBackground tick]#✓# Available + - -__The login, authentication, token generation, and logout services are available under **session**__. -|[tag greenBackground tick]#✓# Available + - -|*Data APIs* + -Data query APIs for searching data from a data source and querying a Liveboard and its visualization data.|[tag greenBackground tick]#✓# Available|[tag greenBackground tick]#✓# Available - -|*Connection and live query services* -API endpoints for CRUD operations of data connection objects |[tag greenBackground tick]#✓# Available| [tag greenBackground tick]#✓# - -|*Database services* + -Data management API services for databases such as Falcon + - -__Applicable to ThoughtSpot Software deployments only__ |[tag greenBackground tick]#✓# Available| [tag greyBackground tick]#–# - -|*Dependency services* + -API endpoints for querying dependent object details. |[tag greenBackground tick]#✓# Available| [tag greenBackground tick]#✓# Available + - -__Available as part of metadata API operations__. - -|*Groups* + -API endpoints for group administration and management|[tag greenBackground tick]#✓# Available| [tag greenBackground tick]#✓# Available - -|*Liveboard export* + -API for downloading Liveboard and visualizations data as PDF| -[tag greenBackground tick]#✓# Available| [tag greenBackground tick]#✓# Available + - -__This API service is available under *report*.__ - -|*Logs* + -API for audit logs + -__Applicable to ThoughtSpot Cloud deployments only__ |[tag greenBackground tick]#✓# Available| [tag greenBackground tick]#✓# Available - -|*Materialization services* + -API endpoint for refreshing a materialized view. + - -__Applicable to ThoughtSpot Software deployments only__ |[tag greenBackground tick]#✓# Available| [tag greyBackground tick]#–# - -|*Metadata services* + - -API for querying metadata objects, assigning tags, setting favorites, and importing and exporting TML objects|[tag greenBackground tick]#✓# Available + - -__The metadata API service does not support fetching SQL query information from Answer and Liveboard objects__|[tag greenBackground tick]#✓# Available + - -__Supports fetching SQL query information from Answer and Liveboard objects + -__Includes API services for importing and exporting TML representation of metadata objects such as Liveboard, Worksheets, and Answers__ - -|*Orgs* + -API endpoints for Org administration and management | [tag greenBackground tick]#✓# Available |[tag greenBackground tick]#✓# Available - -|*Reports* + -API endpoints for downloading Liveboards and Answers in PDF, PNG, XLS, or CSV format.| [tag greenBackground tick]#✓# Available + - -__The Answer download API service is not available__ |[tag greenBackground tick]#✓# Available - -|*Session* + -API endpoints for user login, authentication token generation, default Liveboard assignment, and user logout.| [tag greenBackground tick]#✓# Available |[tag greenBackground tick]#✓# Available + - -__The login, authentication, token generation, and logout services are available as *session* resource and are listed under the *Authentication* category in the Playground__. - -|*Security* + -API endpoints for sharing objects and assigning permissions. |[tag greenBackground tick]#✓# Available|[tag greenBackground tick]#✓# Available - -|*System* + -API endpoints for querying system information a|[tag greenBackground tick]#✓# Available + - -__The system administration API operations are available as **Admin services**__|[tag greenBackground tick]#✓# Available - -|*TML* + -API endpoints for importing and exporting TML representation of metadata objects|[tag greenBackground tick]#✓# Available|[tag greenBackground tick]#✓# Available + - -__The import and export metadata API service is available under *metadata*__. - -|*User* + -API endpoints for user administration and management |[tag greenBackground tick]#✓# Available|[tag greenBackground tick]#✓# Available - -|*Version control* + -API endpoints for Git integration and version control |[tag greyBackground tick]#–# Not Available -|[tag greenBackground tick]#✓# Available - -|*Schedules* + -API endpoints to schedule and manage Liveboard jobs. |[tag greyBackground tick]#–# Not Available -|[tag greenBackground tick]#✓# Available - |===== -- -//// == Request methods [div tableContainer] @@ -183,6 +83,7 @@ In REST API v2.0 framework, most of the API operations require you to use the `P For some API operations, such as querying system information or session information, you can use the `GET` method. |===== -- + == Object types and naming convention The following table lists the metadata object types and subtypes supported in REST API v1 and REST API v2.0: @@ -228,24 +129,25 @@ a| Metadata object types in REST API v2.0: * `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. * `LOGICAL_RELATIONSHIP` for table and worksheet joins -__Querying metadata objects by subtypes is not supported in the current release__. +_Querying metadata objects by subtypes is not supported in the current release_. |===== -- + == Request and response structure In REST API v2.0, the API endpoints let you pass several request parameters in a single API call. User and group administration and metadata query APIs support several distinct operations. -The following example shows the REST API v1 and v2 endpoints available for user administration and provisioning: +The following example shows the REST API v1 and v2.0 endpoints available for user administration and provisioning: [.widthAuto] [.bordered] -image::./images/v1-v2-comparison.png[REST API v1 and v2 comparison,link="./doc-images/images/v1-v2-comparison.png"] +image::./images/v1-v2-comparison.png[REST API v1 and v2 comparison,link="./images/v1-v2-comparison.png"] Although the REST API v2.0 has fewer endpoints, it supports all user administration and CRUD operations that were available with REST API v1. === Request body -The following example shows the API v1 and v2 request body for user creation operation: +The following example shows the REST API v1 and v2.0 request body for the user creation operation: REST API v1:: @@ -277,7 +179,7 @@ curl -X POST \ "name": "UserB", "display_name": "User B", "password": "123Cloud!", - "email": "UserA@example.com", + "email": "UserB@example.com", "account_type": "LOCAL_USER", "account_status": "ACTIVE", "group_identifiers": [ diff --git a/modules/ROOT/pages/rest-api-v2-getstarted.adoc b/modules/ROOT/pages/rest-api-v2-getstarted.adoc index 8a3cfe5e2..dcc3cc89c 100644 --- a/modules/ROOT/pages/rest-api-v2-getstarted.adoc +++ b/modules/ROOT/pages/rest-api-v2-getstarted.adoc @@ -24,7 +24,7 @@ By default, your cluster URL is set as the base path for your API requests. * To allow a REST client to log in to ThoughtSpot using `username` and `password`, create a local user account in ThoughtSpot. * To use OAuth 2.0 authentication method, make sure your ThoughtSpot instance has the required configuration to support the OpenID Provider or IdP that authenticates your users. -* To trusted authentication to authenticate REST clients, make sure xref:trusted-authentication.adoc#trusted-auth-enable[Trusted authentication is enabled] on your ThoughtSpot instance, and your authenticator service has access to the `secret key`. +* To trusted authentication to authenticate REST clients, make sure xref:trusted-auth-secret-key.adoc#trusted-auth-enable[Trusted authentication is enabled] on your ThoughtSpot instance, and your authenticator service has access to the `secret key`. == Authorize your client diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index 00170609a..d50cd0cd5 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -31,10 +31,10 @@ Creates a conversation session with ThoughtSpot Spotter |ThoughtSpot Cloud: __10.4.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ -//a|`POST /api/rest/2.0/ai/data-source-suggestions` + -//Gets data source recommendations for a given query. -//|ThoughtSpot Cloud: __10.15.0.cl or later__ + -//|+++Try it out+++ +a|`POST /api/rest/2.0/ai/data-source-suggestions` + +Gets data source recommendations for a given query. +|ThoughtSpot Cloud: __26.2.0.cl or later__ + +|+++Try it out+++ a|`POST /api/rest/2.0/ai/relevant-questions/` + Breaks down a user submitted query into relevant questions @@ -61,6 +61,21 @@ Allows sending a query to an ongoing conversation session with Spotter agent and |ThoughtSpot Cloud: __10.15.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ +a|`PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets custom instructions for the Spotter agent. +|ThoughtSpot Cloud: __26.6.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the custom instructions currently configured for the Spotter agent. +|ThoughtSpot Cloud: __26.6.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + +Stops an in-progress Spotter agent response for a given conversation session. +|ThoughtSpot Cloud: __26.6.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + a|`POST /api/rest/2.0/ai/instructions/set` + Sets NL instructions on a data model. |ThoughtSpot Cloud: __10.15.0.cl or later__ + @@ -130,6 +145,15 @@ ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out +++ + +a| `POST /api/rest/2.0/auth/configure` + +Enables or disables authentication. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + +a| +++Try it out +++ + +a| `POST /api/rest/2.0/auth/search` + +Retrieves the authentication configuration for the specified auth type. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + +a| +++Try it out +++ + |===== -- @@ -237,6 +261,11 @@ Downloads connection metadata differences between Cloud Data Warehouse and Thoug ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out +++ + +a| `POST /api/rest/2.0/connections/{connection_identifier}/status` + +Deactivates or activates a connection. a| ThoughtSpot Cloud: __26.6.0.cl or later__ + +a| +++Try it out +++ + |===== -- == Connection Configuration diff --git a/modules/ROOT/pages/rest-apiv1-changelog.adoc b/modules/ROOT/pages/rest-apiv1-changelog.adoc index 9b90bf3c3..e0bcc2d87 100644 --- a/modules/ROOT/pages/rest-apiv1-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv1-changelog.adoc @@ -121,7 +121,7 @@ For multi-tenant clusters with Orgs, ThoughtSpot provides new endpoints to allow For more information, see xref:org-api.adoc[Org API] and xref:org-manage-api.adoc[Org administration and management via REST API]. Session API endpoints;; -If the Orgs feature is enabled and Orgs are created on your cluster, the cluster administrators can use the `/tspublic/v1/session/orgs` to xref:session-api#orgSwitch[Switch between Orgs]. +If the Orgs feature is enabled and Orgs are created on your cluster, the cluster administrators can use the `/tspublic/v1/session/orgs` to xref:session-api.adoc#orgSwitch[Switch between Orgs]. + For deployments with the trusted authentication framework, you can use the `/tspublic/v1/session/auth/token` API endpoint lets you xref:session-api.adoc#session-authToken[create a user just-in-time and dynamically assign Orgs, groups, and privileges to that user]. @@ -130,7 +130,7 @@ On multi-tenant clusters with Orgs, the `user` and `group` API endpoints allow a For more information, refer to the following articles: * xref:user-api.adoc#create-user[create a user] * xref:user-api.adoc#update-user[update user details] -* xref:user-api.adoc##delete-user[delete a user account] +* xref:user-api.adoc#delete-user[delete a user account] * xref:group-api.adoc#create-group[create a group] == Version 8.9.0.cl, November 2022 diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 720af01df..7c9ecbe95 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,88 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 26.6.0.cl, June 2026 + +=== Spotter AI APIs + +Agent instructions APIs:: +The following new API endpoints allow you to set and retrieve persistent behavioral instructions for the Spotter agent. + +* `PUT /api/rest/2.0/ai/agent/instructions/set` + +Sets behavioral instructions for the Spotter agent. Use this endpoint to define persistent guidance that Spotter applies when responding to queries in a conversation session. + +* `GET /api/rest/2.0/ai/agent/instructions/get` + +Retrieves the behavioral instructions currently configured by the administrator for the Spotter agent. + ++ +For more information, see xref:spotter-agent-instructions.adoc[Spotter AI Agent instructions APIs]. + +Stop in-progress agent response:: + +* `POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` + +Stops a Spotter agent response that is currently in progress for a given conversation session. + +For more information, see xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stop an in-progress agent response]. + +==== Authentication +The following new endpoints allow searching for the authentication configuration at the cluster or Org level, and also allows enabling and disabling the authentication. Currently, only support trusted authentication. + +* `POST /api/rest/2.0/auth/configure` + +Enables or disables authentication at cluster or Org level for the specified auth type. +* `POST /api/rest/2.0/auth/search` + +Returns the authentication configuration for the specified auth type at cluster and Org level. + +==== Connection deactivate and activate API [beta betaBackground]^Beta^ + +// SOURCE: SCAL-294844, SCAL-294845, SCAL-278132 + +ThoughtSpot introduces REST API v2.0 endpoints to programmatically deactivate and activate data connections: + +* `POST /api/rest/2.0/connections/{connection_identifier}/status` + +Deactivates or activates a connection. + +=== Answer report API enhancements [earlyAccess eaBackground]#Early Access# + +The `POST /api/rest/2.0/report/answer` API endpoint introduces the following enhancements: + +Pinned Answer export:: +// SOURCE: SCAL-236681, SCAL-306548 +You can now export a pinned Answer directly from a Liveboard using the Answer report API. +To export a pinned Answer, specify the `viz_guid` parameter in your API request. +Exports from this endpoint inherently respect Liveboard-level filters, Runtime Filters, Column security rules, and JWT token context. ++ +To export a specific personalized view of a pinned Answer, include the `personalised_view_identifier` parameter. + +Spotter Answer export:: +// SOURCE: SCAL-236681, SCAL-306548 +XLSX and PDF export formats are now supported for Spotter (conversational) Answers. + +Custom PNG dimensions:: +// SOURCE: SCAL-236681, SCAL-306548 +PNG exports now support custom dimensions via the following new parameters: ++ +* `x_resolution` — Sets the export width in pixels. Valid range: 600–3840 px. +* `y_resolution` — Sets the export height in pixels. Valid range: 600–3840 px. + +Display scaling:: +// SOURCE: SCAL-236681, SCAL-306548 +A new `scaling` parameter allows you to adjust the relative size of visual elements in PNG exports without cropping. +Valid range: 80–500%. + +Automatic file naming:: +// SOURCE: SCAL-236681, SCAL-306548 +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. +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^ + +The `POST /api/rest/2.0/security/metadata/share` endpoint now supports sharing Collections. + +To share a Collection, set `metadata_type` to `COLLECTION` in the request body. +For more information, see xref:collections.adoc#share-collection[Share a Collection]. + == Version 26.5.0.cl, May 2026 === Sync connection metadata attributes @@ -438,7 +520,7 @@ The search metadata (`/api/rest/2.0/metadata/search`) API includes the following * The `liveboard_reponse_version` parameter. It allows you to specify the xref:rest-api-v2-metadata-search.adoc#_response_format_for_liveboards[response format for Liveboard objects]. * The `subtypes` attribute to specify the sub-type for the `LOGICAL_TABLE` metadata type. The `LOGICAL_TABLE` type allows to fetch objects such as Tables, Models, and Views. The `subtypes` parameter allows you to filter API response by specifying subcategories of the object type. -* The `include_only_published_objects` attribute to specify whether the search should should include xref:publish-api.adoc[published objects]. +* The `include_only_published_objects` attribute to specify whether the search should include xref:publish-api.adoc[published objects]. === System API @@ -694,7 +776,7 @@ Authentication:: The `/api/rest/2.0/auth/token/custom` API endpoint is now available to generate an authentication token with custom rules and filter conditions for a user. + -ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[REST API v2 authentication] and xref:abac-user-parameters.adoc[ABAC via tokens]. +ThoughtSpot recommends using the custom token API endpoint to generate tokens for the Attribute-Based Access Control (ABAC) implementation. For more information, see xref:abac_rls-variables.adoc[ABAC via RLS with variables]. Connections:: The following new API endpoints are available for updating and deleting a connection object: @@ -937,7 +1019,7 @@ Deprecation notice:: The `default_branch_name` and `guid_mapping_branch_name` parameters will be deprecated from version 10.0.0.cl and later releases. -For more information, see xref:version_control.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. +For more information, see xref:git-configuration.adoc#connectTS[Connect your ThoughtSpot environment to the Git repository]. ==== Commit API diff --git a/modules/ROOT/pages/rls-rules.adoc b/modules/ROOT/pages/rls-rules.adoc index 60bcc32a1..c38e10f46 100644 --- a/modules/ROOT/pages/rls-rules.adoc +++ b/modules/ROOT/pages/rls-rules.adoc @@ -172,7 +172,7 @@ With the JOINs set up properly, you place the RLS Rule not on the ACL table, but This will cause queries that reference the fact or dimension to include the INNER JOIN to the ACL table, with the filter condition on the signed-in user. === Updating the ACL table -In the ACL table pattern, the embedding web application must define a process for updating the ACL table in the data warehouse with the correct entitlement rows for each user. This is a separate process that does not involve ThoughtSpot, although it can be combined with the xref:trusted-authentication#authenticator-service-back-end[authenticator service] used for Trusted Authentication. +In the ACL table pattern, the embedding web application must define a process for updating the ACL table in the data warehouse with the correct entitlement rows for each user. This is a separate process that does not involve ThoughtSpot, although it can be combined with the xref:trusted-authentication.adoc#authenticator-service-back-end[authenticator service] used for Trusted Authentication. == Additional resources See the link:https://community.thoughtspot.com/customers/s/article/How-to-secure-your-data-in-ThoughtSpot[RLS best practices guide, window=_blank] for a comprehensive guide with RLS examples. A data model setup is also available on the ThoughtSpot Community. diff --git a/modules/ROOT/pages/security-settings.adoc b/modules/ROOT/pages/security-settings.adoc index 80a485d06..01b02b423 100644 --- a/modules/ROOT/pages/security-settings.adoc +++ b/modules/ROOT/pages/security-settings.adoc @@ -492,10 +492,15 @@ curl -X POST \ ---- === Trusted authentication -See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management]. +To enable or disable trusted authentication at the cluster or Org level, send a request to the `POST /api/rest/2.0/auth/configure` endpoint. + +To find the trusted authentication configuration for the specified auth type at the cluster or Org level, send a request to the `POST /api/rest/2.0/auth/search` endpoint. + +For more information on the trusted authentication configuration through APIs, see xref:authentication.adoc[Configuring authentication settings]. + +See xref:trusted-authentication.adoc[Trusted authentication] and xref:_secret_key_management[Secret key management] for other related information. + -[NOTE] -Trusted authentication is not supported through the REST APIs v2. == Retrieve security settings You can retrieve the security settings for your ThoughtSpot instance by sending a `POST` request to `POST /api/rest/2.0/system/security-settings/search` API endpoint. diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 3eb4a5680..4b07695db 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1,4 +1,4 @@ -= AI APIs (Spotter Agent and Spotter 3) += Spotter Agent AIs :toc: true :toclevels: 2 @@ -49,6 +49,10 @@ a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/send/strea xref:spotter-agent-apis.adoc#_send_a_query_to_agent_and_get_streaming_responses[Sends one or more natural language messages] to an existing Spotter agent conversation and returns the response as a real-time Server-Sent Events (SSE) stream. __Replaces /api/rest/2.0/ai/agent/{conversation_identifier}/converse__. +a|`POST /api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` [.version-badge.new]#New# + +xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[Stops an in-progress Spotter agent response] for a given conversation session. The conversation session remains active after the response stops. + +__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ + a| `POST /api/rest/2.0/ai/data-source-suggestions` [beta betaBackground]^Beta^ + xref:spotter-agent-apis.adoc#_get_data_source_suggestions[Returns a list of relevant data sources], such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + __Available on ThoughtSpot Cloud instances from 10.15.0.cl onwards__. @@ -1034,6 +1038,50 @@ data: { } ---- +[#_stop_an_in_progress_agent_response] +== Stop an in-progress agent response + +The `/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response` API endpoint stops a Spotter agent response that is currently in progress for a given conversation session. + +Use this endpoint when you want to cancel a long-running Spotter response before it completes. +The conversation session remains active after you stop a response, so you can send a new query to the same session immediately. + +=== Request parameters + +[width="100%", cols="2,2,4"] +[options='header'] +|===== +|Parameter|Type| Description +|`conversation_identifier`|Path parameter|__String__. Required. The identifier of the active conversation session. Use the value returned by the xref:spotter-agent-apis.adoc#_create_a_conversation_session_with_spotter_agent[create conversation] API endpoint. +|===== + +This endpoint does not require a request body. + +=== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/{conversation_identifier}/stop-response' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot stops the in-progress response and returns an 204 response code. + +If the conversation session is not found or has expired, the API returns an error: + +[source,JSON] +---- +{ + "error_code": "CONVERSATION_NOT_FOUND", + "message": "The specified conversation session does not exist or has expired." +} +---- + [#process_results] == Process results generated from a conversation session To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. diff --git a/modules/ROOT/pages/spotter-agent-instructions.adoc b/modules/ROOT/pages/spotter-agent-instructions.adoc new file mode 100644 index 000000000..09b16adc5 --- /dev/null +++ b/modules/ROOT/pages/spotter-agent-instructions.adoc @@ -0,0 +1,132 @@ += Spotter AI Agent instructions API +:toc: true +:toclevels: 2 + +:page-title: Spotter Agent instructions APIs +:page-pageid: spotter-agent-instructions +:page-description: Use the Spotter agent instructions APIs to set and retrieve persistent behavioral guidance for the Spotter agent in a conversation session. + +Administrators and developers can configure persistent behavioral instructions for the Spotter agent using the agent instructions APIs. These instructions guide how Spotter responds within a conversation context. For example, to focus on specific business domains, enforce response formats, or apply analytical constraints. + +Unlike xref:spotter-nl-instructions.adoc[NL coaching instructions], which operate at the data model level, agent instructions operate at the agent level and do not require a data source identifier. + +[NOTE] +==== +To use the agent instructions APIs, you need `CAN_USE_SPOTTER` privilege and valid authentication. +==== + +== Supported API endpoints + +[width="100%", cols="1"] +|===== +a|`PUT /api/rest/2.0/ai/agent/instructions/set` [.version-badge.new]#New# + +xref:spotter-agent-instructions.adoc#_set_agent_instructions[Sets behavioral instructions] for the Spotter agent. + +__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ + +a|`GET /api/rest/2.0/ai/agent/instructions/get` [.version-badge.new]#New# + +xref:spotter-agent-instructions.adoc#_get_agent_instructions[Retrieves the behavioral instructions] currently configured for the Spotter agent. + +__Available on ThoughtSpot Cloud instances from 26.6.0.cl onwards.__ +|===== + +== Set agent instructions + +The `PUT /api/rest/2.0/ai/agent/instructions/set` API endpoint sets behavioral instructions for the Spotter agent. +Use this endpoint to define persistent guidance that Spotter applies when responding to queries. +Instructions persist until you overwrite or remove them by sending a new `PUT` request. + +=== Request parameters + +[width="100%", cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`instructions` a|__String__. Required. +The behavioral instruction text to apply to the Spotter agent. +Use natural language to define how Spotter should respond. For example: + +* `"Always respond in English."` +* `"Focus on revenue and margin metrics. Avoid referencing raw row counts unless the user asks."` +* `"When a time period is not specified, default to the current fiscal quarter."` + +|===== + +=== Example request + +[source,cURL] +---- +curl -X PUT \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/instructions/set' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "instructions": "Always respond in English. Focus on revenue and margin metrics. When a time period is not specified, default to the current fiscal quarter." +}' +---- + +=== Example response + +If the API request is successful, ThoughtSpot returns an HTTP `200` response with the following agent instruction properties: + +If the request is successful, the response includes the saved AgentInstructions record: + +* `id`: unique identifier of the record +* `instructions`: the saved instructions text +* `created_at`: ISO timestamp when the instructions were first created +* `updated_at`: ISO timestamp of this update +* `last_updated_by`: user ID of the admin who performed this update + +If the request fails, ThoughtSpot returns an error code and message. For example, if the REST client doesn't have the permission to set agent instructions, the following example shows an authorization error: + +[source,JSON] +---- +{ + "error_code": "UNAUTHORIZED", + "message": "You do not have permission to set agent instructions." +} +---- + +== Get agent instructions + +The `GET /api/rest/2.0/ai/agent/instructions/get` API endpoint retrieves the behavioral instructions currently configured for the Spotter agent. + +=== Request parameters + +This endpoint does not require a request body or query parameters. + +=== Example request + +[source,cURL] +---- +curl -X GET \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/instructions/get' \ + -H 'Accept: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' +---- + +=== Example response + +If the API request is successful and instructions are configured, ThoughtSpot returns the current instructions in the response body. + +[source,JSON] +---- +{ + "instructions": "Always respond in English. Focus on revenue and margin metrics. When a time period is not specified, default to the current fiscal quarter." +} +---- + +If no instructions are configured, ThoughtSpot returns an empty value for the `instructions` field. + +[source,JSON] +---- +{ + "instructions": "" +} +---- + +== Related resources + +* For information about coaching Spotter at the data model level, see xref:spotter-nl-instructions.adoc[Spotter coaching APIs]. +* For information about Spotter agent conversation workflows, see xref:spotter-agent-apis.adoc[AI APIs (Spotter Agent and Spotter 3)]. +* Visit the +++REST API v2.0 Playground+++ to test the set agent instructions endpoint. +* Visit the +++REST API v2.0 Playground+++ to test the get agent instructions endpoint. diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index f4ee15d71..88aab5c4a 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -13,7 +13,6 @@ The key capabilities of the Spotter APIs include the following: * Initiating and managing conversational sessions * Processing natural-language queries and interpreting user intent * Generating analytical responses, insights, and visualizations -//* Recommending relevant datasets or data sources * Decomposing complex user queries Spotter manages conversation sessions, context tracking, and response generation for user-submitted queries. The Spotter APIs are designed for use in Spotter-driven analytics and also for agentic interactions within an orchestrated agent framework. @@ -27,13 +26,14 @@ For information about supported API operations, see the following pages: * xref:spotter-classic-apis.adoc[APIs for Spotter classic workflow] * xref:spotter-agent-apis.adoc[APIs for Spotter agent workflows] * xref:spotter-nl-instructions.adoc[APIs for Spotter coaching and NL instructions] +* xref:spotter-agent-instructions.adoc[APIs for Spotter agent instructions] == Locale settings for API requests When using the xref:spotter-classic-apis.adoc#_generate_a_single_answer[Single Answer] and xref:spotter-classic-apis.adoc#_send_a_query_to_a_conversation_session[Send message] APIs, the locale used for API requests depends on your application's locale settings: * If your application is set to "Use browser language", the API will use this locale to generate responses. To override this setting, you must explicitly include the desired locale code in the `Accept-Language` header of your API request. To ensure consistent localization, set the `Accept-Language` header in your API requests when relying on browser language detection, or configure the locale explicitly in the user profile settings in ThoughtSpot. -* If you have set a specific locale in your ThoughtSpot instance or user profile, the API will use this locale to generate responses, overriding the browser or OS locale. +* If you have set a specific locale in your ThoughtSpot instance or user profile, the API uses this locale to generate responses, overriding the browser or OS locale. == Per-user API rate limits diff --git a/modules/ROOT/pages/spotter-nl-instructions.adoc b/modules/ROOT/pages/spotter-nl-instructions.adoc index 4a278c469..54c9a2de4 100644 --- a/modules/ROOT/pages/spotter-nl-instructions.adoc +++ b/modules/ROOT/pages/spotter-nl-instructions.adoc @@ -1,4 +1,4 @@ -= Spotter coaching APIs += Spotter instructions API :toc: true :toclevels: 2 diff --git a/modules/ROOT/pages/spottercode-integration.adoc b/modules/ROOT/pages/spottercode-integration.adoc index 4fc9a1104..31209817e 100644 --- a/modules/ROOT/pages/spottercode-integration.adoc +++ b/modules/ROOT/pages/spottercode-integration.adoc @@ -6,12 +6,12 @@ :page-pageid: integrate-SpotterCode :page-description: This document provides a comprehensive, step-by-step approach to integrating SpotterCode with your development environment -Connecting your IDE to ThoughtSpot's SpotterCode is easy. All you need is the SpotterCode MCP Server URL. This guide will walk you through the process of adding SpotterCode to your IDE. +This guide walks you through the process of adding SpotterCode to your IDE. == Before you begin * Ensure that your IDE is AI-native and supports chat sessions with AI models. -* Ensure that you have the necessary permissions to configure MCP servers on your IDE. +* Ensure that you have the necessary permissions to configure Model Context Protocol (MCP) servers in your IDE. * Ensure that the latest version of Node.js is installed in your environment. This is required for building embedding code with the SDK. * Ensure that you have access to a ThoughtSpot instance and can view the objects and resources that you want to embed or access via the REST API. @@ -25,14 +25,14 @@ Via Cursor Marketplace:: SpotterCode is available as an official plugin in the link:https://cursor.com/marketplace/thoughtspot[Cursor Marketplace, window=_blank]. To install SpotterCode from the Cursor Marketplace: . Go to link:https://cursor.com/marketplace/thoughtspot[Cursor Marketplace, window=_blank]. . Ensure that you are signed in, and then click **Add to Cursor** -> **Add Plugin**. -. To view it in your Cursor, click *View in Editor*. +. To view the plugin in Cursor, click *View in Editor*. Via installation link:: . Copy the following link and open it in Cursor: + + `cursor://anysphere.cursor-deeplink/mcp/install?name=SpotterCode&config=eyJ1cmwiOiJodHRwczovL3Nwb3R0ZXJjb2RlLnRob3VnaHRzcG90LmFwcC9tY3AifQ==` + -. On clicking this link, Cursor opens the MCP server installation page to add SpotterCode. +. Cursor opens the MCP server installation page to add SpotterCode. . Click **Install**. //// @@ -41,7 +41,7 @@ Via installation link:: image:./images/spottercode-cursor-url.png[SpotterCode MCP Server installation in Cursor] //// -=== Using mcp.json file +=== Using the mcp.json file Cursor also allows you to integrate SpotterCode by adding the MCP server URL in the `mcp.json` file. To add the URL: @@ -58,58 +58,37 @@ Cursor also allows you to integrate SpotterCode by adding the MCP server URL in } } ---- -. Click *Save* and close the `mcp.json` file. This will install the SpotterCode MCP server and tools for the AI models on Cursor to execute. +. Click *Save* and close the `mcp.json` file. This installs the SpotterCode MCP server and makes its tools available for AI models in Cursor. For information about configuring MCP servers in Cursor, refer to the link:https://cursor.com/docs/context/mcp[Cursor Documentation, window=_blank]. - -== Integrate SpotterCode with Visual Studio Code - -Although you can configure the MCP server in Visual Studio Code, to start a chat session with the AI agent, you'll need GitHub Copilot or a similar extension. - -To add an MCP Server to Visual Studio Code, you can use the Extensions view, the `MCP: Add Server` command via command palette, or directly edit the `mcp.json` file in your workspace configuration. - -[source,JSON] ----- -{ - "servers": { - "SpotterCode": { - "url": "https://spottercode.thoughtspot.app/mcp", - "type": "http" - } - } -} ----- - -After you add the MCP server URL, the SpotterCode MCP server will be available in the Extensions view. For more information about configuring MCP servers in Visual Studio Code, refer to link:https://code.visualstudio.com/docs/copilot/customization/mcp-servers[Visual Studio Code Documentation, window=_blank]. - == Integrate SpotterCode with Claude -If your Claude account includes access to Claude AI (web chat), you can add SpotterCode as a remote MCP connector. Connectors added in Claude AI automatically sync to Claude Cowork and Claude Code without any additional configuration. +If your Claude account includes access to Claude AI (web chat), you can add SpotterCode as a remote MCP connector. Connectors added in Claude AI automatically sync to Claude Code without any additional configuration. -For the xref:spottercode-integration.adoc#_for_integration_setup_with_claude_code[Claude Code-only setup], you must manually point Claude Code to the SpotterCode MCP server via CLI. +For the xref:spottercode-integration.adoc#_claude_code_only_setup[Claude Code-only setup], you must manually point Claude Code to the SpotterCode MCP server via CLI. -=== For integration setup with Claude AI +=== Claude AI integration To add SpotterCode as a custom connector: . Go to **Customize** > **Connectors** . Click the `+` icon and select **Add custom connector**. -. Enter the SpotterCode MCP server URL. +. Enter the SpotterCode MCP server URL: `https://spottercode.thoughtspot.app/mcp`. . Click **Add**. -This configuration will automatically enable SpotterCode in Claude AI chat, Claude Cowork, and Claude Code for users of the Claude account. +This configuration automatically enables SpotterCode in Claude AI chat and Claude Code for users of the Claude account. -=== For Claude Code-only setup +=== Claude Code-only setup -To enable SpotterCode in Claude Code, add the MCP server URL using the following `claude mcp add` command in Claude Code CLI. +To enable SpotterCode in Claude Code, add the MCP server URL using the following `claude mcp add` command in the Claude Code CLI. [source,Bash] ---- claude mcp add --transport http SpotterCode https://spottercode.thoughtspot.app/mcp ---- -=== For Claude Desktop +=== Claude Desktop integration If you are using Claude Desktop, add the URL directly to the Claude configuration JSON file: [source,JSON] @@ -123,8 +102,38 @@ If you are using Claude Desktop, add the URL directly to the Claude configuratio } ---- +=== Claude Cowork integration +If you are using Claude Cowork with Claude AI or Claude Desktop, verify whether the SpotterCode MCP connector is enabled for Claude Cowork. If it's not enabled, add the SpotterCode MCP server: + +. Open Claude Cowork either in Claude AI or Claude Desktop app. +. Navigate to **Settings** > **Connectors** > **Customize**. +. If SpotterCode is already available in your organization's list of connectors, select the SpotterCode connector. If it's not available: +.. Click the `+` icon and select **Add custom connector**. +.. Add the SpotterCode MCP server URL: `\https://spottercode.thoughtspot.app/mcp`. + //For more information about adding MCP servers to Claude Code, see link:https://code.claude.com/docs/en/mcp[Claude Code Documentation, window=_blank]. + +== Integrate SpotterCode with Visual Studio Code + +Although you can configure the MCP server in Visual Studio Code, to start a chat session with the AI agent, you'll need GitHub Copilot or a similar extension. + +To add the SpotterCode MCP Server to Visual Studio Code, use the Extensions view or the `MCP: Add Server` command via the Command Palette. Alternatively, directly edit the `mcp.json` file in your workspace configuration. + +[source,JSON] +---- +{ + "servers": { + "SpotterCode": { + "url": "https://spottercode.thoughtspot.app/mcp", + "type": "http" + } + } +} +---- + +After you add the MCP server URL, the SpotterCode MCP server is available in the Extensions view. For more information about configuring MCP servers in Visual Studio Code, refer to link:https://code.visualstudio.com/docs/copilot/customization/mcp-servers[Visual Studio Code Documentation, window=_blank]. + == Verify the integration To verify the integration: @@ -135,7 +144,7 @@ If the integration is successful, you'll see SpotterCode in the MCP servers list . Verify the available SpotterCode skills. + -For example, Cursor shows the MCP skills of MCP connectors in the **Tools & MCP** page. Check if the xref:spottercode.adoc#_supported_skills[SpotterCode MCP skills] are listed under SpotterCode. As you hover over each skill, you can view the description and input schema used for agentic interactions. You can also disable the MCP skills that you don't want the AI model to use. +For example, Cursor shows the skills of MCP connectors in the **Tools and MCP** page. Check if the xref:spottercode.adoc#_supported_skills[SpotterCode MCP skills] appear under SpotterCode. As you hover over each skill, you can view the description and input schema used for agentic interactions. You can also disable the MCP skills that you don't want the AI model to use. + [div videoContainer] @@ -152,7 +161,7 @@ In the following example, a chat session with Cursor AI is initiated with the pr video::./images/cursor-chat-session.mp4[width=100%,options="autoplay,loop"] -- -. Verify that the AI Agent is able to discover SpotterCode skills and is using these skills to generate a response. +. Verify that the AI agent is able to discover SpotterCode skills and is using these skills to generate a response. . Review the response returned for your prompt and verify the results. + The following example shows how Cursor AI scaffolds the embed code using the SpotterCode skills. Notice that the AI agent identifies and lists the minimum configuration settings, such as the ThoughtSpot host URL, Liveboard ID, and authentication attributes, required to complete the embedding. diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 8757ec3b8..b971e964a 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -379,7 +379,7 @@ When set to `true`, exports the guid of the object. This flag will work only whe * `include_obj_id` + When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. * `export_with_associated_feedbacks` + -When set to `true`, exports the the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object +When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object * `export_column_security_rules` [beta betaBackground]^Beta^ + When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. * `export_with_column_aliases` [beta betaBackground]^Beta^ + @@ -426,7 +426,7 @@ For example, `"guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: L . Paste the YAML output copied from the export TML API response into a text editor. . Remove the quotation marks, update the TML, and ensure that the YAML is properly formatted: + `guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n` -. When +++importing TML in the Playground+++, do not paste the YAML directly into the `metadata_tmls` input field. Instead, use the JSON editor to add the the YAML. +. When +++importing TML in the Playground+++, do not paste the YAML directly into the `metadata_tmls` input field. Instead, use the JSON editor to add the YAML. . To open the JSON editor, click *View JSON*. + In the JSON preview, you'll see the following code: + diff --git a/modules/ROOT/pages/trusted-auth-secret-key.adoc b/modules/ROOT/pages/trusted-auth-secret-key.adoc index 9071fc5e8..526c981e6 100644 --- a/modules/ROOT/pages/trusted-auth-secret-key.adoc +++ b/modules/ROOT/pages/trusted-auth-secret-key.adoc @@ -6,7 +6,8 @@ :page-pageid: trusted-auth-secret-key :page-description: You can configure support for token-based authentication service on ThoughtSpot. -== secret key overview +[#secret-key-overview] +== Secret key overview The `secret_key` allows calling the ThoughtSpot *token request* REST APIs to generate a token for *any user*. Requests with the `secret_key` do not require any type of user login or admin permissions and the `secret_key` is equivalent to an admin-level login for the token request REST APIs. @@ -44,6 +45,9 @@ This key is required for making API calls to get a token for ThoughtSpot users. . Store the key in a secure location. . Click *Save Changes*. +[NOTE] +To enable Trusted authentication programmatically, send a `POST` request to the `POST /api/rest/2.0/auth/configure` endpoint. For more information, see xref:authentication.adoc[Configuring authentication settings]. + == Request a new secret key Requesting a new `secret_key` simply involves disabling and re-enabling trusted authentication. diff --git a/modules/ROOT/pages/trusted-auth-token-request-service.adoc b/modules/ROOT/pages/trusted-auth-token-request-service.adoc index cb21b86e9..c140294d5 100644 --- a/modules/ROOT/pages/trusted-auth-token-request-service.adoc +++ b/modules/ROOT/pages/trusted-auth-token-request-service.adoc @@ -161,7 +161,7 @@ V1 tokens stay valid for a length of time based on the following rules: To set a consistent five-minute expiration time, you can generate a second token to start the expiration clock for the previous login token that is sent to the user's browser. == Revoking a token -There is a xref:authentication.adoc#revoke-a-token[REST API for revoking a V2 Token], which could be incorporated into an additional endpoint of the *token request service* if you have concerns about the longer-lived tokens existing beyond the web application's session lifespan. +There is a xref:authentication.adoc#_revoking_a_token[REST API for revoking a V2 Token], which could be incorporated into an additional endpoint of the *token request service* if you have concerns about the longer-lived tokens existing beyond the web application's session lifespan. For example, the sign-out process of the web application could call the *token request service* to revoke the previously requested token. diff --git a/modules/ROOT/pages/trusted-authentication.adoc b/modules/ROOT/pages/trusted-authentication.adoc index a3c6fbf29..8d1082c00 100644 --- a/modules/ROOT/pages/trusted-authentication.adoc +++ b/modules/ROOT/pages/trusted-authentication.adoc @@ -36,7 +36,7 @@ If you are embedding ThoughtSpot content in an app that is not in the same domai See the xref:trusted-auth-sdk.adoc[Visual Embed SDK documentation] for the exact details of implementing either form of trusted authentication. == How to turn off trusted authentication -xref:trusted-auth-secret-key.adoc#disable-trusted-authentication[Disabling trusted authentication] also invalidates the previous `secret_key`. +xref:trusted-auth-secret-key.adoc#_disable_trusted_authentication[Disabling trusted authentication] also invalidates the previous `secret_key`. == Troubleshoot trusted authentication Please see the xref:trusted-auth-troubleshoot.adoc[troubleshooting steps] if you encounter issues with the browser-side aspects of the trusted authentication implementation. diff --git a/modules/ROOT/pages/tse-eco-mode.adoc b/modules/ROOT/pages/tse-eco-mode.adoc index d27b81593..5b5fc8b2c 100644 --- a/modules/ROOT/pages/tse-eco-mode.adoc +++ b/modules/ROOT/pages/tse-eco-mode.adoc @@ -126,7 +126,7 @@ https://{cluster-name}.thoughtspotstaging.cloud/?tse=true&start_cluster=true https://{cluster-name}.thoughtspotdev.cloud/?tse=true&start_cluster=true ---- -In the request header, you must include the `security-key`. This `security-key` is used to authenticate your request when xref:trusted-authentication.adoc#trusted-auth-enable[trusted authentication is enabled]. ThoughtSpot Embedded users can obtain the `security key` for their instance or Org context from their ThoughtSpot administrator. +In the request header, you must include the `security-key`. This `security-key` is used to authenticate your request when xref:trusted-auth-secret-key.adoc#trusted-auth-enable[trusted authentication is enabled]. ThoughtSpot Embedded users can obtain the `security key` for their instance or Org context from their ThoughtSpot administrator. If your instance has Orgs: diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index a5d4ce38b..f58cb6dd6 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -8,6 +8,7 @@ Variables allow you to substitute values for specific properties of a metadata object and enable dynamic data propagation across Orgs in ThoughtSpot. Using variables, you can parameterize the properties of data connections, table references, and formulas per Org without changing the underlying data or creating duplicate objects. Variable values are assigned at runtime to ensure that customized configuration is available to users of different Orgs in ThoughtSpot. + == Overview ThoughtSpot provides predefined system variables such as `ts_username` and `ts_groups`, which can be used in formulas for data security. Additionally, you can configure variables programmatically via REST APIs, and later use these variables for the following purposes: diff --git a/modules/ROOT/pages/version_control.adoc b/modules/ROOT/pages/version_control.adoc index 12963a93f..b5d8af618 100644 --- a/modules/ROOT/pages/version_control.adoc +++ b/modules/ROOT/pages/version_control.adoc @@ -47,7 +47,7 @@ ThoughtSpot’s Git integration does not support moving objects within the same ==== == Moving TML changes between environments -Each environment is a linked pair of a ThoughtSpot Org and a Git branch that can only export (xref:git-rest-api-guide.adoc#commit-files[commit]) or import (xref:git-rest-api-guide.adoc#deploy-commits[deploy commits]). +Each environment is a linked pair of a ThoughtSpot Org and a Git branch that can only export (xref:git-rest-api-guide.adoc#_commit_files[commit]) or import (xref:git-rest-api-guide.adoc#_deploy_commits[deploy commits]). The standard workflow is: @@ -85,12 +85,12 @@ The deploy REST API has a xref:guid-mapping.adoc[*GUID Mapping*] feature to subs All TML in all Git branches maintain the same GUIDs and other properties as the *dev branch*, while the deploy commits REST API does all necessary substitutions in the TML files prior to the final TML import action. === Validate merge before deploying -Both the xref:git-rest-api-guide.adoc#deploy-commits[deploy] and the xref:git-rest-api-guide.adoc#validate-merge[validate merge] APIs can be used in modes that check for errors before doing merge and deploy actions. +Both the xref:git-rest-api-guide.adoc#_deploy_commits[deploy] and the xref:git-rest-api-guide.adoc#_validate_merge[validate merge] APIs can be used in modes that check for errors before doing merge and deploy actions. === Sharing imported content with users and groups On the first deployment into a given Org, the objects that are newly created will not be *shared* with any users or groups. -The xref:access-control-sharing#_sharing_via_rest_api[REST API for sharing objects] can be called on the newly created objects. All of the GUIDs of the objects will be stored in the xref:guid-mapping.adoc[GUID Mapping files]. +The xref:access-control-sharing.adoc#_sharing_via_rest_api[REST API for sharing objects] can be called on the newly created objects. All of the GUIDs of the objects will be stored in the xref:guid-mapping.adoc[GUID Mapping files]. Standard content in "prod" Orgs should only ever be shared as *READ-ONLY*. diff --git a/modules/ROOT/pages/viz-overrides.adoc b/modules/ROOT/pages/viz-overrides.adoc new file mode 100644 index 000000000..1edf94fd3 --- /dev/null +++ b/modules/ROOT/pages/viz-overrides.adoc @@ -0,0 +1,468 @@ += Configuring visualization overrides +:toc: left +:toclevels: 3 + +:page-title: VisualizationOverrides +:page-pageid: visualization-overrides +:page-description: Visualization overrides to customize chart and table rendering in embedded ThoughtSpot experience. + +The Visual Embed SDK allows you to apply visual styling overrides programmatically to the charts and tables generated from Search data queries in an embedded app. + +== Overview +The visualization overrides feature allows developers to pre-define the chart and table settings for their embedding application users and apply these overrides at load time. This eliminates the need for embedding application users to manually adjust charts and tables in the edit mode. + +Using the `visualOverrides` object, embed application developers can preset the following properties in the new answers retrieved from a search data query: + +* Chart properties, such as the legend position, data labels, axis ranges, column colors, conditional formatting, and grid lines +* Table properties, including column visibility, text wrap, content density, and summary configuration + +== Configuring visual overrides + +The `visualOverrides` object in the `VisualizationOverrides` interface lets you apply styling overrides to charts and tables generated in the embedded ThoughtSpot Search interface. These overrides can be categorized as: + +* Visualization-level overrides that affect settings such as legend visibility, data labels, axis ranges, colors, gridlines, and conditional formatting on a chart. +* Column-level overrides applied such as number formatting, headline visibility, and sort order in a table. + +Within `visualOverrides`, the chart and table settings can be applied in the `chart` and `table` objects. + +=== Chart override settings + +For chart overrides, use the top-level `chart` object and configure the following properties as needed: + +[cols="2,5a"] +|=== +|Property | Description + +|`legend` __Optional__ +|Object properties for setting visibility, position, and color palette of a legend. + +|`show` __Optional__ +|__Boolean__. Shows or hides the chart legend. + +|`position` __Optional__ +|__String__. Position of the legend relative to the chart. Valid values include: + +* `LegendPosition.Top` to position the legend at the top of the chart. + +* `LegendPosition.Bottom` to position the legend at the bottom of the chart. + +* `LegendPosition.Left` to position the legend at the left of the chart. + +* `LegendPosition.Right` to position the legend at the right of the chart. + +|`colorPalette` __Optional__ +|Custom color palette properties for the legend. Overrides the default color sequence applied by ThoughtSpot. To customize color, specify the hex code in the `color` parameter. + +.5+|`dataLabel` __Optional__ +a|Data label visibility settings, including per-column label filters. + +a|`allLabels` + +__Boolean__. When `true`, shows data labels on all data points across all series. + +a| `stackLabels` + +__Boolean__. When `true`, shows cumulative total labels on stacked chart segments. + +a| `columnDataLabel` + +__Boolean__. Per-column data label visibility and filter threshold settings. For column data labels, you can define the following properties: + + +* `name`: __String__. Required parameter. Column name to apply the data label configuration to. + +* `visible`: __Boolean__. Optional parameter. Shows or hides data labels for this column. + +* `filter`: Optional parameter. Sets a filter threshold. When set, the labels are displayed only for data points that meet the filter condition. Define the following attributes to set a filter: + +a|For `filter`, include the following attributes: + + +* `value`: __Integer__. Threshold value for the filter comparison. + +* `operator`: __String__. Comparison operator for the threshold filter. Valid values for this attribute are: +** `DataLabelFilterOperator.GreaterThan` - Shows the label when value > threshold. + +** `DataLabelFilterOperator.LessThan` - Shows the label when value < threshold. + +** `DataLabelFilterOperator.GreaterThanOrEqualTo` - Shows the label when value ≥ threshold. + +** `DataLabelFilterOperator.LessThanOrEqualTo` - Shows the label when value ≤ threshold. + +** `DataLabelFilterOperator.EqualTo` - Shows the label when value = threshold. + +** `DataLabelFilterOperator.NotEqualTo` - Shows the label when value is not equal to the threshold. + +.4+|`display` __Optional__ +|Object for chart display settings. +a|`summaries` + +Row and column totals and grand totals. Applies to cross-tab (pivot) charts. Enable or disable the following settings as needed: + +* `showRowTotals`: __Boolean__. Shows a totals cell at the end of each row. +* `showColumnTotals`: __Boolean__. Shows a totals cell at the bottom of each column. +* `showRowGrandTotals`: __Boolean__. Shows a grand total row summarizing all rows. +* `showColumnGrandTotals`: __Boolean__. Shows a grand total column summarizing all columns. + +|`regressionLine` + +__Boolean__. When `true`, overlays a statistical regression (trend) line on the chart. + +a|`gridLine` + +__Optional__. Shows or hides grid lines on the chart. Specify the following attributes: + +* `x`: __Boolean__. When `true`, shows vertical grid lines along the x-axis. +* `y`: __Boolean__. When `true`, shows horizontal grid lines along the y-axis. + +.5+|`axis` __Optional__. a|Per-axis configurations. Each entry controls one axis group, identified by its linked columns. + +| `linkedColumns` + +__Array of strings__. Column names bound to this axis configuration. +| `showName` + +__Boolean__. Shows or hides the axis name label. +| `showLabelValue` + +__Boolean__. Shows or hides the value labels along the axis. +a| `yAxisRange` + +Sets the y-axis range to a specific minimum and maximum value. Use to enforce a consistent scale across embed instances. Valid values include: + +* `min`: __Integer__. Minimum value of the y-axis domain. +* `max`: __Integer__. Maximum value of the y-axis domain. + +.4+|`columns` +a|Per-column overrides: series color and conditional formatting rules. Include the following attributes: + +| `name` + +__String__. Column name to apply overrides to. + +| `color` + +__String__. Default series color for this column as a hex string. For example, `#1A73E8`. +a| `conditionalFormatting` + +Conditional formatting rules applied to data points in this column. Specify the following properties as needed. To apply conditional formatting, set an array of rules in the `rows` object. Each rule is evaluated independently; the first matching rule is applied. For more information, see xref:viz-overrides.adoc#_conditional_formatting_overrides[Conditional formatting overrides]. + +| `updateMaskPaths` | +__Array of strings__. Field mask for partial updates. Specifies which fields to apply when updating an existing visualization. Pass an empty array `[]` to apply all provided fields. +|| +|=== + +=== Table overrides +If the answers are in the table format, use the `table` object and define the following attributes: + +[cols="2,5a"] +|=== +|Property | Description +.3+| `columns` +a| Per-column overrides: visibility, text wrapping, and conditional formatting. +| `name` + +__String__. Column name to apply overrides to. +|`wrapText` + +__Boolean__. When `true`, wraps long cell content across multiple lines. When `false`, clips content to a single line. +| `show` + +__Boolean__. Show or hide the column in the table. +|`Conditional formatting` + +Conditional formatting rules applied to data points in this column. Specify the following properties as needed. To apply conditional formatting, set an array of rules in the `rows` object. Each rule is evaluated independently; the first matching rule is applied. For more information, see xref:viz-overrides.adoc#_conditional_formatting_overrides[Conditional formatting overrides]. + +3+| `display` +a|Table-level display settings: theme and content density. + +a|`tableTheme` + +__String__. Visual theme for the table. Controls row borders, alternating row colors, and cell styling. Valid values are: + +* `TableTheme.Outline` to render the table with outer border and column header borders only. + +* `TableTheme.Row` to render the table with horizontal row dividers. + +* `TableTheme.Zebra` to render the table with alternating row background colors. + +a|`tableContentDensity` + +__String__. Row height and padding density of the table. + +Accepted values: + +`TableContentDensity.Regular` for standard row height with default padding. + +`TableContentDensity.Compact` for reduced row height and padding; displays more rows in the same vertical space. + +.3+|`displaySummaryConfig` |Controls whether column summary rows (totals and aggregations) are shown, with per-column exceptions. + +|`showAllSummaries` |__Boolean__. When `true`, shows summary rows (totals and aggregations) for all columns. Individual columns can be excluded using `columnVisibility`. +|`columnVisibility` a|__Boolean__. Shows or hides the summaries for the specified string in the `columnId`. + + +* `visible`. __Boolean__. Shows or hides the summary for this column. +* `columnId`. __String__. Column ID to control summary visibility for. + +|| +|=== + +=== Conditional formatting overrides +The conditional formatting properties can be configured in both chart and table override settings in the `columns` object. + +[cols="2,5a"] +|=== +|Property | Description +.8+a| `conditionalFormatting` | +Conditional formatting rules applied to data points in this column. Specify the following properties as needed. To apply conditional formatting, set an array of rules in the `rows` object. Each rule is evaluated independently; the first matching rule is applied. + +a|`operator`. + +__String__. Required parameter. Comparison operator that triggers the formatting rule. Valid values are: + +* `ConditionalFormattingOperator.Is` to set the exact cell value. + +* `ConditionalFormattingOperator.IsNot` to exclude a cell value. + +* `ConditionalFormattingOperator.Contains` to set cell value to a specified string. + +* `ConditionalFormattingOperator.DoesNotContain` to set a cell value that does not contain the specified string. + +* `ConditionalFormattingOperator.StartsWith` to set a specific starting string for the cell value. + +* `ConditionalFormattingOperator.EndsWith` to set a cell value that ends with the specified string. + +* `ConditionalFormattingOperator.GreaterThan` to set a cell value greater than the specified value. + +* `ConditionalFormattingOperator.LessThan` to set a cell value that is less than the specified value. + +* `ConditionalFormattingOperator.GreaterThanEqualTo` to set a cell value that is greater than or equal to the specified value. + +* `ConditionalFormattingOperator.LessThanEqualTo` to set a cell value that is less than or equal to the specified value. + +* `ConditionalFormattingOperator.EqualTo` to set a cell value that is equal to the specified value. + +* `ConditionalFormattingOperator.NotEqualTo` to set a cell value that is not exactly equal to the specified value. + +* `ConditionalFormattingOperator.IsBetween` to set a cell value that is between the defined range of values. + +* `ConditionalFormattingOperator.IsNull` to set a null value. + +* `ConditionalFormattingOperator.IsNotNull` to set a value that is not null. + +a| `value` + +__String__. Literal value to compare against within a range of 0 to 1000000. Used when `comparisonType` is set as `ConditionalFormattingComparisonType.ValueBased` and the operator is set as `ConditionalFormattingOperator.IsBetween`. +a| `comparisonType` + +__String__. Determines what the `operator` compares against. Valid values are: + +* `ConditionalFormattingComparisonType.ValueBased` to compare the column value against a literal string in `value`. + +* `ConditionalFormattingComparisonType.ColumnBased` to compares the column value against another column specified in `columnToCompare`. + +* `columnToCompare`: __String__. Column name to compare against (right-hand side). Used when `comparisonType` is `ConditionalFormattingComparisonType.ColumnBased`. +* `ConditionalFormattingComparisonType.ParameterBased` to compare the column value against a ThoughtSpot parameter specified in `comparisonParameterId`. +* `comparisonParameterId`: __String__. Parameter ID to compare against. Used when `comparisonType` is `ConditionalFormattingComparisonType.ParameterBased`. + +| `plotAsBand` + +__Boolean__. When `true`, draws a reference band across the chart area instead of coloring individual data points. + +a| `isHighlightRow` + +__Boolean__. When `true`, applies the formatting to the entire table row instead of just the individual cell. + +a| `lhsColumnId` + +__String__. The column whose value is evaluated against the rule (left-hand side of the comparison). +a| `fontProperties` + +Text styling applied to the cell when the condition is met. Specify the following attributes: + +* `color`: __String__. Text color as a hex string. For example, `#ffffff`. +* `bold`: __Boolean__. When `true`, renders the text in bold. +* `italic`: __Boolean__. When `true`, renders the text in italic. +* `strikeThrough`: __Boolean__. When `true`, renders the text with a strikethrough. +* `underline`: __Boolean__. When `true`, renders the text with an underline. +* `backgroundFormatType`: __String__. Type of background fill to apply when the condition is met. Specify one of the following attributes: +** `BackgroundFormatType.Solid` to apply a flat solid fill color. Requires `solidBackgroundAttrs`. In the `solidBackgroundAttrs`, you can specify the fill color in the `color` attribute. +** `BackgroundFormatType.Gradient` to apply a gradient fill. Requires `gradientBackgroundAttrs`. In the `GradientBackgroundAttrs`: + +*** Specify an array of hex color strings defining the gradient stops in `colors`. +*** Specify the midpoint position of the gradient with a value range between 0 and 100. +*** Specify the numeric range values that map to the gradient color stops in `backgroundFormatRange`. +*** To scale the gradient range to the data minimum and maximum values, set `isAutoScaled` to `true`. +|| +|=== + +== Code sample +The following example shows the chart and table override settings for the new Answers generated from the embedded Search interface: + +[source,JavaScript] +---- +import { + init, // Core SDK initialization function. + AuthType, // for authentication type selection. + SearchEmbed, // Embeds the ThoughtSpot Search page into a host application. + ConditionalFormattingOperator, // Enum for conditional formatting comparison operators. + DataLabelFilterOperator, // Enum for data label filter operators. + ConditionalFormattingComparisonType, // Enum for conditional formatting comparison. + BackgroundFormatType, // Enum for the background fill type in conditional formatting rules. + TableTheme, // Enum for the visual theme of embedded tables. + TableContentDensity, // Enum for the row height and padding density of embedded tables. + LegendPosition, // Enum for the position of the chart legend. +} from "@thoughtspot/visual-embed-sdk"; + +init({ + thoughtSpotHost: '', // Replace with your application URL + authType: AuthType.None, +}); + +const embed = new SearchEmbed('#tsEmbed', { + frameParams: { + width: '100%', + height: '100%', + }, + dataSource: "", // Replace with your application URL + visualOverrides: { + chart: { + // Show or hide the chart legend, and set its position. + legend: { + show: true, + position: LegendPosition.Bottom, + }, + // Data labels to show on chart series. + dataLabel: { + // Show labels on all data points across all series. + allLabels: true, + // Show cumulative total labels on stacked chart segments. + stackLabels: true, + // Per-column label visibility and optional value filters. + // Use filters to suppress labels below or above a threshold. + columnDataLabel: [{ + name: 'Ship Mode', + visible: true, + // Only show the data label when the value is greater than 0 + filter: { + value: 0, + operator: DataLabelFilterOperator.GreaterThan + }, + }, + { + name: 'Discount', + // Hide data labels for this column entirely. + visible: false, + // No filter applied + filter: null, //label is hidden regardless of value. + }, + ], + }, + // chart display settings. + display: { + // Controls row/column summary rows on crosstab (pivot) charts. + summaries: { + showRowTotals: true, // Show totals at the end of each row. + showColumnTotals: false, // Hide totals at the bottom of each column. + showRowGrandTotals: true, // Show the grand total row. + showColumnGrandTotals: true, // Show the grand total column. + }, + // Show a statistical regression (trend) line on the chart. + regressionLine: true, + // Show or hide horizontal and vertical grid lines. + gridLine: { + x: true, // Show vertical grid lines (x-axis). + y: true, // Show horizontal grid lines (y-axis). + }, + }, + + // Each entry in this array configures one axis group. columns listed in "linkedColumns" share the same axis settings. + axis: [{ + // Columns bound to this axis configuration. + linkedColumns: ['Total Discount', 'Ship Mode'], + + // Show the axis name label. + showName: true, + + // Show tick mark value labels along the axis. + showLabelValue: true, + + // Fix the y-axis domain to a specific minimum/maximum range. + // Useful for enforcing a consistent scale across embed instances. + yAxisRange: { + min: 0, + max: 100, + }, + }, ], + // Per-column series color and conditional formatting rules. + columns: [{ + name: 'Total Discount', + // Default series color for this column (hex string). + color: '#ababab', + // Applies visual formatting rules to data points that meet the specified conditions. Each entry in rows[] is one rule. + conditionalFormatting: { + rows: [{ + // Trigger this rule when the cell value is greater than 3300. + operator: ConditionalFormattingOperator.GreaterThan, + value: '3300', + // When true, draws a reference band across the chart instead of coloring individual data points. + plotAsBand: true, + // Compare the column value against a literal value. + comparisonType: ConditionalFormattingComparisonType.ValueBased, + // The column whose value is evaluated against the rule. + lhsColumnId: 'Total Discount', + // Applied to cell text when the condition is met. + fontProperties: { + color: '#ffffff', // White text. + bold: true, + italic: false, + strikeThrough: false, + underline: false, + }, + // Use a solid fill color or a gradient fill. + backgroundFormatType: BackgroundFormatType.Solid, + solidBackgroundAttrs: { + color: '#2E75F0', // Blue background when condition is met. + }, + + // For gradient fill, set "BackgroundFormatType.Gradient". + // backgroundFormatType: BackgroundFormatType.Gradient, + // gradientBackgroundAttrs: { + // colors: ['#000000', '#ffffff'], + // }, + }, ], + }, + }, ], + + // Field mask for partial updates. An empty array applies all provided fields. + updateMaskPaths: [], + }, + table: { + // Per-column overrides for visibility, text wrapping, and conditional formatting. + columns: [{ + name: "Total Discount", // Column name + wrapText: true, // wrap long content across multiple lines + show: true, + // Conditional formatting rules to cells in this column. + conditionalFormatting: { + rows: [{ + // Trigger rule based on the cell value. Compares the column value against the literal string in `value`. + operator: ConditionalFormattingOperator.GreaterThan, + value: "3300", + // For value range-based matching condition, use `ConditionalFormattingOperator.IsBetween` and `rangeValues` + // operator: ConditionalFormattingOperator.IsBetween ('IS_BETWEEN'). + // rangeValues: { min: 0, max: 1000000 }, + // Apply formatting to the entire table row instead of just the individual cell. + isHighlightRow: false, + comparisonType: ConditionalFormattingComparisonType.ValueBased, + // The column whose value is evaluated against the rule (left-hand side). + lhsColumnId: "Total Discount", + // Text styling applied to the cell when the condition is met. + fontProperties: { + color: "#ffffff", // White text. + bold: true, + italic: false, + strikeThrough: false, + underline: false, + }, + + // Use solid or gradient fill color for background styling + backgroundFormatType: BackgroundFormatType.Solid, + solidBackgroundAttrs: { + color: "#2E75F0", //Solid fill color applied when the condition is met. + }, + }, ], + }, + }, + + // second column with no conditional formatting. + { + name: "Ship Mode", + wrapText: false, + show: true, + }, + ], + // Table-level display settings. + display: { + // Set the row height and padding density of the table. + tableContentDensity: TableContentDensity.Compact, // Use TableContentDensity.Regular for standard row height. + }, + displaySummaryConfig: { + // Show summary rows for all columns by default. + showAllSummaries: true, + // Per-column exceptions to showAllSummaries. + columnVisibility: [{ + columnId: "Total Discount", + visible: false + }, + { + columnId: "Total Extended Price", + visible: false + }, + ], + }, + + // Field mask for partial updates. An empty array applies all provided fields. + updateMaskPaths: [], + + }, + }, +}); + +embed.render(); +---- + +== Limitations + +* Visual overrides cannot be applied to the existing saved answers or an answer with a modified search query. The overrides apply only to the new answers generated from the Search data interface. +* Visual overrides are not supported in Liveboard and Spotter embedding. +* Visual overrides do not control which fields are placed on the x-axis, y-axis, or slice-by-color. They also do not control whether measures share a single axis or are placed on dual axes. +* Legend colors use a positional color palette and per-value mapping. Colors are applied in sequence to legend items in the order they appear in the chart. The overrides may not result in the exact legend item-to-color mapping by attribute value. +* Overrides cannot be modified via HostEvents. To change overrides after the component has rendered, create a new embed with the updated configuration. ThoughtSpot recommends testing the overrides on a development or test environment before applying them on production instances. +* Overrides do not create undo and redo history entries. Applying `visualOverrides` does not add entries to the answer's undo and redo history. Embedding application users cannot undo a visual override through the ThoughtSpot UI. +* Overrides do not trigger answer re-execution. Setting `visualOverrides` does not re-run the underlying query. Overrides are merged into the existing visualization configuration +after the answer is loaded, with no performance impact on query execution. + +== Additional references + +* xref:embed-search.adoc[Embed Search page] +* xref:full-embed.adoc[Embed full application] +* xref:SearchViewConfig.adoc[SearchViewConfig] +* xref:AppViewConfig.adoc[AppViewConfig] + diff --git a/modules/ROOT/pages/whats-new-prev-history.adoc b/modules/ROOT/pages/whats-new-prev-history.adoc index e2661ee2c..dfb3d083f 100644 --- a/modules/ROOT/pages/whats-new-prev-history.adoc +++ b/modules/ROOT/pages/whats-new-prev-history.adoc @@ -669,7 +669,7 @@ The Spotter feature is in beta and disabled by default on ThoughtSpot Embedded i ==== To generate a token with custom rules, attributes, and filter conditions for Attribute-Based Access Control (ABAC) [beta betaBackground]^Beta^, you can use the `/api/rest/2.0/auth/token/custom` API endpoint instead of the `user_parameters` property in `/api/rest/2.0/auth/token/full` and `/api/rest/2.0/auth/token/object` APIs. -For more information, see xref:authentication.adoc#_get_tokens_with_custom_rules_and_filter_conditions[Get tokens with custom rules and filter conditions]. +For more information, see xref:authentication.adoc#_generate_a_custom_token_for_abac_implementation[Get tokens with custom rules and filter conditions]. ==== .Visual Embed Playground enhancements @@ -1184,8 +1184,6 @@ For more information, see xref:version_control.adoc[Git integration and version ==== The Visual Embed SDK provides a new JavaScript library to embed the Search page with AI-powered features such as natural language search and AI-suggested answers. To view the AI-suggested answers, make sure the AI search support is enabled on the data source or worksheet used for searching data. -//ThoughtSpot does not display AI-suggested search responses if the xref:search-assist-tse.adoc[Search Assist] feature is enabled. - For more information, see xref:SageEmbed.adoc[SageEmbed SDK reference]. ==== @@ -1316,7 +1314,7 @@ ThoughtSpot now supports generating secret keys per Org. Org administrators can Starting from 9.2.0.cl, Org users require Org-specific authentication tokens issued for their user accounts when switching between Orgs. When generating an authentication token via REST API, make sure to request separate tokens for each Org context. -For more information, see xref:trusted-authentication.adoc#trusted-auth-enable[Trusted authentication]. +For more information, see xref:trusted-auth-secret-key.adoc#trusted-auth-enable[Trusted authentication]. ==== .Custom styles @@ -1704,8 +1702,6 @@ For information about REST API enhancements, see xref:rest-apiv1-changelog.adoc[ [%collapsible] ==== Your application users can now access sample search walkthrough lessons created using Search Assist on embedded ThoughtSpot instances. If the Search Assist feature is enabled in the SDK, and the Search Assist lessons are created on the Worksheet, users can view sample search questions and follow the actions in the walkthrough to get answers. - -//For more information, see xref:search-assist-tse.adoc[Enable Search Assist, window=_blank]. ==== .Visual Embed SDK 1.13.0 @@ -1830,7 +1826,6 @@ ThoughtSpot introduces app actions[beta betaBackground]^Beta^ to support seamles Users with developer or admin privileges can create an app action for Slack[beta betaBackground]^Beta^ in the Developer portal and add it as a menu action on visualizations and saved answers. On clicking this action, ThoughtSpot users can initiate the Slack integration workflow and send data to their Slack channels without leaving the ThoughtSpot UI. -For more information, see xref:app-actions.adoc[App actions] and xref:push-data-to-slack.adoc[Push data to a Slack workspace]. |==== //// @@ -1860,7 +1855,7 @@ The REST API v2 [beta betaBackground]^Beta^ endpoint URL path is changed from `/ Trusted authentication:: If trusted authentication is enabled on your instance, you can now obtain a login token to authenticate to ThoughtSpot and authorize your API requests. -For more information, see xref:authentication.adoc#trustedAuthToken[REST API v2 authentication]. +For more information, see xref:authentication.adoc[REST API v2 authentication]. SDK for .NET clients:: ThoughtSpot provides the .NET SDK to allow developers to interact with REST APIs from .NET applications. You can download the SDK from NuGet Package Manager and install it using the NuGet GUI. For more information, see xref:rest-api-sdk-libraries.adoc[REST API SDK and client libraries]. @@ -1961,7 +1956,7 @@ If you have embedded the full ThoughtSpot application, you will notice that the The SDK supports the `OIDC` `authType` in `init` calls. If you want your application users to authenticate to an OpenID provider and use their SSO credentials to access the embedded ThoughtSpot content, you can enable the `OIDC` authentication type in the SDK. -For more information, see xref:embed-authentication#oidc-auth.adoc[Authentication and security attributes]. +For more information, see xref:embed-authentication.adoc#oidc-auth[Authentication and security attributes]. |[tag greenBackground]#NEW FEATURE# a|+++
Embed events
+++ The SDK includes the following new event: @@ -2495,15 +2490,15 @@ Use this API to remove an object from a user's favorites list. For more informat * `POST /tspublic/v1/session/homepinboard` + -Use this API to set a pinboard as the home pinboard for a user account. For more information, see xref:session-api.adoc#set-home-pinboard[Set a pinboard as a home pinboard]. +Use this API to set a pinboard as the home pinboard for a user account. For more information, see xref:session-api.adoc#set-home-liveboard[Set a pinboard as a home pinboard]. * `GET /tspublic/v1/session/homepinboard` + -Use this API to get the GUID of the pinboard set as a home pinboard. For more information, see xref:session-api.adoc#get-home-pinboard[Get details of the home pinboard]. +Use this API to get the GUID of the pinboard set as a home pinboard. For more information, see xref:session-api.adoc#get-home-liveboard[Get details of the home pinboard]. * `DELETE /tspublic/v1/session/homepinboard` + -Use this API to remove the home pinboard. For more information, see xref:session-api.adoc#del-home-pinboard[Remove a home pinboard]. +Use this API to remove the home pinboard. For more information, see xref:session-api.adoc#del-home-liveboard[Remove a home pinboard]. .Other API enhancements diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index b8859cbbf..6320f0913 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -1,4 +1,4 @@ -= What’s new += What's new :toc: true :toclevels: 1 @@ -23,6 +23,70 @@ This page lists new features, enhancements, and deprecated functionality introdu // *Affects:* Developers, Administrators, End Users // ============================================================ +== June 2026 + +**Release version**: ThoughtSpot Cloud 26.6.0.cl + +*Upgrade notes*: No breaking changes. + +*Recommended SDK versions*: Visual Embed SDK v1.49.0 and later + +[.cl-table, cols="2,4", frame=none, grid=none] +|===== +a| +[.cl-label] +*Version 26.6.0.cl* + +a| +[discrete] +==== Chart and table overrides [.version-badge.new]#New# +You can now apply visualization overrides to charts and tables generated from a search query in ThoughtSpot search and full application embedding. The `visualOverrides` property in `SearchViewConfig` and `AppViewConfig` allows developers to apply at the embed initialization time: + +* Chart overrides + +Control legend visibility and position, data label display and per-column filter +thresholds, regression lines, grid lines, axis range and label settings, series +colors, and conditional formatting rules including font and background styling. +* Table overrides + +Control column visibility, text wrapping, row height and padding density, table +theme, and column summary visibility with per-column exceptions. + +For more information, see xref:viz-overrides.adoc[Configuring visualization overrides]. + +--- + +[discrete] +==== Spotter AI and embedding enhancements [.version-badge.new]#New# + +This release introduces the following enhancements for Spotter AI workflows and embedded Spotter applications. + +* Spotter embedding: + +Spotter now includes data literacy skills that help users understand the underlying data model. Users can ask Spotter to explain available data sources, fields, and relationships in plain language within a conversation session. +* Spotter AI APIs: + +** New REST API endpoints to configure and retrieve persistent behavioral xref:spotter-agent-instructions.adoc[instructions for the Spotter agent]. +** New API endpoint xref:spotter-agent-apis.adoc#_stop_an_in_progress_agent_response[stop and cancel a long-running Spotter response]. + +--- + +[discrete] +==== Developer page enhancements +The **Develop** page in the ThoughtSpot UI has been updated with the following enhancements: + +* The **Custom actions** list page now shows the code-based custom actions configured using the Visual Embed SDK. +* Removal of REST API v1 + +The legacy REST Playground v1 has been removed from the left navigation. This change does not affect your current integrations with v1 REST API. ThoughtSpot recommends that you update your integration workflows to use REST API v2. For more information, see xref:rest-api-v1v2-comparison.adoc[REST API v1 to v2 migration]. +* Removal of GraphQL playgrounds + +The menu link to the GraphQL playground has been removed from the UI. + +[discrete] +==== Visual Embed SDK +The Visual Embed SDK version 1.49.0 includes several new features and enhancements. For more information, see the xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] +==== REST API v2 +This release introduces new API endpoints for Spotter, connections and trusted authentication. For information about REST API v2 enhancements, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + +|===== + == May 2026 @@ -39,6 +103,7 @@ a| a| + [discrete] ==== Liveboard downloads @@ -46,7 +111,7 @@ Continuous Liveboard PDF export [beta betaBackground]^Beta^:: In PDF downloads, Liveboard tabs can now be rendered in a single page matching the UI layout. This feature can be enabled by setting `isContinuousLiveboardPDFEnabled` to `true` in the SDK. Setting this flag to `false` returns to the paginated PDF view. Liveboard download in XLSX and CSV formats:: -Embedded Liveboards can now be downloaded in the PDF, XLlX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. +Embedded Liveboards can now be downloaded in the PDF, XLSX and CSV file formats. To enable this feature, ensure that the `isLiveboardXLSXCSVDownloadEnabled` parameter is set to `true`. Excel exports for pivot tables:: Pivot table visualizations can now be exported to Excel format. @@ -483,6 +548,10 @@ The SDKs for embedding ThoughtSpot components in mobile apps are now Generally A [discrete] ==== Visual Embed SDK For information about the new features and enhancements introduced in Visual Embed SDK version 1.44.0, see xref:api-changelog.adoc[Visual Embed changelog]. + +--- + +[discrete] ==== Custom calendar APIs --- diff --git a/modules/_templates/best-practices.adoc b/modules/_templates/best-practices.adoc new file mode 100644 index 000000000..7da28b8a7 --- /dev/null +++ b/modules/_templates/best-practices.adoc @@ -0,0 +1,80 @@ += "> +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1 or 2 levels. Adjust toclevels as needed. + +:page-title: +:page-description: <Description of what this page covers and who it is for.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "spotter-embed-best-practices"> +:keywords: <comma-separated terms. For example, "configure auth", "SSO", "SAML"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +// 1-2 sentences: what this page covers, who it is for, and what +// following these practices helps them achieve. + +== Overview + +// Optional. Provide context for why these practices matter +// what problems they prevent or what outcomes they enable. +// Keep to 2-3 sentences. Link to concept pages for deeper background. + +== Recommended practices +// Include a list of the best practices, dos and don'ts. + +// * <Do not set the token expiration key to ...> +// * <Ensure the API token is saved in a secure place.> + +// If a best practice or recommendation requires its own section, use the format in the following sections. + +=== <Practice title: short imperative phrase, "Refresh API keys periodically"> + +// Lead with the recommendation as a direct statement: +// "Refresh your API keys every 90 days." +// +// Then explain: +// - Why: the risk or benefit this practice addresses +// - How: the steps or configuration required +// - When: any conditions or exceptions that apply + +// TODO: verify recommendation with engineering + +[source,bash] +---- +# Example command or configuration snippet if applicable +---- + +// NOTE: <Optional note that helps the reader apply this practice more effectively.> + +=== <Practice title> + +// Lead with the recommendation. +// Explain why, how, and when. + +== What to avoid + +// Optional but adds value. Describe common mistakes or patterns. +// Use WARNING admonitions for practices that risk data loss or security issues. + +// WARNING: <Describe a practice that risks data loss, security exposure, or system instability. State the consequence clearly.> + +// Alternative: use a simple list for lower-severity anti-patterns. + +// Optional but high value. Describe common mistakes, patterns, dos and don'ts. For example: + +// * <Do not set the token expiration key to less than 10 minutes>, <state the reason/impact and preferred alternative>. +// * <Do not ....> <state the reason/impact and preferred alternative>. + +// Use admonitions to highlight important information. + +//// +[WARNING] +==== +<Describe a practice that risks data loss, security exposure, or system instability. State the consequence clearly.> +==== +//// + +== Additional resources + +//* xref:<file-name>.adoc[Link text]. Add additional info or subtext if required. diff --git a/modules/_templates/concept.adoc b/modules/_templates/concept.adoc new file mode 100644 index 000000000..7ba704386 --- /dev/null +++ b/modules/_templates/concept.adoc @@ -0,0 +1,129 @@ += <Title: Noun phrase describing the concept> +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1 or 2 levels. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-description: <Description of what this page covers and who it is for.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "spotter-embed-overview"> +:keywords: <comma-separated terms. For example, "authentication, SSO, SAML, login"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/concept.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "embed-sso-overview.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for pages that explain WHAT something is or HOW it works. +Do NOT include step-by-step instructions here — link to a procedure page instead. + +Section labels: + REQUIRED — must be present on every page of this type + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to the topic + +Style elements you can use: +//// + + +Admonitions: [NOTE], [TIP], [IMPORTANT], [WARNING], [CAUTION] +Inline badge : [beta betaBackground]^Beta^, [earlyAccess eaBackground]#Early Access# +Version badge: [.version-badge.new]#New#, [.version-badge.deprecated]#Deprecated# [.version-badge.breaking]#Breaking#, [.version-badge.fixed]#Fixed# +Images: image::./images/<image-file>[alt text] + +Tables: +[cols="...", options="header"] +|=== +|... +|=== + +Code blocks: +[source,JavaScript] +---- +<code> +---- + +//// + +// REQUIRED: a lead sentence for the article with 1-2 sentences. For example, explain what the feature is and why it matters to users. + +== Overview + +// Intro block with an overview of the feature. + +== How it works + +// REQUIRED. +// Explain the concept clearly. Avoid procedure steps. Link to procedure pages instead. +// Use plain language; define acronyms on first use. +// +// Add a diagram or screenshot if spatial relationships or architecture matter: +// Use the following format for images: +// image::./images/<diagram-filename>.png[Alt text describing the diagram] +// For example, image::./images/mcp-architecture.png[ThoughtSpot MCP Server architecture] +// +// Use admonitions to highlight key information: + +// [NOTE] +// ==== +// Text for a general note or clarification. +// ==== +// +// [IMPORTANT] +// ==== +// Text for a critical constraint the reader must know before using this feature. +// ==== + +== Key components + +// OPTIONAL. +// Use a definition list for named parts or actors in the system: + +Component A:: +Description of what it does and its role in the system. + +Component B:: +Description of what it does. + +// OPTIONAL: Add a comparison matrix when the concept involves multiple options or variants +// that readers commonly need to choose between: +// +// [cols="1,1,1,1", options="header"] +// |=== +// |Option |Best for |Authentication |Notes +// |REST API v2 |New integrations |Bearer token |Recommended +// |REST API v1 |Legacy systems |Basic auth |Migrate to v2 when possible +// |Visual Embed SDK |Embedded UI |Trusted auth |TypeScript support +// |=== + +== Limitations and constraints + +// RECOMMENDED. +// List known limitations, version-specific behavior, or edge cases the reader should know. +* <Known limitation or constraint.> + +// Use admonitions for critical constraints: +// +// [IMPORTANT] +// ==== +// This feature requires ThoughtSpot Cloud <version> or later. +// ==== +// +// [WARNING] +// ==== +// Enabling this setting affects all users in the org. Confirm with your administrator before proceeding. +// ==== + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. Add additional info or subtext if required. +//* link:<URL>[Link text, window=_blank]. Add additional info or subtext if required. diff --git a/modules/_templates/faqs.adoc b/modules/_templates/faqs.adoc new file mode 100644 index 000000000..b6a229953 --- /dev/null +++ b/modules/_templates/faqs.adoc @@ -0,0 +1,64 @@ += <Title: "Frequently Asked Questions" or "FAQs"> +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1 or 2 levels. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-description: <One sentence: what this page covers and why it matters to the reader.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "embed-faqs"> +:keywords: <comma-separated terms. For example, "authentication", "SSO", "SAML", "IdP", "login"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +// 1-2 sentences: what topic area these FAQs cover and who they are for. +// Note: write each question as users would ask it — this improves +// both findability and GEO citation rates. + +== <Information category. For example, Embed authentication> + +=== <Question written as a user would ask it, for example, "What authentication methods are supported?"> + +// Answer directly in the first sentence. Provide detail after. +// If the answer requires steps, use a numbered list. +// If the answer links to a full page, link to it and summarize here. + +=== <Question> + +// Answer. + +== <Topic group, for example, "Identity and access management"> + +=== <Question> + +// Answer. + +=== <Question> + +// Answer. + +== <Topic group, for example, "OIDC configuration"> + +=== <Question> + +// Answer. + +=== <Question> + +// Answer. + + +== <Information category. For example, trusted authentication> + +=== <Question> + +// Answer. + + + +== Related information + +// Optional. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. Add additional info or subtext if required. +//* link:<URL>[Link text, window=_blank]. Add additional info or subtext if required. diff --git a/modules/_templates/procedure.adoc b/modules/_templates/procedure.adoc new file mode 100644 index 000000000..24dbf0ebc --- /dev/null +++ b/modules/_templates/procedure.adoc @@ -0,0 +1,137 @@ += <Title: Verb + object. For example, "Configuring Single Sign-On"> +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1 or 2 levels. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-description: <One sentence: what this procedure does and who it is for.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page, for example, "embed-sdk-concepts".> +:page-type: procedure +:keywords: <comma-separated terms. For example, "SSO", "SAML", "authentication setup"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/procedure.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "configure-saml-sso.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for pages that describe HOW TO DO something — a sequence of steps +the reader must follow to achieve a specific outcome. +Do NOT explain background theory here — link to a concept page for that. + +Section labels: + REQUIRED — must be present on every page of this type + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to the topic + +Code samples: + SDK procedures : JavaScript or TypeScript code sample is REQUIRED. + REST API procedures: cURL code sample is REQUIRED. JSON request/response is REQUIRED. + UI-only procedures : screenshots are RECOMMENDED (use image:: after the relevant step). + +Style elements you can use: +Admonitions: [NOTE], [TIP], [IMPORTANT], [WARNING], [CAUTION] +Inline badge : [beta betaBackground]^Beta^, [earlyAccess eaBackground]#Early Access# +Version badge: [.version-badge.new]#New#, [.version-badge.deprecated]#Deprecated#, [.version-badge.breaking]#Breaking#, [.version-badge.fixed]#Fixed# +Images: image::./images/<image-file>[alt text] + +Tables: +[cols="...", options="header"] +|=== +|... +|=== + +Code blocks: +[source,JavaScript] +---- +<code> +---- +============== +//// + +== Overview + +// REQUIRED: 1-2 sentences — what this procedure accomplishes and who it is for. +// Mention the product area and the intended audience (developer, administrator, etc.). + +// OPTIONAL: Add a workflow diagram or screenshot of the starting state if required. + + +== Before you begin + +// REQUIRED if there are prerequisites. Use "You must" or "You need" for each item. +// Remove this section only if there are genuinely no prerequisites. + +* You must have <role or group privilege> to <perform the intended action>. +* You need access to <system or resource. For example "a ThoughtSpot Cloud instance with the Embed feature enabled">. +* <Any additional prerequisite>. + +== <Procedure. Use gerund or action verbs. For example, Configuring variables> + +// REQUIRED. Use numbered steps. Each step must describe exactly one action. +// Include the exact command, UI label, menu path, or code for each step. +// Add a `+` continuation after a step to attach a code block or image to it. + +. Step one. Describe the exact UI action or navigation path. ++ +// OPTIONAL: Screenshot showing the UI state after this step: +// image::./images/<step1-screenshot>.png[Description of what to see after step 1] +// For SDK procedures, a code sample is REQUIRED. Use the following format for code samples: + +[source,JavaScript] +---- +<code sample> +---- + +// For REST API procedures, document the required parameters and provide request and response examples. + +[source,cURL] +---- +curl -X POST \ + 'https://<your-instance>.thoughtspot.cloud/api/rest/2.0/<endpoint>' \ + -H 'Authorization: Bearer <token>' \ + -H 'Content-Type: application/json' \ + -d '{ + "param": "value" + }' +---- + +// OPTIONAL: Show the expected JSON response inline: +// [source,JSON] +// ---- +// { +// "field": "value" +// } +// ---- + +// OPTIONAL: Add a WARNING or NOTE for common pitfalls at the end of the procedure. +// [WARNING] +// ==== +// If you see <error>, verify that <condition> before retrying. +// ==== + +== Result + +// REQUIRED. Describe what the user should see or be able to do after completing the procedure. +// Be specific. Specify the name of the UI element, API response, or behavior that confirms success. +// OPTIONAL: Screenshot of the expected result: + +== Next steps + +// OPTIONAL. Link to the next logical task or a related procedure. +// * xref:next-procedure.adoc[Next task name] + + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. Add additional info or subtext if required. +//* link:<URL>[Link text, window=_blank]. Add additional info or subtext if required. diff --git a/modules/_templates/quickstart.adoc b/modules/_templates/quickstart.adoc new file mode 100644 index 000000000..889863276 --- /dev/null +++ b/modules/_templates/quickstart.adoc @@ -0,0 +1,103 @@ += <Title: Getting started with <feature name> > +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1 or 2 levels. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-description: <One sentence: what this quickstart guide covers and who it is for.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page. For example, "embedding-quickstart".> +:keywords: <comma-separated terms. For example, "getting started with embedding", "quickstart"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +// Intro text with 1-2 sentences: what the user will have running or achieved by the +// end of this page. +// Example: "This guide walks you through configuring MCP Server in a chatbot" + +== Before you begin + +// List everything the user must have in place before starting. + + +== Step 1: <First milestone, for example, "Add MCP Server"> + +// Keep each step focused on a single milestone the user can verify. +// Use a numbered list for the actions within each step. + +. Action one. ++ +[source,bash] +---- +# example command +---- + +. Action two. + +. Verify the installation was successful: ++ +[source,bash] +---- +# verification command +---- ++ +Expected output: ++ +---- +<expected output here> +---- + +== Step 2: <Second milestone, for example, "Configure your environment"> + +. Action one. ++ +[source,bash] +---- +# example command or configuration snippet +---- + +. Action two. + + +== Step 3: <Third milestone, for example, "Run your first <action>"> + +. Action one. +. Action two. ++ +[source,bash] +---- +# example command +---- + +. Verify the result: ++ +---- +<expected output here> +---- + +== Next steps + +// Tell the user what to do now that they have a working setup. +// Link to tutorials, deeper configuration guides, or key concepts. + +Now that you have <feature> running, you can: + +* xref:page.adoc[<Next logical task>] +* xref:page1.adoc[<Explore a key feature>] +* xref:page2.adoc[<Understand a core concept>] + +== Troubleshooting + +// Optional. Cover the 2-3 most common issues users hit during setup. + +* *<Issue>*: <state the issue, cause, and fix/workaround>. +* *<Issue>*: <state the issue, cause, and fix/workaround>. + +// Link to the full troubleshooting page if one exists. + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. Add additional info or subtext if required. +//* link:<URL>[Link text, window=_blank]. Add additional info or subtext if required. diff --git a/modules/_templates/reference.adoc b/modules/_templates/reference.adoc new file mode 100644 index 000000000..d21f4ad2e --- /dev/null +++ b/modules/_templates/reference.adoc @@ -0,0 +1,169 @@ += <Title: Noun phrase, for example, "Liveboard report API reference"> +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1 or 2 levels. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-description: <State the purpose and brief summary of the contents of the reference document> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page. For example, "Variable API reference".> +:keywords: <comma-separated terms for search indexing, for example, "REST API endpoint", "Report API", "Liveboard export"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/reference.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "rest-api-auth-reference.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for pages that document parameters, properties, endpoints, request/response workflows, classes, enumerations, or configuration options — reference material a reader looks up, not reads start-to-finish. + +Section labels: + REQUIRED — must be present on every page of this type + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to the topic + +Code samples: + SDK reference : JavaScript or TypeScript example is REQUIRED. + REST API reference : cURL request + JSON response are REQUIRED. + Resource URL, Request parameters, Example request, + Example response, and Response codes are all REQUIRED + for each endpoint documented on this page. + +Style elements you can use: + Tables : [cols="...", options="header"] |=== ... |=== + Code blocks : [source,JavaScript] / [source,TypeScript] / [source,cURL] / [source,JSON] + Admonitions : [NOTE], [TIP], [IMPORTANT], [WARNING] + Inline badge : [beta betaBackground]^Beta^, [earlyAccess eaBackground]#Early Access# + Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated# + [.version-badge.breaking]#Breaking# [.version-badge.fixed]#Fixed# +//// + +// REQUIRED: 1-2 sentences describing what this reference covers — the API, SDK class, +// endpoint group, or configuration object — and the primary use case. + +// OPTIONAL: Comparison matrix — use when documenting multiple methods, endpoints, or +// authentication options that readers commonly need to choose between: +// +// [cols="1,1,1,1", options="header"] +// |=== +// |Method |Auth type |Rate limit |Notes +// |REST API v2 |Bearer token |1000/min |Recommended for new integrations +// |REST API v1 |Basic auth |500/min |Legacy; migrate to v2 when possible +// |Visual Embed SDK |Trusted auth |N/A |TypeScript support; browser only +// |=== + +== Supported operations + +// OPTIONAL for REST API reference pages that cover multiple endpoints. +// List the endpoints or operations covered on this page. +// Use an include directive if the list is generated: +// include::{path}/<api>-list.adoc[] + +=== Required permissions + +// RECOMMENDED: State the role or permission required to call these APIs. + + +// ───────────────────────────────────────────────────────────────────────────── +// ENDPOINT / ATTRIBUTE BLOCK +// Repeat this block for each endpoint or configuration property. +// ───────────────────────────────────────────────────────────────────────────── + +== <Operation or property name> + +// REQUIRED: One sentence describing what this endpoint or property does. + +=== Resource URL + +// REQUIRED for REST API reference. Use a literal block (no syntax highlighting). +---- +POST /api/rest/2.0/<endpoint-path> +---- + +=== Request parameters + +// REQUIRED. Document every parameter. Use "None" if there are no parameters. + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description + +|`param_name` +|string +|Yes +|Description of what this parameter does. Default: none. + +|`optional_param` +|boolean +|No +|Optional flag. Default: `false`. + +|=== + +// OPTIONAL: Version-specific notes — use inline badges to flag changes per parameter: +// [.version-badge.new]#New in vX.X# `new_param` — added in this version; description. +// [.version-badge.deprecated]#Deprecated# `old_param` — deprecated in vX.X; use `new_param` instead. +// [.version-badge.breaking]#Breaking# `changed_param` — behavior changed in vX.X. + +=== Example request + +// REQUIRED. Provide a complete, working example. +// For SDK reference: + +[source,JavaScript] +---- +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '<liveboard-GUID>', + // Optional parameters: + fullHeight: true, + disabledActions: [], +}); +embed.render(); +---- + +// For REST API reference — provide a cURL example: + +[source,cURL] +---- +curl -X POST \ + 'https://<your-instance>.thoughtspot.cloud/api/rest/2.0/<endpoint>' \ + -H 'Authorization: Bearer <token>' \ + -H 'Content-Type: application/json' \ + -d '{ + "param_name": "value", + "optional_param": false + }' +---- + +=== Example response + +// REQUIRED for REST API reference. + +[source,JSON] +---- +{ + "field": "value", + "nested": { + "key": "value" + } +} +---- + +=== Response codes + +// REQUIRED for REST API reference. List HTTP status codes and their meanings. Include additional details as needed. + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. Add additional info or subtext if required. +//* link:<URL>[Link text, window=_blank]. Add additional info or subtext if required. diff --git a/modules/_templates/release-notes.adoc b/modules/_templates/release-notes.adoc new file mode 100644 index 000000000..f82ab258a --- /dev/null +++ b/modules/_templates/release-notes.adoc @@ -0,0 +1,113 @@ += <Title: What's new/Release notes/Changelog> +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page, for example, "release-notes-26-5".> +:page-description: <One sentence: "Release notes for ThoughtSpot Embedded" "MCP Server changelog"> +:keywords: <comma-separated terms. For example, "release notes", "changelog", "new features and enhancements"> +// last-reviewed: <Optional> + +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/release-notes.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "release-notes-26-5.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for release note pages (What's New, changelogs, version history). +Base format: tabular layout modelled on the existing What's New and changelog pages. + +Section labels: + REQUIRED — must be present on every release note page + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to this release + +Tags (column cell, use in the first column of the change table): + [tag greenBackground]#NEW FEATURE# + [tag greenBackground]#ENHANCEMENT# + [tag redBackground]#DEPRECATED# + [tag redBackground]#BUG FIX# + +Inline badges (append after a feature name or inside a description): + [beta betaBackground]^Beta^ — feature is in Beta + [.version-badge.new]#New# — new in this version + [.version-badge.breaking]#Breaking# — breaking change + [.version-badge.deprecated]#Deprecated# — item is deprecated + [.version-badge.fixed]#Fixed# — bug fix + +Format notes: + - Use [discrete] before ==== headings inside table cells to suppress TOC entries. + - Separate entries within the same cell with a horizontal rule: --- + - Each JIRA reference appears in parentheses at the end: (SCAL-XXXXXX) + - Use `*` bold for version labels and metadata lines inside cells. + - Link to full documentation using xref once the target page is published. +//// + +// REQUIRED: One sentence stating the release scope and any critical headline. +This release includes updates to <product area, for example, "the Visual Embed SDK and embed APIs">. + +// REQUIRED: Release metadata block. +*Release version*: ThoughtSpot Cloud <version> + +*Upgrade notes*: <None. / ⚠️ Describe any breaking changes; link to Upgrade notes section.> + +*Recommended SDK versions*: Visual Embed SDK v<X.XX.X> and later + +// REQUIRED: Change table. +// Each row = one change category. Repeat rows as needed. +// The first column holds the tag; the second holds all entries for that category. + +[width="100%" cols="1,4"] +|==== + +// ── NEW FEATURES ────────────────────────────────────────────────────────────── +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +==== <Feature name> [beta betaBackground]^Beta^ + +// REQUIRED: One sentence describing what it does and who benefits. +// TODO: replace the placeholder link once the documentation page is published. +// xref:<page>.adoc[<Feature name>] +Description of the new feature and its benefit to developers or administrators. + +--- + +[discrete] +==== <Second new feature name> + +Description of the second new feature. + +// ── IMPROVEMENTS ────────────────────────────────────────────────────────────── +|[tag greenBackground]#ENHANCEMENT# a| + +* Brief description of the improvement. +* Brief description of another improvement. + +// ── DEPRECATIONS ────────────────────────────────────────────────────────────── +|[tag redBackground]#DEPRECATED# a| + +* `<deprecated_item>` — deprecated in this release. Use `<replacement>` instead. + + +// ── BUG FIXES ───────────────────────────────────────────────────────────────── +// OPTIONAL. Generally not included in monthly release notes/what's new unless the bug fix introduces a behavior change in the product. +//|[tag redBackground]#BUG FIX# a| + +//* Brief description of what was broken and what was fixed. +//* Brief description of another bug fix. + +|==== + +// REQUIRED only when this release includes breaking changes or migration steps. +== Upgrade notes + +// Document breaking changes, configuration updates, or migration steps required. +// Reference specific API endpoints, SDK methods, or config keys by name. + +== Known issues + +// Optional. Generally included in the release notes/what's new blurb itself, or feature documentation pages. If including it as a separate section, describe open issues and workarounds. diff --git a/modules/_templates/troubleshooting.adoc b/modules/_templates/troubleshooting.adoc new file mode 100644 index 000000000..321a63d78 --- /dev/null +++ b/modules/_templates/troubleshooting.adoc @@ -0,0 +1,70 @@ += <Title: Troubleshooting <authentication errors> > +:toc: true +:toclevels: 1 +// Required for mini-toc presentation in the documentation site. The general standard is 1. Adjust toclevels as needed. + +:page-title: <Title text for the page> +:page-description: <One sentence: what issues this page covers and who it is for.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page, for example, "embed-auth-troubleshooting".> +:keywords: <comma-separated terms. For example, "troubleshooting", "authentication errors", "authentication recommendations"> +:product-version: <Optional> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +// 1-2 sentences: what issues this page aims to resolve and who it is for. + +== General troubleshooting steps + +// Optional. Steps to try before attempting issue-specific fixes. +// Remove this section if all issues have distinct, unrelated causes. + +. Check that you are running the correct version. See xref:page.adoc[Supported versions]. +. Review the logs for error messages. Log files are located at `<log-path>`. + +== <heading text describing the issue. For example, "Login failed error"> + +// Description of the error scenario. For example, "The login failed error occurs if the authentication token has expired or when the user account is deactivated." + +// Describe exactly what the user sees: error message text, UI behavior, +// or unexpected output. Use a literal block for exact error messages. + +---- +<exact error message or log output here> +---- + +// Explain why this happens. If the cause is unknown, write: +// "The cause of this issue has not been determined." + +=== Solution/Workaround + +//. Step one. +//. Step two. +//. Step three. + +=== Verification + +// Optional. Describe what the user should see to confirm the issue is resolved. + +--- + +== <Issue title> + +// Description + +=== Solution/Workaround + +//. Step one. +//. Step two. +//. Step three. + +=== Verification + +// Optional. + + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. Add additional info or subtext if required. +//* link:<URL>[Link text, window=_blank]. Add additional info or subtext if required. diff --git a/src/assets/styles/index.scss b/src/assets/styles/index.scss index 4b63c8564..baf0ec97c 100644 --- a/src/assets/styles/index.scss +++ b/src/assets/styles/index.scss @@ -1103,7 +1103,7 @@ a.anchor { .header-banner { min-height: 240px; background: var(--header-banner-background); - box-shadow: 0 3px 3px #122246; + box-shadow: 0 2px 2px #1B3E61; padding: 30px 0 0 40px; diff --git a/src/components/DevDocTemplate/index.tsx b/src/components/DevDocTemplate/index.tsx index 97372e2b5..bb83b7d80 100644 --- a/src/components/DevDocTemplate/index.tsx +++ b/src/components/DevDocTemplate/index.tsx @@ -51,7 +51,6 @@ import { } from '../../constants/uiConstants'; import t from '../../utils/lang-utils'; import { getHTMLFromComponent } from '../../utils/react-utils'; -import { ThemeBuilder } from './playGround/ThemeBuilder'; import VersionIframe from '../VersionIframe'; const DevDocTemplate: FC<DevDocTemplateProps> = (props) => { @@ -150,10 +149,7 @@ const DevDocTemplate: FC<DevDocTemplateProps> = (props) => { const isApiPlayground = params[TS_PAGE_ID_PARAM] === CUSTOM_PAGE_ID.API_PLAYGROUND; - const isThemeBuilder = - params[TS_PAGE_ID_PARAM] === CUSTOM_PAGE_ID.THEME_BUILDER; - - const isVersionedIframe = VERSION_DROPDOWN.some( +const isVersionedIframe = VERSION_DROPDOWN.some( (version) => props?.pageContext?.iframeUrl && version.iframeUrl === props?.pageContext?.iframeUrl, @@ -170,7 +166,6 @@ const DevDocTemplate: FC<DevDocTemplateProps> = (props) => { const isPlayGround = isGQPlayGround || isApiPlayground || - isThemeBuilder || isVersionedIframe; const isAskDocsPage = params[TS_PAGE_ID_PARAM] === CUSTOM_PAGE_ID.ASK_DOCS; @@ -554,11 +549,7 @@ const DevDocTemplate: FC<DevDocTemplateProps> = (props) => { /> ); - if (isThemeBuilder) { - return <ThemeBuilder backLink={backLink} />; - } - - if (isVersionedIframe) { +if (isVersionedIframe) { return ( <VersionIframe iframeUrl={props.pageContext.iframeUrl} diff --git a/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx b/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx deleted file mode 100644 index 7fa3847f8..000000000 --- a/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx +++ /dev/null @@ -1,27 +0,0 @@ -import * as React from 'react'; -import BackButton from '../../BackButton'; - -export const ThemeBuilder: React.FC<ThemeBuilderProps> = (props) => { - const playgroundUrl = 'https://theme-builder-embed-prod.vercel.app/'; - - return ( - <div className="restApiWrapper"> - <BackButton - title="Back" - backLink={props.backLink} - internalRedirect - /> - <iframe - ref={null} - src={playgroundUrl} - height="100%" - width="100%" - id="theme-builder" - /> - </div> - ); -}; - -type ThemeBuilderProps = { - backLink: string; -}; diff --git a/src/components/SecondaryHeader/index.scss b/src/components/SecondaryHeader/index.scss index 9c37aa803..1b2a032fa 100644 --- a/src/components/SecondaryHeader/index.scss +++ b/src/components/SecondaryHeader/index.scss @@ -3,7 +3,7 @@ .secondary-header { background: var(--secondary-header-bg); border-bottom: 0.5px solid var(--secondary-header-border); - box-shadow: 0 2px 2px #1B3E61; + box-shadow: 0 1px 1px #1B3E61; border-top: 0.5px solid var(--secondary-header-border); position: sticky; top: $header-height; diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 7509f0d2b..01c202c5c 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -22,8 +22,8 @@ module.exports = { // 'https://developers.thoughtspot.com/docs/26.3.0.cl?pageid=whats-new' // - GA: ' /docs/whats-new' //linkHref: '/docs/whats-new', - linkHref: '/docs/26.5.0.cl?pageid=whats-new', - linkText: 'Version 26.5.0.cl', + linkHref: '/docs/26.6.0.cl?pageid=whats-new', + linkText: 'Version 26.6.0.cl', openInNewTab: true, }, TYPE_DOC_PREFIX: 'typedoc', @@ -48,9 +48,15 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '26.5.0.cl', + label: '26.6.0.cl', link: ' ', subLabel: 'Cloud (Latest)', + iframeUrl: 'https://developer-docs-26-6-0-cl.vercel.app/docs/', + }, + { + label: '26.5.0.cl', + link: '26.5.0.cl', + subLabel: 'Cloud', iframeUrl: 'https://developer-docs-26-5-0-cl.vercel.app/docs/', }, { @@ -65,12 +71,6 @@ module.exports = { subLabel: 'Cloud', iframeUrl: 'https://developer-docs-26-3-0-cl.vercel.app/docs/', }, - { - label: '26.2.0.cl', - link: '26.2.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-2-0-cl.vercel.app/docs/', - }, { label: '26.3.0.sw', link: '26.3.0.sw', @@ -90,13 +90,11 @@ module.exports = { subLabel: 'Software', iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', }, - ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', ASK_DOCS: 'ask-docs', GQ_PLAYGROUND: 'graphql-play-ground', - THEME_BUILDER: 'theme-builder', }, CLUSTER_TYPES: { PROD: 'PROD',