| ThoughtSpot Thought Spot Application Integration Guide 5.1

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 93

Download| ThoughtSpot Thought Spot Application Integration Guide 5.1
Open PDF In BrowserView PDF
Application Integration Guide
Version 5.1 February 08, 2019

Copyright for ThoughtSpot publications. © 2019 ThoughtSpot, Inc. All rights
reserved.
ThoughtSpot, Inc. 1 Palo Alto Square
Building 1, Suite 200
Palo Alto, CA 94306
All rights reserved. This product is protected by U.S. and international copyright
and intellectual property laws. ThoughtSpot is a trademark of ThoughtSpot, Inc. in
the United States and/or other jurisdictions. All other marks and names mentioned
herein may be trademarks of their respective companies.

ThoughtSpot Application Integration Guide

February 08, 2019

Table of Contents
Introduction .............................................................................................................................. 3
Log in to the Linux shell using SSH ......................................................................................... 4
Log in credentials ..................................................................................................................... 5
Get the JavaScript API ............................................................................................................. 7
SAML

About SAML .......................................................................................................................... 9
Configure SAML .................................................................................................................. 10
Configure CA SiteMinder .................................................................................................... 11
Active Directory

Configure Active Directory Federated Services .............................................................. 14
Initialize the Identity Provider Metadata
Metadata..........................................................................
.......................................................................... 15
Initialize the Service Provider Metadata
Metadata..........................................................................
.......................................................................... 16
Test the ADFS Integration
Integration...............................................................................................
............................................................................................... 17
REST API

About the REST API ............................................................................................................ 18
Calling the REST API
API...........................................................................................................
........................................................................................................... 20
REST API pagination ........................................................................................................... 24
Use the REST API to get data ............................................................................................. 27
Use the Embedded Search API
API...........................................................................................
........................................................................................... 30
Use the Data Push API
API........................................................................................................
........................................................................................................ 31
Embed ThoughtSpot

Understand embedding ...................................................................................................... 35
Embed pinboard or visualization
visualization.........................................................................................
......................................................................................... 39
Authentication flow with embed
embed..........................................................................................
.......................................................................................... 44
Full application embedding ................................................................................................. 46
Configured trusted authentication
authentication.......................................................................................
....................................................................................... 49
Runtime Filters

About Runtime Filters
Filters..........................................................................................................
.......................................................................................................... 52
Apply a Runtime Filter ......................................................................................................... 54
Runtime Filter Operators ..................................................................................................... 56
Style Customization

Customize the application style .......................................................................................... 57
Upload application logos .................................................................................................... 59

support@thoughtspot.com

i

ThoughtSpot Application Integration Guide

February 08, 2019

Set chart and table visualization fonts ................................................................................ 60
Choose a background color
color................................................................................................
................................................................................................ 63
Select chart color palettes .................................................................................................. 64
Change the footer text ........................................................................................................ 66
API Reference

Introduction ......................................................................................................................... 67
pinboarddata API ................................................................................................................ 68
metadata API
API.......................................................................................................................
....................................................................................................................... 71
session API
API..........................................................................................................................
.......................................................................................................................... 78
user API ............................................................................................................................... 80
group API ............................................................................................................................ 90

support@thoughtspot.com

ii

Introduction

February 08, 2019

Introduction
This guide explains how to integrate ThoughtSpot with other applications, including authentication,
embedding, and APIs. For information on how to integrate with other data sources for loading data, refer
to the Data Integration Guide.
Here are the top level topics on application integration:
•
•
•
•
•
•
•
•
•

Log in to the Linux shell using SSH
Login credentials
Using the JavaScript API
SAML
REST API
Emdbed ThoughtSpot
Runtime Filters
Style Customization
API Reference

ThoughtSpot Application Integration Guide

Page 3

Log in to the Linux shell using SSH

February 08, 2019

Log in to the Linux shell using SSH
To perform basic administration such as checking network connectivity, starting and stopping services,
and setting up email, log in remotely as the Linux administrator user “admin”. To log in with SSH from a
client machine, you can use the command shell or a utility like Putty.
In the following procedure, replace  with the hostname or IP address of a node in
ThoughtSpot. The default SSH port (22) will be used.
1. Log in to a client machine and open a command prompt.
2. Issue the SSH command, specifying the IP address or hostname of the ThoughtSpot
instance:

ssh admin@

3. Enter the password for the admin user.

ThoughtSpot Application Integration Guide

Page 4

Log in credentials

February 08, 2019

Log in credentials
You can access ThoughtSpot via SSH at the command prompt and from a Web browser.

Administrative access
Each ThoughtSpot appliance comes pre-built with three default users. You should talk with a
ThoughtSpot Customer Success Engineer or ThoughtSpot support, to get the password for each user.
The default users are:
Type

Username

Description

Shell user

admin

Used for work that requires sudo or root privileges. Does not exist
for application login. Logs for this user are found in /usr/local/
scaligent/logs logs

Shell user

thoughtspot

Used for command line work that does not require sudo or root
privileges. For example, these users can use tsload , tql , and
check the cluster status. This user cannot login to the application.
Logs for this user are found under /tmp .

Application
user

tsadmin

Access through a Web browser.

Both the admin and thoughtspot user can SSH into the appliance. Once on the appliance, either
user can do any of the following:
• tscli
• tsload
• tql
The thoughtspot user is restricted to tscli commands that do not require sudo or root privileges.

SSH to the appliance
To perform basic administration such as checking network connectivity, starting and stopping services,
and setting up email, log in remotely as the Linux administrator user “admin”. To log in with SSH from
any machine, you can use the command shell or a utility like Putty.
In the following procedure, replace  with the hostname or IP address of a node in
ThoughtSpot. The default SSH port (22) will be used.
1. Log in to a client machine and open a command prompt.
2. Issue the SSH command, specifying the IP address or hostname of the ThoughtSpot
instance:

ssh admin@

ThoughtSpot Application Integration Guide

Page 5

Log in credentials

February 08, 2019

3. Enter the password for the admin user.

Log in to the ThoughtSpot application
To set up and explore your data, access the ThoughtSpot application from a standard Web browser
using a username and password.
Before accessing ThoughtSpot, you need:
•
•
•
•

The Web address (IP address or server name) for ThoughtSpot.
A network connection.
A Web browser.
A username and password for ThoughtSpot.
Supported Web browsers include:
Browser

Version

Operating System

Google Chrome

20 and above

Windows 7 or greater, Linux, MacOS

Mozilla Firefox

14 and above

Windows 7 or greater, Linux, MacOS

Internet Explorer

11

Windows 7 or greater

 Tip: While Internet Explorer is supported, using it is not recommended. Depending
on your environment, you can experience performance or UI issues when using IE.

To log in to ThoughtSpot from a browser:
1. Open the browser and type in the Web address for ThoughtSpot:
http://

2. Enter your username and password and click Enter Now
Now.

ThoughtSpot Application Integration Guide

Page 6

Using the JavaScript API

February 08, 2019

Using the JavaScript API
The ThoughtSpot JavaScript API (JS API) allows you to use your ThoughtSpot instance within your own
Web application. The JS API has methods that allow you to:
• Authenticate to ThoughtSpot.
• Embed visualizations from ThoughtSpot in your Web page using iframes.
• Use the ThoughtSpot REST API to get data from ThoughtSpot and use it in your Web page.
You can download the ThoughtSpot JavaScript library from our secure storage server.

 Note: To use the JS API in your Web page, you must have the access and permissions to
update the code of the web page or application.

Browser Support
The JS API works in the following browsers:
Browser

Versions

Internet Explorer

11

Firefox

38 or later

Google Chrome

47 or later

Safari

9 or later

Internet Explorer 10
Microsoft introduced a compatibility mode in Internet Explorer 10, which displays your page using the
version of Internet Explorer that is most compatible with the current page. Since we do not support any
version below 11, this feature can sometimes break the code. There are two ways to force the emulation
of Internet Explorer to the most up to date version:
• Add a Custom Response Header
This is the recommended approach since it is more robust, offers more control, and has a
lower risk of introducing a bug to your code. The header name should be set to “X-UACompatible” and the value should be set to “IE=Edge”. The response header should be based
on the server it is set on and the technology being used.
• Add a Meta Tag
The following meta tag should be added to your header:  . This tag must be the first tag in the header section of
the page.

ThoughtSpot Application Integration Guide

Page 7

Using the JavaScript API

February 08, 2019

Cross-Origin HTTP Requests (CORS)
Collecting user credentials from one application (domain) and sending them to another (such as
ThoughtSpot) can present security vulnerabilities such as a phishing attack. Cross-origin or crossdomain verification closes this vulnerability.
When you use the JavaScript API, your client makes a call from your own Web page, portal, or
application to ThoughtSpot. The domains of your client and ThoughtSpot will be different. So, you’ll
need to enable cross-origin HTTP requests from your client application to the ThoughtSpot application.
This protects your data, so that another actor cannot use the same URL to embed the visualization in its
own Web pages.
Your cluster’s CORS configuration controls which domains are allowed to use your client code to
authorize users. It also prevents other people from copying your code and running it on their site. For
example, if your Web site is hosted on the domain example.com , you would enable CORS for that
domain. Similarly, if you want to test your code locally, you’ll also need to add the origin for your local
server as well, for example: http://localhost:8080. Though, it is a good idea to disable the
localhost access after your testing is complete.
To enable CORS between your client applications and your ThoughtSpot instance. , you must work with
ThoughtSpot Support.

ThoughtSpot Application Integration Guide

Page 8

About SAML

February 08, 2019

About SAML
ThoughtSpot can be set up with Security Assertion Markup Language (SAML) to enable Single Sign On
(SSO). SAML can be configured in several ways, including with CA SiteMinder.
For basic instructions on configuring SAML, use one of these procedures:
• Configure SAML, for instructions to configure SAML in ThoughtSpot.
• Configure SAML with CA SiteMinder, for configuring SAML specifically with CA SiteMinder.

ThoughtSpot Application Integration Guide

Page 9

Configure SAML

February 08, 2019

Configure SAML
ThoughtSpot can use Security Assertion Markup Language (SAML) to authenticate users. You can set up
SAML through the shell on the ThoughtSpot instance using a tscli based configurator.
Before configuring SAML, you will need this information:
•
•
•
•

IP of the server where your ThoughtSpot instance is running.
Port of the server where your ThoughtSpot instance is running.
Protocol, or the authentication mechanism for ThoughtSpot.
Unique service name that is used as the unique key by IDP to identify the client.
It should be in the following format: urn:thoughtspot:callosum:saml

• Allowed skew time, which is the time after authentication response is rejected and sent back
from the IDP. It is usually set to 86400.
• The absolute path to the idp-meta.xml file. This is needed so that the configuration persists
over upgrades.
• This configurator also checks with the user if internal authentication needs to be set or not.
This internal authentication mechanism is used to authenticate tsadmin , so set it to true if
you do not know what it does.
Use this procedure to set up SAML on ThoughtSpot for user authentication. Note that this configuration
persists across software updates, so you do not need to reapply it if you update to a newer release of
ThoughtSpot.
1. Log in to the Linux shell using SSH.
2. Execute the command to launch the interactive SAML configuration:

tscli saml configure

3. Complete the configurator prompts with the information you gathered above.
4. When the configuration is complete, open a Web browser and go to the ThoughtSpot login
page. It should now show the Single Sign On option.

ThoughtSpot Application Integration Guide

Page 10

Configure CA SiteMinder

February 08, 2019

Configure CA SiteMinder
Summary: CA SiteMinder can be used as an Identity Provider for
single sign on to ThoughtSpot.
Before configuring CA SiteMinder, you must configure SAML in ThoughtSpot. Use this procedure to set
up CA SiteMinder for use with ThoughtSpot:
1. Configure the Local Identity Provider Entity as follows:
Section

Entry

Entity Location

Local

Entity Type

SAML2 IDP

Entity ID

Any (Relevant ID)

Entity Name

Any (Relevant name)

Description

Any (Relevant description)

Base URL

https:// where FWS_FQDN is the fully-qualified domain name for the host serving SiteMinder Federation Web Services

Signing Private Key
Alias

Select the correct private key alias or import one if not done already

Signed Authentication Requests Required

No

Supported NameID
format

Optional

2. Create the Remote SP Entity, either via a metadata import or manually. To configure the
Remote SP entity manually, select Create Entity
Entity. Create ThoughtSpot as a Remote Entity with
following details:
Section

Entry

Entity Location

Remote

New Entity Type

SAML2 SP

Entity ID

Your cluster

Entity Name

Any (relevant name)

ThoughtSpot Application Integration Guide

Page 11

Configure CA SiteMinder

February 08, 2019

Section

Entry

Description

Any (relevant description)

Assertion Consumer Service
URL

(Relevant URL)

Verification Certificate Alias

Select the correct certificate or import one if not done already. This
is used to verify the signature in incoming requests

Supported
NameID Format

Optional

3. You will now configure the Federation Partnership between CA SiteMinder (the IDP) and
ThoughtSpot (the Remote SP) in CA SiteMinder. Log in to CA SiteMinder.
4. Navigate to Federation -> Partnership Federation -> Create Partnership (SAML
SAML 2 IDP -> SP
SP).
5. Click Configure Partnership and fill in the following values:
Section

Entry

Add Partnership Name

Any (relevant name)

Description

Any (relevant description)

Local IDP ID

Select Local IDP ID

Remote SP ID

Select Remote SP ID

Base URL

Will be pre-populated

Skew Time

Any per environment requirement

User Directories and Search Order

Select required Directories in required search order

6. Click Configure Assertion and fill in the following values:
Section

Entry

Name ID
Format

Optional

Name ID
Type

User Attribute

Value

Should be the name of the user attribute containing the email address or
user identifier. For example, ‘mail’

7. Click Configure SSO and SLO and fill in the following values:

ThoughtSpot Application Integration Guide

Page 12

Configure CA SiteMinder

February 08, 2019

Section

Entry

Add Authentication URL

This should be the URL that is protected by SiteMinder

SSO Binding

Select SSO Binding supported by the SP, typically the
HTTP-Post

Audience

(Relevant audience)

Transaction Allowed

Optional

Assertion Consumer Service URL

This should be pre-populated using the information from
the SP entity

8. Continue to Partnership Activation and select Activate
Activate.

ThoughtSpot Application Integration Guide

Page 13

Configure Active Directory Federated Services

February 08, 2019

Configure Active Directory Federated
Services
You can configure Active Directory Federated Services (AD FS) to work with ThoughtSpot. This
procedure outlines the basic prerequisites and steps to set up AD FS.
• Configure SAML in ThoughtSpot.
• Install AD FS 2.0.
• Make sure you can run AD FS 2.0 Federation Server Configuration Wizard from the AD FS 2.0
Management Console.
• Make sure that DNS name of your Windows Server is available at your service provider (SP)
and vice versa. You can do this by running the command nslookup on both machines,
supplying the DNS of the other server.
AD FS 2.0 supports SAML 2.0 in IdP (Identity Provider) mode and can be easily integrated with the SAML
Extension for both SSO (Single Sign-On) and SLO (Single Log Out).
After completing the prerequisites, use these procedures to configure AD FS for use with ThoughtSpot.
1. Initialize IdP metadata.
2. Initialize the Service Provider metadata.
3. Test your ADFS integration.

ThoughtSpot Application Integration Guide

Page 14

Initialize the Identity Provider Metadata

February 08, 2019

Initialize the Identity Provider Metadata
Summary: This procedure shows how to initialize the Identity Provider
(IdP) metadata for AD FS.
This is one part of the configuration procedure for setting up ThoughtSpot to work with AD FS for
authentication. You should also refer to the overview of the entire process of integrating with AD FS.
To initialize the IdP metadata on AD FS:
1. Download the AD FS 2.0 IdP metadata from the AD FS server. You can reference this file by
its URL, which looks like:

https:///FederationMetadata/2007-06/Federat
ionMetadata.xml

2. Log in to the Linux shell using SSH.
3. Change directories to the SAML directory:

$ cd /usr/local/scaligent/release/production/orion/tomc
at/callosum/saml

4. Replace the contents of the file idp-meta.xml with the metadata of the IdP that you
downloaded. Do not change the name of the file.
5. Contact ThoughtSpot support for help restarting ThoughtSpot’s Tomcat instance.
6. Next, Initialize the Service Provider Metadata.

ThoughtSpot Application Integration Guide

Page 15

Initialize the Service Provider Metadata

February 08, 2019

Initialize the Service Provider Metadata
Summary: This procedure shows how to initialize the Service Provider
(SP) metadata for AD FS.
This is the second part of the configuration procedure for setting up ThoughtSpot to work with AD FS for
authentication. You should also refer to the overview of the entire process of integrating with AD FS.
To initialize the Service Provider metadata on AD FS:
1.
2.
3.
4.
5.
6.

7.
8.
9.
10.
11.
12.
13.

14.
15.
16.
17.
18.

Open the AD FS 2.0 Management Console.
Select Add Relying Party Trust
Trust.
Select Import data about the relying party from a file
file.
Upload the metadata.xml file that you downloaded from ThoughtSpot earlier.
Select Next. The wizard may complain that some of the content of the metadata is not
supported. You can safely ignore this warning.
In the Ready to Add Trust section, make sure that the tab endpoints contains multiple
endpoint values. If not, verify that your metadata was generated with the HTTPS protocol
URLs.
Leave the Open the Edit Claim Rules dialog checkbox checked. Click Next
Next.
Select Add Rule
Rule.
Choose Send LDAP Attributes as Claims and click Next.
For NameID enter “Claim rule name”
For Attribute store
store, choose “Active Directory”.
For LDAP Attribute choose “SAM-Account-Name”.
For Outgoing claim type
type, choose “Name ID”.
a. If you are using ADFS 3.0, you might need to configure the Name ID as a Pass
Through claim.
Finish the wizard and confirm the claim rules window.
Open the provider by double-clicking it.
Select the Advanced tab and change Secure hash algorithm to “SHA-1”.
Your Service Provider is now registered.
Test the ADFS Integration.

ThoughtSpot Application Integration Guide

Page 16

Test the ADFS Integration

February 08, 2019

Test the ADFS Integration
After setting up the AD FS integration, test to make sure it is working properly. To test your AD FS
integration, go to ThoughtSpot login page using a Web browser and try to login with SAML.

ThoughtSpot Application Integration Guide

Page 17

About the REST API

February 08, 2019

About the REST API
Summary: The purpose of the REST API is to get data out of
ThoughtSpot so you can use it in a Web page, portal, or application.
When using the REST API, authentication is achieved through SAML. After authentication, use the POST
method to call a URL for the desired visualization or pinboard. A JSON (JavaScript Object Notation)
representation of the data will be returned.

Authentication
Before you can use the REST API, you must authenticate to ThoughtSpot using SAML with the
JavaScript API.

Cross Domain Verification
You’ll need to enable cross domain verification when using the REST API. This protects your data, so
that another website cannot use a URL to get data from ThoughtSpot. The procedure for enabling the
JavaScript API includes information on how to enable this.

REST API capabilities
Use a POST method to access the URL, which calls the REST API. The data is returned as a JSON
string. When using this method, you’ll need to extract the data from the JSON file and render it on your
Web page, portal, or application.
You can use the REST API to do things like:
•
•
•
•

Generate dynamic picklists on your Web page.
Display a single value.
Retrieve the data to populate a visualization drawn by your own renderer.
Pull data directly from ThoughtSpot

Remember that the data you retrieve from ThoughtSpot is live data, so whenever the Web page is
rendered, the current value(s) will be shown.

Direct Search-to-Embed API
The Direct Search-to-Embed API enables searching directly from an external application or web page to
pull data from ThoughtSpot. This feature was introduced in ThoughtSpot 5.0. When using it, you can
access data stored in ThoughtSpot directly. You do not need to save a search result to a pinboard and
then reference it using the visualization’s URL.

Public API reference
You can find more information on our public APIs in the Reference guide.

ThoughtSpot Application Integration Guide

Page 18

Related information

February 08, 2019

Related information
• API Reference guide.
• Direct Search-to-Embed API.

ThoughtSpot Application Integration Guide

Page 19

Calling the REST API

February 08, 2019

Calling the REST API
To call the REST API, you’ll specify a URL using the POST method, passing the ID numbers of the
objects from which you want to obtain data.

Specify the pinboard or visualization example
For a pinboard, you’ll append the ID of your pinboard as a parameter, like this example:

https:///callosum/v1/tspublic/v1/pinboardda
ta?id=7752fa9e-db22-415e-bf34-e082c4bc41c3

To retrieve data from a specific visualization within a pinboard, you would append the ID number of the
visualization using the vizid parameter:

https:///callosum/v1/tspublic/v1/pinboardda
ta?id=7752fa9e-db22-415e-bf34-e082c4bc41c3&vizid=%5B1e99d70f-c1
dc-4a52-9980-cfd4d14ba6d6%5D

Remember: You must add brackets around the vizid parameter. The URL encoding for open bracket is
%5B , and the URL encoding for close bracket is %5D .

Object Format for Returned Data
When you parse the returned JSON data you can see that there is one object for every viz on the
pinboard. The objects are named according to the corresponding vizid.

ThoughtSpot Application Integration Guide

Page 20

Calling the REST API

February 08, 2019

If you make a call to a specific viz on a pinboard, it will return just one object. The JSON object format
for the data that is returned from ThoughtSpot is:

{
vizId1 : {
name: “Viz name”,
:[[2-d array of data values], [], [] …..[]],
columnNames:[col1, col2, …. ],
samplingRatio: n
},
vizId2 : {
.
}
}

Each object contains four components:
1.
2.
3.
4.

An array of column headers.
An array of data.
The name given to the specific viz.
And a sampling ratio. The sampling ratio tells you the percentage of total data returned. 1
would mean all data in the viz was returned in the API call.

The columnNames array contains a list of all column headers. And the data array contains a list of
other arrays. Each sub array represents a new row of data.

ThoughtSpot Application Integration Guide

Page 21

Calling the REST API

February 08, 2019

The REST API supports filtering the data returned via parameters that you pass within the URL. These
are called Runtime Filters.

Example
The following example shows a JavaScript function that calls the REST API, gets the results back, and
retrieves a single value from the JSON results:

ThoughtSpot Application Integration Guide

Page 22

Calling the REST API

February 08, 2019

/**
* Generates headline by making a data API call.
*
* @param void
* @return void
*/
function generateHeadline(filters) {
var pinboardId = "0aa0839f-5d36-419d-b0db-10102131dc37";
var vizId = "67db30e8-06b0-4159-a748-680811d77ceb";
var myURL = "";
if (filters === void 0) {
myURL = "http://192.168.2.55:443/callosum/v1/tspublic/v
1/" +
"pinboarddata?id=" + pinboardId + "&" +
"vizid=%5B" + vizId + "%5D";
} else {
var query = getQueryString(filters);
myURL = "http://192.168.2.55:443/callosum/v1/tspublic/v
1/" +
"pinboarddata?id=" + pinboardId + "&" + +
"vizid=%5B" + vizId + "%5D&" + query;
}
var jsonData = null;
var xhr = new XMLHttpRequest();
xhr.open("POST", myURL, true);
xhr.withCredentials = true;
xhr.onreadystatechange = function() {
var headline = document.getElementById("embeded-headlin
e");
if (xhr.readyState == 4 && xhr.status == 200) {
jsonData = JSON.parse(xhr.responseText);
headline.innerHTML = jsonData[vizId].data[0][0];
} else {
headline.innerHTML = "Error in getting data !!!";
}
};
xhr.send();
}

ThoughtSpot Application Integration Guide

Page 23

REST API pagination

February 08, 2019

REST API pagination
Summary: You can paginate the JSON response that is called from
the REST API. The order of the data is retained from page to page.
Given the ability to paginate, you can quickly populate tables and make new REST calls every time you
go to the next page of the data on the table. There is significant load time if you want to populate the
data table with many rows (greater than 1000) from the REST API.
To paginate results in your API response, you’ll need to add new parameters to the query:
PageSize determines the number of rows to be included.

{
"name": "pagesize",
"description": PageSize: The number of rows.",
"defaultValue": "-1",
"type": "integer"
}

Offset determines the starting point.

{
"name": "offset",
"description": Offset: The starting point",
"defaultValue": "-1",
"type": "integer"
}

PageNumber is an alternate way to determine the offset. You must make a call with pageNumber = 1
first. Then you can access any page. Calling with pageNumber != 1 as the initial call will fail.
pageNumber = 0 is not a valid value.

ThoughtSpot Application Integration Guide

Page 24

REST API pagination

February 08, 2019

{
"name": "pagenumber",
"description": PageNumber: This is an alternate way to set
offset. This is 1-based
indexing. Offset = (pageNumber - 1) * pageSi
ze.
"defaultValue": "-1",
"type": "integer"
}

FormatType is the JSON format type.

{
"name": "formattype",
"description": FormatType: This sets the JSON format type.
Values that are allowed are
FULL and COMPACT.
"defaultValue": "COMPACT",
"type": "string"
}

COMPACT is the default type, and is formatted as follows: ['col1', 'col2'] [1, 'a'] . While FULL
is formatted like this: {'col1': 1 'col2': 'a'}

Example
The following example shows ThoughtSpot data that is being populated in a table:

ThoughtSpot Application Integration Guide

Page 25

REST API pagination

February 08, 2019

/**
* Sample response for Page-1.
*/
{
"totalRowCount": 1500,
"pageSize": 100,
"pageNumber": 1
"data":
[
{
"key1": "value1",
"key2": "value2",
},
{
"key1": "value1",
"key2": "value2",
},
]
}

ThoughtSpot Application Integration Guide

Page 26

Use the REST API to get data

February 08, 2019

Use the REST API to get data
Summary: This procedure shows how to use the REST API to get
data out of ThoughtSpot, so you can use it in a Web page, portal, or
application.
Data retrieved using the REST API is returned as JSON (JavaScript Object Notation).
Before you can use the REST API, you need to enable the JavaScript API (JS API) and authenticate to
ThoughtSpot.
Use this procedure to construct the URL you will use to call the REST API:
1. Log in to ThoughtSpot from a browser.
2. Navigate to the pinboard from which you want to get data. If it doesn’t exist yet, create it now.
3. Find the ID number of the object you want to get the data from. If the object is:
• A pinboard, click ellipses icon (3 dots)

the and select Copy Link
Link.

• A visualization, click the Copy Link icon in the upper right corner of the table or
chart.

ThoughtSpot Application Integration Guide

Page 27

Use the REST API to get data

February 08, 2019

4. Copy the ID number from the link shown. Paste it somewhere so that you can use it later to
construct the URL to use when calling the REST API.
If the object is:
• A pinboard, copy the identifier that appears after “viz/”. Omit the trailing “/”.

• A visualization (table or chart), copy the identifier that appears after “viz/”. This is
the visualization ID.

ThoughtSpot Application Integration Guide

Page 28

Use the REST API to get data

February 08, 2019

5. Construct the URL as follows: For a pinboard, the URL takes the form:

https:///callosum/v1/tspublic/v1/pi
nboarddata?id=

For a visualization, the URL takes the form:

https:///callosum/v1/tspublic/v1/pi
nboarddata?id=&vizid=%5B%5D

6. If you want to apply any filters to the data that will be returned, apply Runtime Filters.
7. Now your URL is complete, and you can use it to access the data directly via the HTTP POST
method. The REST API returns the data formatted as JSON.
8. Retrieve the data from the JSON and display it in your Web page, Web portal, or application.

ThoughtSpot Application Integration Guide

Page 29

Use the Embedded Search API to pull data from ThoughtSpot

February 08, 2019

Use the Embedded Search API to pull
data from ThoughtSpot
Summary: This procedure shows how to use the Embedded Search
API to get data from ThoughtSpot
The Embedded Search API enables searching directly from an external application or web page to pull
data from ThoughtSpot. This feature was introduced in ThoughtSpot 5.0. When using it, you can access
data stored in ThoughtSpot directly. You do not need to save a search result to a pinboard and then
reference it using the visualization’s URL.
This embedded search is useful when you want to allow an application to pull data directly from
ThoughtSpot in an ad hoc fashion.
To have the Embedded Search API functionality turned on, contact ThoughtSpot Support.
Data retrieved using the Embedded Search API is returned as JSON (JavaScript Object Notation). You
will need to parse the JSON to get the data values you need, generally using JavaScript in the receiving
application.
Use this procedure to construct the call to the Embedded Search API:
1. Enable the JavaScript API (JS API) on the receiving page of the target application.
2. Authenticate to ThoughtSpot on the receiving page of the target application.
3. Embed the ThoughtSpot application in your own web page or application.
4. To subscribe to results for all the searches the user does in the embedded ThoughtSpot
application, use the API JavaScript function subscribeToData( ). This will allow your page to
listen for data coming from ThoughtSpot.
Now when a user searches, the iFrame will send data to the subscription. The parent web
page or application receives the data as JSON, and can do whatever you want with it.
5. You can set up your web page or application to display or otherwise act on the data it
receives from the subscription.
6. To test it out, do a search in the embedded ThoughtSpot application to retrieve the data. Your
application should act on the data in the way you set it up to do so.

ThoughtSpot Application Integration Guide

Page 30

Use the Data Push API

February 08, 2019

Use the Data Push API
Summary: This procedure shows how to use the Data Push API to
send data from ThoughtSpot to another application
The Data Push API allows you to open a web page in the context of the ThoughtSpot application. This
third party web page will then have access to the results of the ThoughtSpot search from which it was
invoked. This is useful when you want to initiate an action in another application based on the result of a
search in ThoughtSpot. The Data Push API was introduced in ThoughtSpot 5.0.
An example of pushing data to another system to trigger an action would be where you do a search to
find customers who are coming due for renewal of their contract in the next month. You could then
trigger an action that brings up a web page from an external billing system. The billing system could be
set up to read the data (list of names, emails, products, and renewal dates) from ThoughtSpot. The
billing system might then add the price, generate an invoice for each customer, and send it out via email.
To have the Data Push API functionality turned on, contact ThoughtSpot Support.
The DataPush API makes the data available to the external application formatted as JSON (JavaScript
Object Notation). You will need to parse the JSON to get the data values you need using JavaScript in
the receiving application.

Create an Custom Action
To create a Custom Action, you must have the Can administrator ThoughtSpot privilege.
Use this procedure to create an Custom Action in ThoughtSpot:
1. Log in to ThoughtSpot from a browser.
2. Choose Admin and then Action Customization
Customization.
3. Click the Add custom action item button.
4. Fill in the details for your custom action:
• Item Label: Clicking the menu item with the name you provide here will initiate the
data push to the other system. This menu item will appear under the three dot
menu of a search result.
• URL: The URL of the target page in the external web page or application.
• Window size: The size of the window that will display the external web page or
application in ThoughtSpot.

ThoughtSpot Application Integration Guide

Page 31

Use the Data Push API

February 08, 2019

5. Now when a user is viewing a search result, they’ll have the option to use the Custom Action
you created. To initiate the action, they’ll click the ellipses icon (3 dots)

, and select

Your Action Name
Name. You’ll notice a Custom tag next to your action name to indicate that this is
something custom built, and not a ThoughtSpot action.

6. When a user clicks your action, they’ll see the web page you entered as the URL for your
custom action.

ThoughtSpot Application Integration Guide

Page 32

Use the Data Push API

February 08, 2019

 Note: In order for your action to work correctly, the answer from which the user selected the
action needs to have the correct search terms which your application or web page is expecting to
receive. There is no way to guarantee this, other to train your users on the purpose of your action,
and what’s required for it to run.

Sample application
Here is a sample application you can use to try out the Data Push API:

ThoughtSpot Application Integration Guide

Page 33

Use the Data Push API

February 08, 2019











 






ThoughtSpot Application Integration Guide

Page 34

Understand embedding

February 08, 2019

Understand embedding
Embedding allows you to embed all or part of ThoughtSpot in another client application. This page
provides an explanation of what you must consider when embedding ThoughtSpot

Decide what to embed and where
The type of embedding your company requires can help you determine what type of embedding to use.
For example, you may simply need a single chart displayed as a wallboard or you may want your
customers to access reports on their own data. The first example could require modifying a single HTML
page while the later example may require working with a development team and several different
workflows in a browser application.
Regardless of the simplicity or complexity of your client application, its infrastructure must allow for
loading and calling the ThoughtSpot JS library. This library allows you to authenticate to ThoughtSpot
and load specific objects.
There are different methods for embedding ThoughtSpot into a client application:
Type

Description

Full

Embeds the entire ThoughtSpot application including menu bars. Full navigation is supported.

Page-level

Embeds pages without the menus bars or page-level navigation. This is
useful where you want to limit the inclusion to a portion of ThoughtSpot.
For example, you may only embed the Search or the Answers page.

Object-level

Embed a single visualization in your application. Content is created in
ThoughtSpot and then that content is embedded. The content is rendered
within an iframe . This returns a JSON object that includes the underlying
data.

You can also use the ThoughtSpot data APIs to request data from ThoughtSpot.

Configuration requirements for embedding
Only Extended Enterprise installation can use ThoughtSpot’s embed functionality. ThoughtSpot
Enterprise installations must also work with ThoughtSpot Support to enable embed before using this
functionality.

Optional settings for embedding
There are some settings that apply to embedding which ThoughtSpot Support or your other
ThoughtSpot technical contact can make for you.
One of these involves what happens when a user clicks on a link within the data. When your data
includes URLs, they display as clickable links in ThoughtSpot tables. By default, clicking on a link opens
the URL in a separate tab. But there is a system-wide setting that can be changed to open the links
within the context in which they appear.
Changing this setting opens the links:

ThoughtSpot Application Integration Guide

Page 35

Understand embedding

February 08, 2019

Link type

Opens in

Link in search result table in ThoughtSpot

Same browser tab as ThoughtSpot application

Link in table embedded in an iFrame

Same iFrame that contains the table

Link in full ThoughtSpot application embedded in an
iFrame

Same iFrame that contains the application

Choose an authentication methodology
You can control which type of authentication you use between your client application and ThoughtSpot.

No Authentication
You can simply not set up authentication. This would require the user to already be logged into
ThoughtSpot before interacting with your client application. This is typically only useful when testing your
client. You would not use this in your production environment.

SAML
Before you can embed all or part of ThoughtSpot, you must authenticate to ThoughtSpot using SAML
with the the public REST API call. After authentication, a URL is provided to call the desired visualization
and populate it into an iframe .
You must configure SAML on your ThoughtSpot instance before using this method.

Trusted authentication service
A ThoughtSpot installation can enable support for token-based authentication service. This allows an
installation to use a central authentication service rather than using ThoughtSpot to authenticate. In this
architecture, ThoughtSpot provides the service with a token that allows it to authenticate on behalf of
users.
A trusted authenticator application or service obtains a token from ThoughtSpot. This token is used to
obtain trust from other, third-party client applications that need access to ThoughtSpot. In the scenario
below, the trust authenticator forwards requests for ThoughtSpot data from client applications to
ThoughtSpot.

ThoughtSpot Application Integration Guide

Page 36

Understand embedding

February 08, 2019

A user already logged into client-application interacts with a ThoughtSpot embed point which causes the
following processes:
1.
2.
3.
4.
5.
6.

The client-side application requests a user token from the trusted authenticator.
The trusted authenticator requests user token from ThoughtSpot.
ThoughtSpot verifies the authenticator and returns a user token.
The authenticator returns the user token to the client.
The client forwards the user token to ThoughtSpot.
ThoughtSpot validates the token and returns information commensurate with that
authenticated user’s authorization.

Plan for Cross-Origin HTTP Requests (CORS)
Collecting user credentials from one application (domain) and sending them to another (such as
ThoughtSpot) can present security vulnerabilities such as a phishing attack. Cross-origin or crossdomain verification closes this vulnerability.
When embedding, you must enable CORS between your client application domain and the ThoughtSpot
domain. This protects your data, so that another actor cannot use the same URL to embed the
visualization in its own Web pages.

Decide if you need to change the feedback
email
ThoughtSpot has an automated feature that collects feedback from users and sends it to
support@thoughtspot.com . Depending on what and how you embed, user actions with your
embedded application can trigger feedback. You can continue to forward feedback in this manner or
direct the feedback to another email. To learn how to change the feedback email, see Manage the
feedback contact.

ThoughtSpot Application Integration Guide

Page 37

Understand embedding

February 08, 2019

Remove the ThoughtSpot branded footer
The ThoughtSpot footer appears by default in the ThoughtSpot application. It also appears with an
embed application that encompasses an individual pinboard or a full application. In embed applications
that are have a single visualization, you can ask your ThoughtSpot support engineer to disable the
footer.

ThoughtSpot Application Integration Guide

Page 38

Embed pinboard or visualization

February 08, 2019

Embed pinboard or visualization
The page explains, through an example, how to embed a visualization (table or chart) or pinboard from
ThoughtSpot in your own static Web page, portal, or application.
To build this sample, you need to have access to a text editor and a ThoughtSpot instance with a
visualization. You should also have some experience working with Javascript.

Get the link for an entire pinboard or single
visualization
This procedure assumes the pinboard with the visualization you want to embed already exists. If the
pinboard or visualization doesn’t exist, create it now before continuing.
1. Log in to ThoughtSpot from a browser.
2. Navigate to a visualization on the Pinboard tab.
3. Open a pinboard.
4. Copy the URL for the entire pinboard and for a single visualization.
If the object is a pinboard, click the ellipses icon (3 dots)

> Copy Link
Link.

The format for the link is: ::/#/embed/viz/

ThoughtSpot Application Integration Guide

Page 39

Embed pinboard or visualization

For a vizualization in a pinboard, click the ellipses icon (3 dots)

February 08, 2019

> Copy Link
Link.

The format for the link is: ::/#/embed/
viz//

Edit the test.html
You need to edit the page in your application or web page where you want to embed a ThoughtSpot
pinboard or visualization. For this example, you’ll get a copy of the test.html file.
1.
2.
3.
4.
5.
6.

Create an empty directory called test .
Save the test.html file to the test directory.
Download the ThoughtSpot JavaScript library.
Place the Javascript library in an api directory co-located with the test.html file.
Edit the test.html file in your favorite editor.
Scroll down to the Variables section (about line 37).
Here are the fields in the test.html file you need to edit.

var protocol = "THOUGHSPOT_PROTOCOL";
var hostPort = "HOST_PORT";
var pinboardId = "PINBOARD_ID";
var vizualizationId = "VIZUALIZATON_ID";

7. Edit each variable in the section and replace it with the IDs you copied from the pinboard.
For example, your URL may look similar to the following:

ThoughtSpot Application Integration Guide

Page 40

Embed pinboard or visualization

February 08, 2019

http://172.18.202.35:8088/#/embed/viz/061457a2-27bc-43a9-9754-0cd873691bf0/
9985fccf-b28d-4262-b54b-29619a38348e

This is a link copied from an individual visualization, the result in the file is:

var protocol = "http";
var hostPort = "172.18.202.35:8088";
var pinboardId = "061457a2-27bc-43a9-9754-0cd873691bf
0";
var vizualizationId = "9985fccf-b28d-4262-b54b-29619a38
348e";

The protocol ( http or https ) of your client and your ThoughtSpot instance should match.
You’ll use this identifier in the next part.
8. Save your changes and close the test.html file.

Enable CORS for your client domain
You must work with ThoughtSpot support to enable CORS between your client application domain and
the ThoughtSpot domain. If you don’t do this, you will receive an error message when test.html
attempts to load the embedded objects.
The test infrastructure uses Python’s simplehttpserver which runs, by default as localhost:8000 ,
this is information ThoughtSpot support will need. You can also just copy the test directory to an
existing web server. If you do this, you’ll need to DNS for the server when you contact Support.

Test the example page
You are almost ready to view your embedded pinboard and visualization. The fastest way to run a
webserver and test the code is using Python’s simplehttpserver . If you have Python on your system
you already have the simplehttpserver .
1. Log into ThoughtSpot.
In production, you would have added authentication code to your client. You haven’t done
that with this system. So, before you test, you’ll login to the ThoughtSpot. Successfully
logging in causes the system to create a session and an authentication key. Your browser has
this information and so when you load the test.html page in another tab, you won’t need
to authenticate again.
2. Change to your test directory.
3. Start the simplehttpserver web server.

python -m SimpleHTTPServer 8000

4. Open your browser’s Developer tools.

ThoughtSpot Application Integration Guide

Page 41

Embed pinboard or visualization

February 08, 2019

5. Navigate to the test page in your browser.
http://localhost:8000/test.html

You should see something similar to the following:

6. Check the browser console.
Success is appears in the console with a message similar to this:

test.html:60 Initialization successful.
test.html:113 http://172.18.202.35:8088/#/embed/viz/061
457a2-27bc-43a9-9754-0cd873691bf0
test.html:129 http://172.18.202.35:8088/#/embed/viz/061
457a2-27bc-43a9-9754-0cd873691bf0/9985fccf-b28d-4262-b54
b-29619a38348e

Troubleshooting embeds
If your embeds don’t load, open the developer tools on your browser. Look for errors in the page
loading, usually on the Console tab. If you see an error similar to:

No 'Access-Control-Allow-Origin' header is present on the reque
sted resource.

ThoughtSpot Application Integration Guide

Page 42

Embed pinboard or visualization

February 08, 2019

Typically you see this if the cross domain (CORS) setting was not completed correctly on your
ThoughtSpot cluster. Contact support@thoughtspot.com for more help.

ThoughtSpot Application Integration Guide

Page 43

Authentication flow with embed

February 08, 2019

Authentication flow with embed
If your ThoughtSpot system is configured for Security Assertion Markup Language (SAML) you can
enable Single Sign On (SSO) for your embed application.
Place the JS API library in the  section of the HTML on your Web page. Ensure that the JS API
script tag is the first script loaded in the page. You can see examples of this

Authenticate when the window is initialized
Your web page needs to authenticate by calling window.thoughtspot.initialize and waiting for the
onInitializationCallback to be called before embedding any ThoughtSpot visualizations or making
any ThoughtSpot REST API calls.
The JS API call window.thoughtspot.initialize can cause the entire Web page to be re-directed to
your Identity Provider (IDP). This order implies that you may not execute any of your application logic
before window.thoughtspot.initialize has called your callback.
Any redirection could interfere with your application logic. So, don’t embed any static ThoughtSpot
visualizations in your HTML. In other words, you should generate the ThoughtSpot visualizations
dynamically after window.thoughtspot.initialize has called your callback.
The onAuthExpiration is only available if you have at least one ThoughtSpot visualization iframe in
your web page.

Example of code flow
To authenticate with SSO.
1. Download the ThoughtSpot JavaScript library.
2. Include the library file into your web page’s  section:




4. Work with ThoughtSpot support to enable CORS between your client application domain and
the ThoughtSpot domain.
When this value is changed, the nginx service is restarted automatically to reflect the
change.
Now, you’re ready to either embed a visualization or use the REST API to get data from ThoughtSpot
and display it within your Web page or application.

ThoughtSpot Application Integration Guide

Page 45

Full application embedding

February 08, 2019

Full application embedding
Summary: Full embedding allows users to create ThoughtSpot
content in an embedded environment.
Fully embedding ThoughtSpot content gives your users the ability to:
•
•
•
•

create answers and pinboards
share objects with users
upload data and refresh uploaded data
relate uploaded data with existing worksheets

This is useful for supplying the full search experience into an iframe with different navigation views and
toggle options. However, there are limitations. Users won’t be able to:
• create worksheets or views.
• modify profiles.
• view the Help Center.
Before you try the technique, make sure you have read, Understand embedding in this section.

A single page with the full application
embedded
The following sample embed.html demonstrates how you might full embed app the application.

ThoughtSpot Application Integration Guide

Page 46

Full application embedding

February 08, 2019







ThoughtSpot Embed App







ThoughtSpot Application Integration Guide

Page 47

Full application embedding

February 08, 2019





The function updateIframeUrl(id) reflects the logic to change the src URL of the iframe when your
users clicks on different navigation buttons.

Hide the ThoughtSpot navigation bar
To hide the primary navigation, configure this:
• Make sure the app is in an