...

If your dashboard is installed locally with all the default settings, to access the example go to http://localhost:8224/pi_embed_example/.

Embedding A Panintelligence Chart

Step 1 - Ensure your dashboard is running in HTTPS

See Configuring HTTPS for more information.

Step 2 - Configuring the Dashboard

By default, embedding the dashboard in an iframe will no longer work without configuration. This is by design to provide the most secure out of the box configuration.

We have implemented click-jacking protection in the form of the recommended 'frame-ancestors'. By default, this is configured to disallow any embedding from any site. This can be changed via the Panintelligence Configuration Tool.

Using the Configuration Tool

On Windows

You can get to the Configuration Tool via the Start menu:

...

On Linux

Double click configuration-tool-GUI.AppImage.

...

Editing the CORS / Frame Ancestors / Trusted Hosts and the Cookie settings

...

...

Using environment variables

Settings can be applied via environment variables and this is true for these fields too:

...

Using the configuration file

These settings can also be applied via a configuration file to support unattended installs and GUI-less environments.

...

...

Step 3 - Getting a token

You can run a working example by following this repository:

...

var url = "https://localhost:8224/" //Change this to your url
var username = "admin" //Change this to the user you want to login as
var password = "dashboard" //Change this to user's password
$.ajax({
    // POST to the API with username and password to swap that for a session token
    type: "POST",
    url: url + apiToken,
    contentType: "application/json",
    xhrFields: {
        withCredentials: true
    },
    beforeSend: function (xhr, settings) {
        xhr.setRequestHeader("Authorization", "basic " + username + ":" + password);
    },
    success: function (data) {
        login(data.token);
    }
});

function login(token) {
    // Issue an ajax request to embeddedTokenLogin with the token in the header to pick up the session cookies
    $.ajax({
        type: "GET",
        url: url + "pi/auth/embeddedTokenLogin",
        contentType: "text/HTML",
        xhrFields: {
            withCredentials: true
        },
        beforeSend: function (xhr, settings) {
            // This is the header we need to set
            xhr.setRequestHeader("Authorization", "bearer " + token);
        },
        success: function (data) {
            // Once we have a succesful ajax request with authentication we can load the charts in the iframes
        }
    });
}

Step 4 - Embedding

Chart

To embed a chart you’ll need an iframe and the chart’s ID. You can get this by going into the dashboard, clicking chart tools at the top-right of a chart cell and selecting the i icon:

...

function login(token) {
    // Issue an ajax request to embeddedTokenLogin with the token in the header to pick up the session cookies
    $.ajax({
        type: "GET",
        url: url + "pi/auth/embeddedTokenLogin",
        contentType: "text/HTML",
        xhrFields: {
            withCredentials: true
        },
        beforeSend: function (xhr, settings) {
            // This is the header we need to set
            xhr.setRequestHeader("Authorization", "bearer " + token);
        },
        success: function (data) {
            document.querySelector("#chart_iframe").src = "https://your.dashboard.com/pi/chart#chart-filter/481__1"
        }
    });
}

Category

We have embedded a chart but what if we want to embed a category? Embedding a category isn’t actually any different from embedding the whole dashboard (yes, you can do that too!).

Below are the different category modes that you can use when embedding the categories:

categoryMode=0: Normal

This will show the category exactly as it appears on the dashboard.

...

categoryMode=1: Headless Single Category

This will hide the category header and the category list.

...

categoryMode=2: Single Category

This will show the category header options but will still hide the category list.

...

categoryMode=3 Headless Normal

This will remove the header but keep the category list.

...

Interacting with the left & right drawers

One thing to note with the different embed options is that you can actually use JavaScript’s post message API to open the category list / filter panel within the various modes if you wish to (and if they’re available in that category mode).

...

The full range of messages the dashboard interprets can be found in our API Embed Examples and they include opening, closing, pinning and unpinning drawers.

Using filters to filter a chart via JavaScript while embedded

With Category Filters (whole category)

Adding filters

The dashboard supports embedding with default category filters selected.

Refer to Embedded Categories for details. If changing the filter values outside of the dashboard is needed, we will need to implement functions to be called outside of an iframe, so that filter values are supplied to the dashboard elegantly.

The current structure of the URL for category filters

...

https://localhost:8224/pi/#PA-CA###category/141__0/c-o-p=eq__[[Department]]{{dev}}/*$*gt__[[Number]]{{100}}

With Temporary Filters (per chart)

Current URL Structure

...

https://localhost:8224/pi/chart#chart-filter/330__1/t-f-p=eq__[[Department]]{{dev}}/*$*gt__[[Number]]{{100}}

Types of filters

...

Delimiters

/*$* - Used to separate multiple criteria items

:::: - Used to separate values within {{}}, used for Between/Not Between and In/Not In list criteria

Gotchas

CORS errors?

If you see an error in the Javascript Console such as:

...

Then you need to review your frame-ancestors settings (via the config tool or via the config file).

If everything still looks correct, then make sure you’re not using any browser addon that attempts to bypass CORS.

Login screen keeps showing / looping after logging in?

Check your cookie settings

This usually means your cookie settings aren’t set up correctly. Review your cookie settings (via the config tool or via the config file).

Is your dashboard behind a proxy?

If the cookie settings look correct, it might be that your dashboard is being served via http and the proxy in front of it will be doing the ssl communication. If that's the case, you'll need to tell the dashboard that it's behind a proxy and that the proxy is doing https. This is done by editing your proxy settings in one of three ways.

Using the configuration tool

...

Editing the configuration file

Edit dashboard.json configuration file:

{
        "proxy": {
            "enabled": true,
            "scheme": "https",
            "secure": true,
            "host": "proxy-host.com",
            "port": 443
        }
}

Using environment variables

PI_PROXY_ENABLED=true
PI_PROXY_SCHEME=https
PI_PROXY_IS_SECURE=true
PI_PROXY_HOST="proxy-host.com"
PI_PROXY_PORT=443

Is your dashboard a try-pi or an AMI?

This is the same scenario as if having the dashboard behind a proxy.

...

Then make sure you reboot your instance.

Check the URL being embedded

We’ve noticed the cookie doesn’t get recognised if there’s a double-slash in the URL of the iframe.

For example: https://dashboard//pi/ or https://dashboard/pi// instead of https://dashboard/pi/

Embedded Sub Domains

If you have subdomains, the hostname in the custom trusted hosts will need to be entered as *.hostname *.hostname 
 

...