# 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 is great for simple embedding use cases. However, if your requirements involve something more complex than described in this article, Sisense has 2 additional embedding methods for entire dashboards or individual widgets, providing a more detailed API for a more interactive embedded experience.

To learn more, please refer to the Embedding Sisense 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.

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

# 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

# Additional References