# 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

# 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:

  1. Include the SDK file from your Sisense Web Server:

    <script src="http://1.2.3.4:8081/js/frame.js"></script>
    

    (Replace 1.2.3.4 with the IP or DNS address of your Sisense Web Server)

  2. 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 subsctibe to 1
eventHandler function Event handler function
# 1 Supported events:

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 unsubsctibe from 1
eventHandler function Event handler function to unsubsctibe
# 1 Supported events:

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

# dashboard.on

dashboard.on(eventName, eventHandler)string

Subscribe a handler to a dashboard event.

Parameters

Name Type Description
eventName string Name of event to subsctibe to 1
eventHandler function Event handler function
# 1 Supported Events

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 unsubsctibe from 1
eventHandler function Event handler function to unsubscribe
# 1 Supported Events

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 other users viewing the same dashboard, 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 other users viewing the same dashboard, 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.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" 1

1 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 Beta

dashboard.openSimplyAsk()

Opens the SimplyAsk NLQ popup as a modal dialog within the iFrame.

Parameters

N/A

Returns

N/A

Example

sisenseFrame.dashboard.openSimplyAsk();

# widget.on 8.1.1 L8.2.1

widget.on(eventName, eventHandler)string

Subscribe a handler to a widget event.

Parameters

Name Type Description
eventName string Name of event to subsctibe to 1
eventHandler function Event handler function
# 1 Supported Events

Returns

N/A

# widget.off 8.1.1 L8.2.1

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 unsubsctibe from 1
eventHandler function Event handler function to unsubscribe
# 1 Supported Events

Returns

N/A

# widget.open 8.1.1 L8.2.1

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 8.1.1 L8.2.1

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 8.1.1 L8.2.1

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

# dashboardloaded

Dashboard Loaded event will fire when a new dashboard is loaded in the iFrame.

Use constant enums.DashboardEventType.LOADED.

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

Properties

Name Type Default Description
eventName string "'dashboardloaded'" Event name
dashboard DashboardInfo Dashboard information

# dashboardunloaded

Dashboard un-loaded event will fire when a dashboard is being unloaded from the iFrame, such as when navigating to a different dashboard or transitioning to a differnt state.

Use constant enums.DashboardEventType.UNLOADED.

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

Properties

Name Type Default Description
eventName string "'dashboardunloaded'" Event name
dashboard DashboardInfo Dashboard information

# dashboardfilterschanged

Dashboard filters changed event will fire when the dashboard filters have been modified.

Use constant enums.DashboardEventType.FILTERS_CHANGED.

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

Properties

Name Type Default Description
eventName string "'dashboardfilterschanged'" Event name
dashboard DashboardInfo Dashboard information

# dashboardrefreshed

Dashboard refreshed event will fire when the dashboard has been refreshed (and widget queries re-run), usually as a result of filters being changed.

Use constant enums.DashboardEventType.REFRESHED.

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

Properties

Name Type Default Description
eventName string "'dashboardrefreshed'" Event name
dashboard DashboardInfo Dashboard information

# dashboardstylechanged

Dashboard style changed event will fire when the dashboard's style has been changed.

Use constant enums.DashboardEventType.STYLE_CHANGED.

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

Properties

Name Type Default Description
eventName string "'dashboardstylechanged'" Event name
dashboard DashboardInfo Dashboard information

# dashboardwidgetadded

Dashboard widget added event will fire when a new widget is added to the dashboard.

Use constant enums.DashboardEventType.WIDGET_ADDED.

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

Properties

Name Type Default Description
eventName string "'dashboardwidgetadded'" Event name
dashboard DashboardInfo Dashboard information

# sizechanged

Dashboard size changed event will fire when the dashboard size changes.

Use constant enums.DashboardEventType.SIZECHANGED.

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

Properties

Name Type Default Description
eventName string "'sizechanged'" Event name

# widgetready 8.1.1 L8.2.1

Widget Loaded event will fire when a widget displayed in the iFrame is rendered and ready

Use constant enums.WidgetEventType.READY.

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

Properties

Name Type Default Description
eventName string "'widgetready'" Event name
widget WidgetInfo Widget information

# widgetloaded 8.1.1 L8.2.1

Widget Loaded event will fire when a new widget is loaded in the iFrame.

Use constant enums.WidgetEventType.LOADED.

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

Properties

Name Type Default Description
eventName string "'widgetloaded'" Event name
widget WidgetInfo Widget information

# widgetunloaded 8.1.1 L8.2.1

Widget un-loaded event will fire when a widget is being unloaded from the iFrame, such as when navigating to a different widget or transitioning to a differnt state.

Use constant enums.WidgetEventType.UNLOADED.

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

Properties

Name Type Default Description
eventName string "'widgetunloaded'" Event name
widget WidgetInfo Widget information

# widgetchanged 8.1.1 L8.2.1

Widget metadata changed event will fire when the current widget's metadata has been changed, such as new dimensions added or widget filters removed

Use constant enums.WidgetEventType.CHANGED.

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

Properties

Name Type Default Description
eventName string "'widgetchanged'" Event name
widget WidgetInfo Widget information

# widgetsave 8.1.1 L8.2.1

Widget Saved event will fire when the widget is saved, either via UI button or the widget.save() function

Use constant enums.WidgetEventType.SAVE.

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

Properties

Name Type Default Description
eventName string "'widgetsave'" Event name
widget WidgetInfo Widget information

# Types

# frameState

Frame state properties

Properties

Name Type Description
mode string Current mode ('home', 'dashboard') 1
dashboard string OID of the current dashboard displayed, if applicable

1 Represented by enums.FrameStateMode.HOME and enums.FrameStateMode.DASHBOARD

# sizingInfo

Frame sizing information

Properties

Name Type Description
header.width integer header width
header.height integer header height
toolbar.width integer toolbar width
toolbar.height integer toolbar height
leftpane.width integer leftpane width
leftpane.height integer leftpane height
rightpane.width integer rightpane width
rightpane.height integer rightpane height
midpane.width integer midpane width
midpane.height integer midpane height
content.width integer content width
content.height integer content height

# uiSettings

Sisense UI settings, defining which panels are displayed in the iFrame

Properties

Name Type Default Description
[showToolbar] boolean false Should the toolbar be displayed?
[showLeftPane] boolean false Should the left panel be displayed?
[showRightPane] boolean false Should the right panel be displayed?
# Panels in Dashboard mode
  • Toolbar: dashboard header
  • Left Pane: dashboard navigation panel
  • Right Pane: dashboard filters panel

# init

Initial configuration required by the SisenseFrame() constructor.

Properties

Name Type Description
[id] string An optional ID to assign to the iFrame element (if not specified, a random GUID will be assigned). Only applicable when iFrame is created by the SDK, ignored otherwise.
url string Base URL of the Sisense application. Includes only the protocol, hostname and port, for example: https://1.2.3.4:8081
[state] initState Initial state for the iFrame to load in
[settings] uiSettings Initial UI settings
[element] HTMLElement An iFrame element to attach to. If not specified, iFrame will be created by the SDK
[editMode] boolean Whether the embedding component should initially load in editMode - defaults to false.

# initState

An initial state for the iFrame to load in.

Properties

Name Type Description
[dashboard] string OID of the dashboard to open. If not provided, home page will be opened
[widget] string OID of the widget to open. Must be provided alongside a dashboard OID. 8.1.1 L8.2.1

# AppInfo

Application info object.

Properties

Name Type Description
version string Current Sisense version
isTrial boolean True if the Sisense application is a trial version

# UserInfo

User info object.

Properties

Name Type Description
oid string User's ID
email string User's email
username string User's username
firstName string User's first name
lastName string User's last name
role object
role.oid string User's role ID
role.name string User's role title

# DashboardInfo

Dashboard Response Object

Properties

Name Type Description
oid string Dashboard OID
title string Dashboard title
description string Dashboard description
instanceType string "owner" or "user" 1
owner string Dashboard owner user OID
userId string Dashboard user OID (who's version of the dashboard is loaded)
datasource Datasource Dashboard's primary datasource
filters Array.<DashboardFilter> Dashboard filters array
created Date Dashboard creation time
lastUpdated Date Dashboard last update
lastUsed Date Dashboard last used
lastOpened Date Dashboard last opened

1 Represented by enums.DashboardInstanceType.OWNER and enums.DashboardInstanceType.USER

# WidgetInfo 8.1.1 L8.2.1

Widget Response Object

Properties

Name Type Description
oid string Widget OID
title string Widget title
type string Widget type
subtype string Widget subtype
owner string Widget owner OID
userId string Instance user OID
created Date Widget creation time
lastUpdated Date Dashboard last update
lastUsed string Dashboard last used
tags string[] Widget tags
instanceType string "owner" or "user" 1
datasource Datasource Widget's datasource
dashboardid string Dashboard OID
queryStartTime Date widget's last query start time
metadata MetadataItem[] Widget metadata
data object[][] Widget data
jaqlQuery string Widget JAQL

1 Represented by enums.WidgetInstanceType.OWNER and enums.WidgetInstanceType.USER

# Datasource

Dashboard datasource Object

Properties

Name Type Description
title string Datasource title
fullname string Datasource fullname
id string Datasource id
address string Datasource address
database string Datasource database name

# DashboardFilter

Dashboard filter Object

Properties

Name Type Description
disabled boolean Is filter disabled
isCascading boolean Is a cascading filter
jaql Object Filter JAQL (See JAQL reference)

# Enums

# FrameStateMode

  • enums.FrameStateMode.HOME: 1
  • enums.FrameStateMode.DASHBOARD: 2
  • enums.FrameStateMode.WIDGET: 3

# DashboardInstanceType

  • enums.DashboardInstanceType.OWNER: 'owner'
  • enums.DashboardInstanceType.USER: 'user'

# WidgetInstanceType 8.1.1 L8.2.1

  • enums.WidgetInstanceType.OWNER: 'owner'
  • enums.WidgetInstanceType.USER: 'user'

# DashboardEventType

  • enums.DashboardEventType.LOADED: 'dashboardloaded'
  • enums.DashboardEventType.UNLOADED: 'dashboardunloaded'
  • enums.DashboardEventType.FILTERS_CHANGED: 'dashboardfilterschanged'
  • enums.DashboardEventType.REFRESHED: 'dashboardrefreshed'
  • enums.DashboardEventType.STYLE_CHANGED: 'dashboardstylechanged'
  • enums.DashboardEventType.WIDGET_ADDED: 'dashboardwidgetadded'
  • enums.DashboardEventType.SIZECHANGED: 'sizechanged'

# WidgetEventType 8.1.1 L8.2.1

  • enums.WidgetEventType.READY: 'widgetready'
  • enums.WidgetEventType.LOADED: 'widgetloaded'
  • enums.WidgetEventType.UNLOADED: 'widgetunloaded'
  • enums.WidgetEventType.SAVE: 'widgetsave'
  • enums.WidgetEventType.CHANGED: 'widgetchanged'

# ExportMode

  • enums.ExportMode.PDF: 'pdf'
  • enums.ExportMode.PNG: 'png'

# ApplicationEventType

  • enums.ApplicationEventType.LOADED: 'sisenseapploaded'

# Additional References