# Sisense Embed SDK Reference

Feature Availability

The Embed SDK is available on:

Sisense for Windows 8.1 or newer
Sisense for Linux L8.2.1 or newer

Some features in this reference are only available from Sisense version 8.1.1/L8.2.1 or higher - they are marked with the 8.1.1 and L8.2.1 badges, respectively.

The Sisense Embed SDK is a JavaScript library used for embedding Sisense Dashboards into web applications and facilitating the interaction between the host page and the embedded dashboard.

# Using the SDK

# Prerequisites

Make sure to read the Embed SDK documentation.
Ensure CORS is enabled (opens new window) on your Sisense web server.

# Importing the SDK

The SDK is bundled with the Sisense Web Server starting with Sisense v8.1; To use it on your web page or application, follow these steps:

Include the SDK file from your Sisense Web Server:
```
<script src="https://example.com/js/frame.js"></script>
```
(Replace https://example.com with the IP or DNS address of your Sisense Web Server)
Import the module:
```
const { SisenseFrame, enums } = window['sisense.embed'];
```
(enums is optional, and contains values for different options in the API)

# SisenseFrame Class

Main SDK Entry point - An instance of this class represents a single Sisense embedded iFrame on the host page, and provides the API for interacting with the embedded Sisense application.

The SDK can either wrap an existing iFrame element by passing the element property to the constructor, or generate an iFrame element automatically into any DOM element provided as the container argument of render().

Notes:

Application related methods such as getUser are contained under the app property. These are methods that relate to the entire Sisense application, regardless of the frame's current state.
Dashboard related methods such as applyFilters are contained under the dashboard property. These are methods that relate to the currently Dashboard loaded in the iFrame and to navigation between dashboards.
Each of the above objects (app and dashboard) have their own on and off methods to subscribe to events in either the global application or dashboard contexts, and each has specific supported events.

# Constructor

new SisenseFrame(init)

Create a new instance of SisenseFrame to interact with a Sisense iFrame-embedded application.

Name	Type	Description
`init`	`init`	Initial configuration for the frame

# Properties

Note: The properties below will only be available once the render() method was called.

Property	Type	Description
`id`	`string`	iFrame element's id
`url`	`string`	iFrame base URL
`element`	`HTMLElement`	iFrame DOM element

# Methods

# render

render([container], [hidden]) → Promise<null>

Create the iFrame according to current settings.

If an iFrame DOM element was provided in the constructor via the element property, container is optional and can be left as undefined/null; Otherwise, a DOM element is required, into which the iFrame element will be rendered.

Parameters

Name	Type	Default	Description
`[container]`	`DOMElement`		A container DOM element to render the iFrame into
`[hidden]`	`boolean`	`false`	Whether the iFrame should be rendered in hidden mode

Returns

A Promise that resolves with no data when the iFrame element has been rendered.

# show

show()

Show the iFrame element.

Parameters

N/A

Returns

N/A

# hide

hide()

Hide the iFrame element.

Parameters

N/A

Returns

N/A

# getSettings

getSettings() → uiSettings

Get the current UI settings for the iFrame.

Parameters

N/A

Returns

A uiSettings type object

# updateSettings

updateSettings(settings) → Promise

Update the frame's UI settings.

Parameters

Name	Type	Description
`settings`	`uiSettings`	UI settings to apply to the iFrame

Returns

A Promise that resolves with no data when the new settings have been applied

# getState

getState() → frameState

Get the current state of the frame, with information on what is currently displayed within it.

Parameters

N/A

Returns

A frameState type object

# getSize

getSize() → Promise<sizingInfo>

Get frame content sizing information

Parameters

N/A

Returns

A Promise that resolves with a sizingInfo object.

# app.on

app.on(eventName, eventHandler)

Subscribe a handler to an application event.

Parameters

Name	Type	Description
`eventName`	`string`	Name of event to subscribe to ¹
`eventHandler`	`function`	Event handler function

Returns

N/A

# app.off

app.off(eventName, eventHandler)

Un-subscribe a handler from an application event. The same event handler function must be passed as the eventHandler argument.

Parameters

Name	Type	Description
`eventName`	`string`	Name of event to unsubscribe from ¹
`eventHandler`	`function`	Event handler function to unsubscribe

# ¹ Supported events:

sisenseapploaded
appstatechanged

Returns

N/A

# app.getInfo

app.getInfo() → Promise.<AppInfo>

Get information about the Sisense application currently displayed in the iFrame.

Parameters

N/A

Returns

A Promise that resolves to the AppInfo type

# app.getUser

app.getUser() → Promise.<UserInfo>

Get information about the current user logged in to the Sisense application currently displayed in the iFrame.

Parameters

N/A

Returns

A Promise that resolves to the UserInfo type

# app.logout

app.logout()

Log out from Sisense.

The iFrame will automatically redirect to the login page, hence usually this will be called before the host page is navigated elsewhere or together with the hide() method to avoid showing the login page to the user.

Parameters

N/A

Returns

N/A

# app.setTheme L2021.3

app.setTheme(themeOid) → Promise

Applies the specified theme (by its oid) to the embedded Sisense UI. This action can be reverted using the app.clearTheme method.

Parameters

Name	Type	Description
`themeOid`	`string`	`oid` of theme to apply

Returns

A promise that resolves once the theme has been applied.

# app.clearTheme L2021.3

app.clearTheme() → Promise

Clears the custom theme applied with the app.setTheme method, reverting to the user's default theme.

Parameters

N/A

Returns

A promise that resolves once the theme has been cleared.

# dashboard.on

dashboard.on(eventName, eventHandler) → string

Subscribe a handler to a dashboard event.

Parameters

Name	Type	Description
`eventName`	`string`	Name of event to subscribe to ¹
`eventHandler`	`function`	Event handler function

# ¹ Supported Events

dashboardloaded
dashboardunloaded
dashboardfilterschanged
dashboardrefreshed
dashboardstylechanged
dashboardwidgetadded
sizechanged

Returns

N/A

# dashboard.off

dashboard.off(eventName, eventHandler)

Un-subscribe a handler from a dashboard event. The same event handler function must be passed as the eventHandler argument.

Parameters

Name	Type	Description
`eventName`	`string`	Name of event to unsubscribe from ¹
`eventHandler`	`function`	Event handler function to unsubscribe

# ¹ Supported Events

dashboardloaded
dashboardunloaded
dashboardfilterschanged
dashboardrefreshed
dashboardstylechanged
dashboardwidgetadded
sizechanged

Returns

N/A

# dashboard.open

dashboard.open(dashboardId, [editMode]) → Promise.<DashboardInfo>

Navigate the frame to a dashboard by the dashboard's OID. Calling this may trigger both dashboardunloaded and then dashboardloaded events.

Parameters

Name	Type	Default	Description
`dashboardId`	`string`		OID of dashboard to open
`[editMode]`	`booean`	`false`	Should dashboard be shown in edit mode

Returns

A Promise that resolves to the <DashboardInfo> type once the new dashboard is loaded

# dashboard.getCurrent

dashboard.getCurrent() → Promise.<DashboardInfo>

Get information about the current dashboard displayed in the iFrame, including a list of filters applied to it. If no dashboard is being displayed, the Promise will be rejected.

Parameters

N/A

Returns

A Promise that resolves to the <DashboardInfo> type

# dashboard.applyFilters

dashboard.applyFilters(filters, persist) → Promise.<Array.<Object>>

Apply (add or update) one or more filters to the current dashboard. If a filter already exists for the same dimension (field), it will be replaced. By default, Filter changes will not persist after refresh/reload and will not affect the current user's dashboard instance in Sisense, unless a true value is passed as the persist argument.

Parameters

Name	Type	Description
`filters`	`Array.<DashboardFilter>`	An array of filters to apply to the dashboard.
`persist`	`boolean`	Should the filter change be persisted.

Returns

Promise.<Array.<Object>> - An array containing all currently applied filters, after the operation is complete

# dashboard.removeFilters

dashboard.removeFilters(filters, persist) → Promise.<Array.<Object>>

Remove one or more filters from the current dashboard. Filters are matched using the dimension (field) name, so it is sufficient to provide just the jaql.dim property without the actual filter details to remove. By default, Filter changes will not persist after refresh/reload and will not affect the current user's dashboard instance in Sisense, unless a true value is passed as the persist argument.

Parameters

Name	Type	Description
`filters`	`Array.<DashboardFilter>`	An array of filters to remove from the dashboard.
`persist`	`boolean`	Should the filter change be persisted.

Returns

Promise.<Array.<Object>> - An array containing all currently applied filters, after the operation is complete

# dashboard.clearFilters L2022.1

dashboard.clearFilters(persist) → Promise

Clears all dashboard filters.
By default, Filter changes will not persist after refresh/reload and will not affect the current user's dashboard instance in Sisense, unless a true value is passed as the persist argument.

Parameters

Name	Type	Description
`persist`	`boolean`	Should the filter change be persisted.

Returns

Promise - A promise that resolves once the operation is complete

# dashboard.export

dashboard.export([mode]) → Promise

Trigger a dashboard export process - this command will open the export UI modal window within the iFrame, where the user can configure the export and download it.

Parameters

Name	Type	Default	Description
`[mode]`	`string`	`"pdf"`	Either `"pdf"` or `"png"` ¹

¹ Represented by enums.ExportMode.PDF and enums.ExportMode.PNG

Returns

A Promise that resolves with no data when the user closed the export window

# dashboard.openSimplyAsk L8.2.1

dashboard.openSimplyAsk()

Opens the SimplyAsk NLQ (opens new window) popup as a modal dialog within the iFrame.

Parameters

N/A

Returns

N/A

Example

sisenseFrame.dashboard.openSimplyAsk();

dashboard.share()

Opens the Share Dashboard popup as a modal dialog within the iFrame, allowing dashboard designers to share the dashboard directly from the embedded interface even if the dashboard toolbar element is hidden.

Parameters

N/A

Returns

N/A

Example

sisenseFrame.dashboard.share();

# dashboard.createWidget L2021.8

dashboard.createWidget()

Opens the New Widget popup as a modal dialog within the iFrame, allowing dashboard designers to create a new widget on the dashboard, even if the dashboard toolbar is hidden.

Parameters

N/A

Returns

N/A

Example

sisenseFrame.dashboard.createWidget();

# dashboard.createTextWidget L2021.8

dashboard.createTextWidget()

Creates a blank new Text Widget within the embedded dashboard, allowing dashboard designers to create a new text widget on the dashboard, even if the dashboard toolbar is hidden.

Parameters

N/A

Returns

N/A

Example

sisenseFrame.dashboard.createTextWidget();

# dashboard.new L2022.8

dashboard.new() → Promise.<DashboardInfo>

Creates a blank new dashboard and navigates to it, allowing dashboard designers to create a new dashboard, even if the navigation toolbar is hidden.

Parameters

N/A

Returns

A Promise that resolves to the <DashboardInfo> type once the new dashboard is created & loaded.

Example

sisenseFrame.dashboard.new();

widget.on(eventName, eventHandler) → string

Subscribe a handler to a widget event.

Parameters

Name	Type	Description
`eventName`	`string`	Name of event to subscribe to ¹
`eventHandler`	`function`	Event handler function

# ¹ Supported Events

widgetready
widgetloaded
widgetunloaded
widgetchanged
widgetsave

Returns

N/A

widget.off(eventName, eventHandler)

Un-subscribe a handler from a widget event. The same event handler function must be passed as the eventHandler argument.

Parameters

Name	Type	Description
`eventName`	`string`	Name of event to unsubscribe from ¹
`eventHandler`	`function`	Event handler function to unsubscribe

# ¹ Supported Events

widgetready
widgetloaded
widgetunloaded
widgetchanged
widgetsave

Returns

N/A

widget.open(dashboardId, widgetId, [editMode]) → Promise WidgetInfo

Navigate the frame to a widget by the dashboard and widget's OID. Calling this may trigger both widgetloaded and then widgetunloaded events.

Parameters

Name	Type	Default	Description
`dashboardId`	`string`		OID of dashboard containing the widget
`widgetId`	`string`		OID of widget to open
`[editMode]`	`booean`	`false`	Should dashboard be shown in edit mode

Returns

A Promise that resolves to the WidgetInfo type once the new dashboard is loaded

widget.getCurrent() → Promise.WidgetInfo

Get information about the current widget displayed in the iFrame. If no widget is being displayed, the Promise will be rejected.

Parameters

N/A

Returns

A Promise that resolves to the WidgetInfo type

widget.save([returnToDashboard]) → Promise.WidgetInfo

Applies changes to the widget, same as the "Apply" UI button would do, for cases when it is not visible. By default will keep the frame showing the widget. If true value is passed as the first argument, will automatically navigate back to the dashboard. Calling this may trigger both widgetsave and then widgetunloaded events.

Parameters

Name	Type	Default	Description
`[returnToDashboard]`	`booean`	`false`	Should dashboard be shown after save

Returns

A Promise that resolves to the WidgetInfo type once the widget is saved

# Events

# sisenseapploaded

Application Loaded event will fire when the Sisense application is loaded in the iFrame. At this point, app.getUser() and app.getInfo() become available.

Use constant enums.ApplicationEventType.LOADED.

Can only be used with app.on()/app.off()

Name	Type	Default	Description
`eventName`	`string`	`"sisenseapploaded"`	Event name

# appstatechanged L2022.6

Application State Changed event will fire when the Sisense application is changing state (navigating to a different view).

Below you can find a table of available states. This event allows you to react to navigation happening within the embedded Sisense application.

For example: When a user deletes a dashboard they are currently viewing, they will be navigated to the home page by default. If you wish to override this behavior, for example by navigating them to a different page in your host application (instead of the Sisense home page that is now embedded within), this event will allow you to detect when this navigation happens and handle it.

Use constant enums.ApplicationEventType.STATECHANGED.

Can only be used with app.on()/app.off()

Name	Type	Default	Description
eventName	`string`	`"appstatechanged"`	Event name
fromState	`string`		Previous state
toState	`string`		New state

Available states

State name	Description
`home`	Default home page ("all dashboards")
`home.folder`	Home page, focused on a specific folder
`dashboard`	Dashboard
`widget.edit`	Widget editor
`widget.new`	New widget wizard

Example

sisenseFrame.app.on(enums.ApplicationEventType.STATECHANGED, (args) => {
   if (args.toState.startsWith('home')) {
      // if user is entering the "home" view, navigate to a different page
      window.location = 'https://example.com/analytics/home';
   }
});