...
Table of Contents | ||||
---|---|---|---|---|
|
You can find a live code example that details how to embed the dashboard in your dashboard installation.
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:
...
Or by navigating to the Dashboard installation folder. On Windows, the default location is C:\Program Files\Dashboard\Dashboard
...
Open the PortSelector folder.
...
Right click ‘admin.exe’ and choose ‘Run as administrator’.
Click ‘Stop Services and Enter Admin’
...
Click the Advanced tab and configure according to your security preferences.
...
:
...
Info |
---|
Please ensure that you run |
On Linux
Double click configuration-tool-GUI.AppImage
.
...
Editing the CORS / Frame Ancestors / Trusted Hosts and the Cookie settings
...
Info |
---|
If you need embedding to work with Internet Explorer, you must set |
From the Trusted Hosts dropdown you’ll see the following values:
none
: No embedding allowed
...
self
: Embedding allowed from the same host
...
custom
: Embedding allowed from the hosts specified in the space separated list
...
This can also be configured automatically with the unattended install config file.
Step 2 - Edit your html page
Change the value of url
to your server's destination.
//Change this to your server
...
Note |
---|
Protocol (http/https) is required for trusted hosts / frame ancestors when using a wildcard. |
Using environment variables
Settings can be applied via environment variables and this is true for these fields too:
Code Block |
---|
PI_TOMCAT_FRAME_ANCESTORS="http://localhost:5000 https://my.awesome.app"
PI_TOMCAT_COOKIE_SECURE=true
PI_TOMCAT_COOKIE_SAMESITE=none |
Info |
---|
If you need embedding to work with Internet Explorer, you must set |
Note |
---|
Protocol (http/https) is required for trusted hosts / frame ancestors when using a wildcard. |
Using the configuration file
These settings can also be applied via a configuration file to support unattended installs and GUI-less environments.
To do this, find or create a file named dashboard.json
next to the configuration tool:
...
Note |
---|
NOTE: When using the configuration tool by the command line and you’re specifying a configuration file, you must specify an absolute path to it (not a relative path).
|
Then edit it using your favourite editor. You’ll need to change tomcat.cookies.secure
, tomcat.cookies.sameSite
and security.trustedHosts
.
...
Info |
---|
If you need embedding to work with Internet Explorer, you must set |
Note |
---|
Protocol (http/https) is required for trusted hosts / frame ancestors when using a wildcard. |
Step 3 - Getting a token
You can run a working example by following this repository:
In our examples, we’re doing this in the frontend just so you can follow a full example.
Note |
---|
However do not do this in production, you’ll be exposing your password! |
Typically your backend communicates with the dashboard in order to get the token. Once in place, your frontend then just uses it.
You can use our API to fetch a token for any user. Below we’ve got an example in javascript using jquery:
Code Block |
---|
var url = "https://localhost:8224/"; Change the login details to the user you want to login as. //Change this to your url var username = "admin" //Change this to the user you want to login as varusername password = "admin dashboard"; //Change this to user'spassword var password = "dashboard"; Change the chart ID in |
//Change 157__1 to the chart ID you want to see var chartFragment = "#chart-filter/157__1"; |
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:
...
Then copy the code snippet:
...
Code Block |
---|
<iframe id="chart_iframe" src='https://your.dashboard.com/pi/chart#chart-filter/481__1' width="500" height="500"></iframe> |
You should probably only update/show the iframes once the user has been logged in.
That would change the login code to be more like:
Code Block |
---|
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"
}
});
} |
Limiting drill levels on embedded charts
When embedding a chart that contains multiple drill levels, it is possible to use the query parameters “drillStart” and “drillEnd” in the URL to limit the drill levels that a user can see.
When using drillStart, the URL will also need to be configured to include the chart ID and hierarchy position of each chart that is being skipped and the chart at the drillStart level. These must be separated by the !$! delimiter when adding multiple levels. When drilling to the top, the user will return the the level defined as the drillStart parameter.
It is possible to use the parameters individually or together. The parameters are 0 indexed - with the first hierarchy in the chart corresponding to drill level 0. The functionality will also work for dynamic drill conditions.
Info |
---|
The below url would allow the user to see drill levels 1, 2 and 3 (i.e the 2nd, 3rd and 4th hierarchy levels) of the chart: http://localhost:1234/pi/chart/?drillStart=1&drillEnd=3#chart-filter/251__1/d-f-p=251__0/!$!251__1 *Location and syntax of the query parameters. *Example of identifiers added to view level 1 (2nd hierarchy level ) of the given chart. |
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 left drawer tag will open the category list as long as the embed mode allows for the category list to be active (Options 0 and 3)
...
. To interact with it you can use something like below:
Code Block |
---|
targetWindow.postMessage("open-drawer:left"); |
The right drawer tag will open the filter panel for every embed mode available. Similarly, you can open it using the same syntax as above:
Code Block |
---|
targetWindow.postMessage("open-drawer:right"); |
The right drawer panel can be opened via a query parameter too: enableDynamicFilterPanel=true
. This lets the dashboard know that the category should load with the Category Object Filters list open
...
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
...
Full URL Examples
http://localhost:8224/pi/chart#chart-filter/195__1/t-f-p=... -------- Use this URL prefix, and add the filters
E.g.
...
Note |
---|
IMPORTANT: This is just for information. We don’t recommend editing the URL directly to change filter values, because it’s not a reliable approach and the implementation may break when upgrading the dashboard |
Category-level filters are applied to all the charts in the category, it currently has such a pattern pattern:
Code Block |
---|
scheme://host:port/pi/#PA-CA###category/id__level/c-o-p=FILTERS |
For example:
This category has filters Department = Dev
:
Code Block |
---|
https://localhost:8224/pi/#PA-CA###category/141__0/c-o-p=eq__[[Department]]{{dev}} |
And this one has Department = Dev
and Number > 100
:
Code Block |
---|
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
Note |
---|
IMPORTANT: This is just for information. We don’t recommend editing the URL directly to change filter values, because it’s not a reliable approach and the implementation may break when upgrading the dashboard |
Temporary filters have something with the following pattern:
Code Block |
---|
scheme://host:port/pi/chart#chart-filter/id/t-f-p=FILTERS |
For example:
Filtering the chart with Department = Dev
:
Code Block |
---|
https://localhost:8224/pi/chart#chart-filter/330__1/t-f-p=eq__[[Department]]{{dev}}------ 1 filterhttp |
Filtering the chart with Department = Dev
and Number > 100
:
Code Block |
---|
https://localhost:8224/pi/chart#chart-filter/330__1/t-f-p=eq__[[Department]]{{dev}}/*$*gt__[[Number]]{{100}}------2 filters |
Types of filters
Note |
---|
IMPORTANT: This is just for information. We don’t recommend editing the URL directly to change filter values, because it’s not a reliable approach and the implementation may break when upgrading the dashboard |
Filter Name | Pattern | Object Types | Examples |
---|---|---|---|
Equals |
| Dimension |
|
...
Measure |
|
...
| |||
Greater than |
| Dimension |
|
...
Measure |
| ||
Lower than |
| Dimension |
|
...
Measure |
| ||
Greater or equals |
| Dimension |
|
...
Measure |
| ||
Lower or equals |
| Dimension |
|
...
Measure |
| ||
Not equals |
| Dimension |
|
...
Measure |
|
Like |
|
...
Dimension |
|
...
| Measure* |
|
...
Not Like |
| Dimension |
|
...
| Measure* |
|
...
Top |
| Dimension |
|
...
Measure |
| ||
Bottom |
| Dimension |
|
...
Measure |
|
...
Works for measure only:
In |
|
...
|
...
|
...
|
...
Dimension |
|
...
|
...
|
...
|
...
Works for dimension only:
...
Not In |
|
...
|
...
| Dimension |
|
...
|
...
| |
Between |
|
...
| Measure |
|
...
|
...
|
...
Not Between |
|
...
|
...
|
...
| Measure |
|
...
|
*May not work for some databases
Note |
---|
Upper/lower case values make a difference! |
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:
Code Block |
---|
Access to XMLHttpRequest at 'https://dashboard-host/' from origin 'https://your-app-host/' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. |
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:
Code Block |
---|
{
"proxy": {
"enabled": true,
"scheme": "https",
"secure": true,
"host": "proxy-host.com",
"port": 443
}
} |
Using environment variables
Code Block |
---|
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.
In settings.sh
or in startup.sh
, set the following environment variables:
Code Block |
---|
export PI_PROXY_ENABLED=true
export PI_PROXY_SCHEME=https
export PI_PROXY_IS_SECURE=true
export PI_PROXY_HOST="<domain url>"
export PI_PROXY_PORT=443
export PI_TOMCAT_COOKIE_SECURE= true
export PI_TOMCAT_FRAME_ANCESTORS=<URL of client site>
export PI_TOMCAT_COOKIE_SAMESITE=none |
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
Elementor macro | ||||||
---|---|---|---|---|---|---|
| ||||||