Dashboards 2.0 supports two-way communication between Birst and 3rd party applications.
Use the Embedding API and JavaScript to embed Dashboards 2.0 dashboards in your web pages. You can also pass data from a web page embedded in Birst to the Birst application.
Embedding Basics
Embedding requires using Birst single sign-on (SSO). Birst uses a standard 3-step SSO handshake, also called a 2-pass SSO handshake. The following diagram shows how authentication mechanism provides access to Birst.
Prior to Using the Embedding API
- Enable SSO for the space and generate the SSO password.
- Decide what SSO parameters you need.
- Confirm
the size of the dashboard to embed. This is also the size
of the parent DIV container on the HTML page. Here are some considerations:
- If you do not use the SSO parameter hideHeader=true then minimum width is 738px and the minimum height is 550px.
- If you do use the SSO parameter hideHeader=true then there is no width and height limit and the end user can resize to any point.
- If you use hideSubHeader=true, then the filter card and dashboard name are removed. This helps when embedding a single KPI or dashlet.
- The JavaScript
embedding file is located at:
https://birst_URL/js/birst_embed.js
where birst_URL is the URL of the Birst server. For example:
https://mrc.bws.birst.com/js/birst_embed.js
To use the embedding API
- Add the link to the birst_embed.js file at the top of the HTML page, inside the head tag. It must be on the page prior to the JavaScript call in Step 5.
<head> <script src="https://birst_URL/js/birst_embed.js" type="text/Javascript"></script> </head>
- In the body of the page, add the DIV element and give it a unique ID for the dashboard. The DIV must be on the page prior to the JavaScript call in step 5.
<div id="BirstDash">
- In your server-side
code, generate a session token (token request).
https://birst_URL/TokenGenerator.aspx?birst.username=user@domain.com &birst.ssopassword=ssopassword&birst.spaceId=space_ID
- In JavaScript,
generate the URL for the Iframe using the Birst
Single-Sign-On parameters. Use the token from the first call in the URL.
The birst.module must be newDashboards, for Dashboards 2.0.
https://birst_URL/SSO.aspx?BirstSSOToken=birst_token &birst.module=newDashboards&birst.exportZoom=2&&birst.embedded=true &birst.hideDashboardNavigation=false&birst.hideDashboardPrompts=false &birst.dashboard=My%20Dashboard&birst.page=My%20Page
- In JavaScript
at the end of the <body> tag, create the configuration object with
the IframeSrc for the URL to the dashboard. Then call BirstConfig.create.
The first parameter is the div id on the HTML page that holds the Iframe,
and the second is the object for the dashboard.
The following example shows it with fixed width and height dimensions. If you do not provide fixed dimensions it will be responsive and automatically resize.
var optionsDashboard={
width: "800",
height: "600",
iframeSrc: "https://birst_URL/SSO.aspx?BirstSSOToken=birst_token
&birst.module=newDashboards&birst.exportZoom=2&&birst.embedded=true
&birst.hideDashboardNavigation=false&birst.hideDashboardPrompts=false
&birst.dashboard=My%20Dashboard&birst.page=My%20Page"
};
BirstConfig.create("BirstDash", optionsDashboard);
Listening for Events
Web pages can listen for events that happen in Birst. Currently, filter and drill-to-dashboard events are supported.
Embedded Web Page Listens for Filter Events from a Parent Birst Application
An embedded web page can listen for filter events that happen in the Birst application in which it is embedded.
First, set up the basic embedding as described above.
Then in the web page configure a listener for the event. For example, for a filter:
var eventHandler=function(e){
if(e.data.operation==="setFilters"){
alert(JSON.stringify(e.data.filters));
}
}
BirstConfig.callBack(eventHandler)
When an event occurs, the eventHandler function is called in the web page. The e.data.operation is setFilters.
Example for a filter:
e.data={operation:'setFilters', filters:[{key:'Time.Year', value:[2012],
operator:'='}]};
Sample Code: Listen For Filter Events
The Listen For Filter Events sample shows how to receive data from a parent Birst application when a filter updates. See Listen For Filter Events Example.
Web Page Listens for Events from an Embedded Birst Application
A web page can listen for events that happen in a Birst application that is embedded in the web page.
The code for a web page that embeds Birst is essentially the same as the previous scenario. However in this case, the e.data.operation can be either setFilters or drillToDashboard.
Example code for drillToDashboard:
e.data={operation:'drillToDashboard', drillAcross:{ dashboard:'Overview', page:'Freight' } };
Setting Filters
Embedded Web Page Sets the Value of a Filter in a Parent Birst Application
A web page embedded in Birst can pass filter values to the Birst application.
The embedded web page uses the following code to set a filter in the Birst application. For example:
window.parent.postMessage({operation:'setFilters', filters:[{key:'Time.Year',
value:[2012], operator:'='}]}, "*");
Sample Code: Pass Filter To Birst From Embedded
The ToBirstParent sample shows how to pass data from an Iframe on a web page to a Birst application using filters and the drillToDashboard parameter. See Pass Filter To Birst From Embedded.
Web Page Sets the Value of a Filter in an Embedded Birst Application
A web page can pass filter values to an embedded Birst application.
First, set up the basic embedding as described above.
Then locate the Iframe that is loading the Birst application and refer to its contentWindow property.
Use the following code for a filter:
BirstConfig.postData({operation:'setFilters',
filters:[{key:'Time.Year', value:[2012],operator:'='}]})
Going To a Dashboard
Open a Dashboards 2.0 in Birst using the drillToDashboard operation. Drill-to-dashboard is essentially the same as a drill-across link on a dashboard. Instead of a button drilling across from one dashboard to another, a web page can "drill-to" a dashboard.
Embedded Web Page Opens a Dashboard in a Parent Birst Application
A web page embedded in Birst can pass the information needed to drill to a specific dashboard to the Birst application.
The embedded web page uses the following code to trigger a drill-to-dashboard in the Birst application.
window.parent.postMessage({operation:'drillToDashboard', dashboard:'Overview',
page:'Freight'}, "*");
Sample Code: Pass Dashboard to Birst from Embedded
See Pass Dashboard To Birst From Embedded.
Web Page Opens a Dashboard in an Embedded Birst Application
A web page can pass the information needed to open, or drill-to, a specific dashboard in an embedded Birst application.
First, set up the basic embedding as described above.
Then locate the Iframe that is loading the Birst application and refer to its contentWindow property.
Example postMessage for drill-to-dashboard:
BirstConfig.postData({operation:'drillToDashboard', dashboard:'Overview',
page:'Freight'})
Querying Birst
An embedded web page can send a BQL query to be executed in a parent Birst application.
Use the BirstConfig.getData to send the query. For example:
BirstConfig.getData("SELECT TOP 100 USING OUTER JOIN
[Order_Date: Sum: Quantity] 'COL0',
[Products.ProductName] 'COL1' FROM [ALL]");
Sample Code: RunningBQuery
The RunningBQuery sample shows how a web page can initiate a query in Birst. See RunningBQuery.
Sample Code: Update D3 Using BQL
The UpdateD3UsingBQL sample shows an Iframe in a web page using BQL, filters, and the D3 library. The D3 visualization updates when a the Products.ProductName filter is updated in the Birst application. See Update D3 Using BQL.
Tip: Alternatively, use the Dashboards 2.0 HTML Editor to embed JavaScript in a dashlet. See Embedding HTML.
