Liveboard export API

Liveboard export API

To programmatically download a Liveboard or specific visualizations from a Liveboard as a PDF file, use the /tspublic/v1/export/pinboard/pdf.

Note

To remove ThoughtSpot logos from the exported PDFs, contact your ThoughtSpot team.

Supported operations🔗

API endpointAvailable from

POST /tspublic/v1/export/pinboard/pdf
Downloads a Liveboard or specific visualizations from a Liveboard as a PDF file.

ThoughtSpot Cloud ts7.april.cl
ThoughtSpot Software 7.1.1

Required permissions🔗

You must have at least view access to the Liveboard object.

Resource URL🔗

POST /tspublic/v1/export/pinboard/pdf

Request parameters🔗

Form parameterDescriptionDefault

id

String. GUID of the Liveboard to download

none

visualization_ids

String. Array of GUIDs of the visualizations to include in the PDF in the JSON array format. For example, ['aab9eb75-d295-4a79-ac37-4a37c1cce0b3', '039943a7-77cb-4fa1-a8a2-785a2b5ebe28']. If you have specified the visualization IDs, make sure you set the layout_type parameter to VISUALIZATION.

none

transient_pinboard_content

String. If the Liveboard has unsaved changes, pass this parameter in the browser fetch request.

none

layout_type

String. Layout type for the PDF. Valid values are PINBOARD and VISUALIZATION. For PINBOARD, the PDF uses the same layout as the Liveboard UI. For VISUALIZATION, the PDF has one visualization for each page.

PINBOARD

orientation

String. Page orientation for the PDF. Valid values are PORTRAIT and LANDSCAPE.

LANDSCAPE

truncate_tables

Boolean. When set to true, only the first page of the tables is displayed in the PDF. This setting is applicable only if the layout_type parameters is set to VISUALIZATION

false

include_logo

Boolean. Include customized wide logo if available in the footer

true

footer_text Optional

String. Footer text to include in the footer of each page of the PDF.

none

include_page_number

Boolean. When set to true, the page number is included in the footer of each page.

true

include_cover_page

Boolean. When set to true, a cover page with the Liveboard title is added in the PDF.

true

include_filter_page

Boolean. When set to true, a second page with a list of all applied filters is added in the PDF

true

Download transient content🔗

Liveboard data with unsaved changes🔗

To download or retrieve a Liveboard with unsaved changes, pass the transient_pinboard_content script with getExportRequestForCurrentPinboard method in the browser fetch request.

function getExportRequestForCurrentPinboard(frame: HTMLIframeElement): Promise<string>;

The promise returned resolves to a string that contains the transient Liveboard content, which is encoded as JSON and is sent to the Liveboard API endpoint with the transient content key. This content resembles the current Liveboard as is, including the unsaved changes if any, including unsaved changes to the following:

  • Liveboard filters

  • Runtime filters applied on visualizations on a Liveboard

  • Liveboard layout

If the new Liveboard experience is enabled, the transient content includes ad hoc changes to visualizations such as sorting, toggling of legends, and data drill down.

Sample browser fetch request🔗

< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe>
< script src = "/path/to/liveboard.js" > < /script>
< script >
    const embed = new LiveboardEmbed("#embed", {
        frameParams: {},
    });
    async function liveboardData() {
    const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard);
    const liveboardDataResponse = await fetch("https://ts_host:port/callosum/v1/tspublic/v1/pinboarddata", {
        method: "POST",
        body: createFormDataObjectWith({
            "transient_pinboard_content": transientPinboardContent,
        }),
    });
 }
< /script>

Sample browser fetch request with Visual Embed SDK🔗

< iframe src = "http://ts_host:port/" id = "ts-embed" > </iframe>
< script src="/path/to/liveboard.js" > < /script>
< script >
    const embed = new LiveboardEmbed("#embed", {
        frameParams: {},
	});
    async function downloadPDF() {
	const transientPinboardContent = await embed.trigger(HostEvent.getExportRequestForCurrentPinboard);
	const pdfResponse = await fetch("https://ts_host:port/callosum/v1/tspublic/v1/export/pinboard/pdf", {
		method: "POST",
		body: createFormDataObjectWith({
			"layout_type": "PINBOARD",
			"transient_pinboard_content": transientPinboardContent,
		}),
	});
  }
< /script>

Sample browser fetch request without Visual Embed SDK🔗

This example calls the getExportRequestForCurrentPinboard function from the api.js file used in the legacy embed method.

< iframe src = "http://ts_host:port/" id = "ts-embed" > < /iframe>
< script src = "/path/to/ts-api.js" > < /script>
< script >
    const tsFrame = document.getElementById("ts-embed");
    async function downloadPDF() {
        const transientPinboardContent = await thoughtspot.getExportRequestForCurrentPinboard(tsFrame);
        const pdfResponse = await fetch("http://ts_host:port/callosum/v1/tspublic/v1/export/pinboard/pdf", {
            method: "POST",
            body: createFormDataObjectWith({
                "layout_type": "PINBOARD",
                "transient_pinboard_content": transientPinboardContent,
            }),
        });
        // Do something with pdfResponse.blob()
    }
< /script>

Example request🔗

Make sure the API request has the following headers:

  • The Accept header is set as Accept: application/octet-stream

  • The Content-type header set as Content-type: multipart/form-data

  • The X-requested-by header set as X-Requested-By: ThoughtSpot

cURL
 curl --location --request POST 'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/export/pinboard/pdf' \
--header 'Content-Type: multipart/form-data \
--header 'Accept: application/octet-stream' \
--header 'X-Requested-By: ThoughtSpot' \
--header 'Cookie: JSESSIONID=71cc2672-7ead-4480-be7d-b6ad52023e98; userGUID=59481331-ee53-42be-a548-bd87be6ddd4a; Callosum-Download-Initiated=false' \
--form 'id="061457a2-27bc-43a9-9754-0cd873691bf0"' \
--form 'layout_type="PINBOARD"' \
--form 'orientation="LANDSCAPE"' \
--form 'truncate_tables="false"' \
--form 'include_logo="true"' \
--form 'include_page_number="true"' \
--form 'include_filter_page="true"' \
--form 'include_cover_page="true"'
Request URL
https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/export/pinboard/pdf

Example response🔗

The response appears in the form of a raw pdf file. The response type is application/octet-stream.

Runtime filters🔗

You can modify the API’s output by passing runtime filters as parameters in the resource URL.

For example:

https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/export/pinboard/pdf?col1=COL_NAME1&op1=OP_TYPE1&val1=VALUE1&coln=COL_NAMEn&opn=OP_TYPEn&valn=VALUEn

You can add more than one filter by specifying col2, op2, val2, and so on.

ParameterDefinition

col<n>

Name of the column to filter on.

op<n>

{IN, EQ, NE, LT, LE…​}

val<n>

Value of the column to filter on.

Note
 These parameters are case-insensitive. For example, EQ, eq, and eQ have the same result.

Runtime filter operators🔗

OperatorDescriptionNumber of Values

EQ

equals

1

NE

does not equal

1

LT

less than

1

LE

less than or equal to

1

GT

greater than

1

GE

greater than or equal to

1

CONTAINS

contains

1

BEGINS_WITH

begins with

1

ENDS_WITH

ends with

1

BW_INC_MAX

between inclusive of the higher value

2

BW_INC_MIN

between inclusive of the lower value

2

BW_INC

between inclusive

2

BW

between non-inclusive

2

IN

is included in this list of values

multiple

Response codes🔗

HTTP status codeDescription

200

Streaming output for Liveboard pdf

400

Invalid parameter values

403

No read access for Liveboard

404

Object not found