# Embedding Dashboards in an iFrame

The quickest & easiest way to embed Sisense dashboards in your web application is with an iFrame element.

Sisense has built in support for this mode of embedding, with query parameters you can append to the dashboard's URL to adjust the UI for your embedding needs.

TIP

The iFrame method is great for simple embedding use cases. However, if your application has more complex requirements than what is described in this article, Sisense has a JavaScript library called Embed SDK which expands on the iFrame embedding capabilities, providing a rich API for a more interactive embedded experience.

To learn more, please refer to the Embed SDK Documentation page.

# Authentication in Embedded Dashboards and Widgets

All Sisense dashboards and widgets require authentication.

When embedding dashboards outside of the Sisense environment, usually the use case is to skip the Sisense authentication (login) page, and instead use SSO (Single Sign On) with existing corporate authentication. To read more on configuring Single Sign On in Sisense, click here (opens new window).

# Walkthrough

Follow the steps below to embed your first dashboard in mere minutes.

# 1. Getting the dashboard's URL for embedding

The easiest way to get a dashboard's URL is by navigating to that dashboard in the Sisense UI and simply copying the entire URL from your browser.

However, to construct the URL which might be required when dynamically choosing which dashboard to display, use the following template:

{protocol}://{hostname}[:{port}]/app/main#/dashboards/{dashboard_id}

For example:

https://example.com/app/main#/dashboards/5ec13529b61a73002db725d3

Dashboards in folders

If your dashboard is within a folder, and you copied the URL from the browser after opening the dashboard, you will need to delete the ?folder={folder id} query parameter from the URL and everything that follows, before continuing to the next step.

For example:

Original dashboard URL for dashboard within folder:

https://example.com/app/main#/dashboards/550952417404b2981a000029?folder=550955a27404b2981a00003b

Embedded URL for dashboard within folder:

https://example.com/app/main#/dashboards/550952417404b2981a000029?embed=true

# 2. Embedding a Dashboard

To embed the dashboard in your application, use an iFrame HTML element and append the query parameter embed=true to the URL retrieved in the previous step.

For example:

<iframe id="sisenseContainer" width="100%" height="100%" frameborder="0"
 src="https://example.com/app/main#/dashboards/5ec13529b61a73002db725d3?embed=true" scrolling="auto"></iframe>

When embed=true is appended to the URL, Sisense will display the dashboard in embedded mode which means all toolbars and panels will be hidden except for the right-side filters panel, and the dashboard will be shown in "view" mode (it cannot be modified or re-arranged).

# 3. Customizing the UI for embedding

By adding specific query parameters appended to the dashboard's URL, you can customize which parts of the Sisense UI are being displayed, and how the UI behaves. You can show panels otherwise hidden in embedded mode, switch the dashboard to "edit" mode, and even apply temporary dashboard filters - all using the query parameters in the URL.

For example, by appending the query parameter l=true you indicate that Sisense should show the left-side panel that contains the dashboard navigation:

https://example.com/app/main#/dashboards/5ec13529b61a73002db725d3?embed=true&l=true

TIP

You can append multiple parameters to the URL by separating them with the & character.

# 3.1. Applying Themes L2021.3

As part of the UI Customization & Themes (opens new window) feature available on Sisense for Linux L2021.3 or newer, you can apply any existing theme to the embedded dashboard by passing the theme's oid with the theme query parameter.

To get the available theme oids, you can use the

GET /api/v1/themes

REST API endpoint.

Then, use the oid field from the response as the value for the optional theme query parameter:

https://example.com/app/main#/dashboards/605c78b1316210002b2f8bb7?embed=true&theme=605b633dc24bb7001ae42fbb

You can also choose a theme when using the Embed Code (opens new window) feature, and this parameter will be included in the generated URL and sample code.

# 4. Using Edit Mode

As mentioned above, when embedding a Sisense dashboard using an iFrame the default behavior is "view" mode, but a query parameter can be used for "edit" mode.

View mode: Users can only view the dashboards and widgets, regardless of whether they are a viewer or a designer for that dashboard. In addition, Designer users can perform the actions available through the toolbar buttons of the dashboard/widget, such as duplicating and downloading dashboards, and renaming and deleting widgets. This mode is identical to "view mode" in the Sisense UI
Edit mode: Designer users can modify the dashboard - move and resize widgets and even edit them directly within the embedded iFrame. Viewers can still only view the dashboard.

As the default behavior is "view" mode, you don't need to do anything to enable it.

To enable "edit" mode, append the parameter edit=true to the URL. For example:

https://example.com/app/main#/dashboards/5ec13529b61a73002db725d3?embed=true&l=true&edit=true

Note that in edit mode, a designer will be able to click the "widget edit" button and navigate the iFrame to the widget editor UI. As that UI has different panels than the dashboard, the various available query parameters will have a different affect. See Available Query Parameters for more details.

# 5. Appending filters

You can provide an array of Sisense JAQL filters via the filter query parameter, as a URI-encoded string.

You can write the JAQL filters yourself or extract them from an existing dashboard.

That JAQL needs to be turned into a string and URI-encoded.

For example, this code will correctly encode the first widget in the currently viewed dashboard (you can run this in the browser's developer console):

// Get the first filter in the current dashboard
var filterObject = prism.activeDashboard.filters.item(0);
// Filters need to be in an array
var filtersArray = [filterObject];
// Serialize the filters array into a string
var filterString = JSON.stringify(filtersArray);
// Encode the string for use in a URI
var uriEncoded = encodeURIComponent(filterString);

This process will turn a JSON object like this:

[
    {
        "jaql": {
            "dim": "[Admissions.Death]",
            "filter": {
                "explicit": true,
                "multiSelection": true,
                "members": ["Yes"]
            },
            "collapsed": false,
            "title": "Death"
        }
    }
]

Into a string like this:

%5B%7B%20%22jaql%22%3A%20%7B%22dim%22%3A%22%5BAdmissions.Death%5D%22%2C%22filter%22%3A%7B%22explicit%22%3Atrue%2C%22multiSelection%22%3Atrue%2C%22members%22%3A%5B%22Yes%22%5D%7D%2C%22collapsed%22%3Afalse%2C%22title%22%3A%22Death%22%7D%7D%5D

Which can then be appended to the iFrame's URL as the query parameter filter:

https://example.com/app/main#/dashboards/5ec13529b61a73002db725d3?embed=true&filter=%5B%7B%20%22jaql%22%3A%20%7B%22dim%22%3A%22%5BAdmissions.Death%5D%22%2C%22filter%22%3A%7B%22explicit%22%3Atrue%2C%22multiSelection%22%3Atrue%2C%22members%22%3A%5B%22Yes%22%5D%7D%2C%22collapsed%22%3Afalse%2C%22title%22%3A%22Death%22%7D%7D%5D

# 6. Using Web Access Tokens L2021.10

In Sisense for Linux versions L2021.10 or newer, you can use Web Access Tokens together with iFrame embedding as an alternative to standard authentication methods such as SSO.

Web Access Token

For more information, please refer to the Web Access Token documentation (opens new window)

For embedding with iFrames, the WAT is used in the same way as described in the WAT documentation - the token is inserted as part of the URL path:

https://{host}:{port}/wat/{WebAccessToken}/app/main#/dashboards/{DashboardOid}?embed=true

For example:

http://example.com:30845/wat/eyJhbGciOtT0[…]pyjKglx.F5eR8BZddcjNLYD1DBEQpA/app/main#/dashboards/5ec13529b61a73002db725d3?embed=true

# Available Parameters

Remember: all of the parameters below are optional and can be combined!

Name	Type	In Dashboards	In Widgets
`embed`	`boolean`	Shows the dashboard in embedded mode	Shows the widget in embedded mode
`edit`	`boolean`	Enables dashboard designers to edit the dashboard	N/A
`h`	`boolean`	Show/hide the environment header	Show/hide the environment header
`t`	`boolean`	Show/hide the dashboard toolbar	Show/hide the widget toolbar
`l`	`boolean`	Show/hide the Navigation Panel to the left	Show/hide the data panel to the left
`r`	`boolean`	Show/hide the filter panel to the right	Show/hide the filter and design panel to the right
`filter`	`string`	Adds temporary filters to the dashboard. See Appending filters.	N/A
`theme`	`string`	Applies the provided theme (by `oid`) to the dashboard	Applies the provided theme (by `oid`) to the widget

# Embedding Dashboards in an iFrame

# Authentication in Embedded Dashboards and Widgets

# Walkthrough

# 1. Getting the dashboard's URL for embedding

# 2. Embedding a Dashboard

# 3. Customizing the UI for embedding

# 3.1. Applying Themes L2021.3

# 4. Using Edit Mode

# 5. Appending filters

# 6. Using Web Access Tokens L2021.10

# Available Parameters

SISENSE

SUPPORT

RESOURCES