Using the Dundas BI embed library

1. Overview

The Dundas BI Embed library is designed to make embedding Dundas BI views (Dashboard, Scorecard, or Report) easy. This is a guide demonstrating how to use the Dundas BI Embed library. The library can be used in two ways:

> Embedding without needing to write JavaScript. This allows a quick and simple embedding option with little technical knowledge.

> Embedding with JavaScript. This allows for more advanced functionality such as CORS, running scripts, and hooking to Dashboard events.

1.1. Downloading the Dundas Embedded Library

The Dundas BI Embedded Library is a single JavaScript file, and you reference it with an HTML script tag.

The file can be found at the following location: [InstanceDirectory]\www\BIWebsite\Scripts\Embed\dundas.embed.min.js

Note
This file only exists in Dundas BI instances in version 4 and above.

<head>
   <script src="dundas.embed.min.js" type="text/javascript" ></script>
</head>
    

2. Embedding without needing to write JavaScript

This method is intended on being a quick and simple way of embedding Dundas BI without having to be an expert with JavaScript.

The following example will create a Dundas BI Embedded application for the Dundas BI instance located at "https://placeholder.dundas-bi-url.com" dashboard with the ID equal to 727ae6b6-b5b6-4c1e-bad7-72561040298d:

   ...
<head>
   <script src="dundas.embed.js" type="text/javascript" ></script>
</head>
   ...

<body>
    <div
         class="dundas-bi-embed"
         data-dundas-bi-url="https://placeholder.dundas-bi-url.com/"
         data-controller-Type="Dashboard"
         data-file-System-Id="727ae6b6-b5b6-4c1e-bad7-72561040298d"
         >
    </div>
</body>


    

The following table describes the HTML attributes that are used when embedding without JavaScript:

Attribute Description
class The class must be set to "dundas-bi-embed" to become a valid Dundas BI Embedded application object.
data-dundas-bi-url The Dundas BI base Url.
data-controller-type The type of object you are embedding. The following are the possiblities: Dashboard, Scorecard, or Report.
data-file-system-id The ID of the file system object you are embedding. The following are the possiblities: Dashboard, Scorecard, or Report.
data-view-options (Optional) The view options for the Dundas BI Embedded application. The following are the possiblities: menuonly, menutoolbar, menutoolbartaskbar, none, toolbaronly, or viewonly. By default this property is set to viewonly.

3. Embedding with JavaScript

When embedding with JavaScript, you gain more control of the embedded application. You can do the following:

  • Set view parameters
  • Loading, and refreshing the view
  • Hooking into dashboard events
  • Running Scripts, and sending messages back

3.1. Getting a Logon Token

This sample will get a logon token for use with a Dundas BI Embedded application:

   ...
<head>
   <script src="dundas.embed.js" type="text/javascript" ></script>
</head>
   ...

<body>
    <script type="text/javascript">

document.addEventListener("DOMContentLoaded", function (event) {

    dundas.embed.logon.getLogonToken('https://placeholder.dundas-bi-url.com/',
            {
                "accountName": "admin",
                "password": "1234",
                "isWindowsLogOn": true 
            },
            function(getLogOnTokenResultData)
            {
                alert(getLogOnTokenResultData.logOnToken);
            }
    );

});

    </script>
</body>
    

3.2. Creating a Dundas BI Embedded Application Object

The Embedded application object is the means in which to control the Dundas BI Embedded application. The following example shows how to get and load the Dundas BI embedded application object.

    ...
<head>
   <script src="dundas.embed.js" type="text/javascript" ></script>
</head>
   ...
<body>

    <!-- Create the container for the Dundas BI Embedded Application -->
    <div id="dundasBI2" />

    <script type="text/javascript">

        var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';
        
        document.addEventListener("DOMContentLoaded", function (event) {

            var embedOptions =
                {
                    dundasBIUrl: dundasBIUrl,
                    controllerType: dundas.embed.ControllerType.DASHBOARD,
                    fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c',
                    viewOptions: dundas.embed.ViewOptions.TOOLBAR_ONLY,
                    parameterValues: []
                };
 
                // Create the Dundas Embedded application object.
                var dundasApp = dundas.embed.create(
                    document.getElementById('dundasBI2'),
                    embedOptions
                );

                // Load the application
                dundasApp.load();

        });

    </script>
</body>
    

3.3. Using the Dundas Embedded Application

The section above described how to get the object. This section describes how to set various properties and call different methods on the embedded application object.

3.3.1. Properties

  Name Description
JsProperty controllerType Gets or sets the controllerType property. Possible values:
dundas.embed.ControllerType.DASHBOARD 
dundas.embed.ControllerType.REPORT
dundas.embed.ControllerType.SCORECARD
JsProperty dundasBIUrl Gets or sets the dundasBIUrl property that represents the Dundas BI Url to connect to. For example, http://somedomain.com:8080/
JsProperty fileSystemId Gets or sets the fileSystemId property. This is the file system ID of either, a dashboard, scorecard, or report.
JsProperty id Gets the ID for the Dundas Embedded Application.
JsProperty logonTokenId Gets or sets the logonTokenId property.
JsProperty parameterValues Gets or sets the parameterValues property.
JsProperty viewOptions Gets or sets the viewOptions property. Possible values:
dundas.embed.ViewOptions.MENU_ONLY
dundas.embed.ViewOptions.MENU_TOOLBAR
dundas.embed.ViewOptions.MENU_TOOLBAR_TASKBAR
dundas.embed.ViewOptions.NONE
dundas.embed.ViewOptions.TOOLBAR_ONLY
dundas.embed.ViewOptions.VIEW_ONLY

 

Example

This sample creates an dundas embedded application sets some properties and loads it:

<head>
   <script src="dundas.embed.js" type="text/javascript" ></script>
</head>
   ...
<body>
    <div
        id="dundasBI2"
         >
    </div>

    <script type="text/javascript">

        var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

        document.addEventListener("DOMContentLoaded", function (event) {
            dundas.embed.logon.getLogonToken(dundasBIUrl,
                {
                    "accountName": "admin",
                    "password": "1234",
                    "isWindowsLogOn": true 
                },
            function(getLogOnTokenResultData)
            {
                var dundasApp = dundas.embed.create(
                    document.getElementById('dundasBI2'),
                    { }
                    );

                dundasApp.dundasBIUrl = dundasBIUrl;
                dundasApp.controllerType = dundas.embed.ControllerType.DASHBOARD;
                dundasApp.fileSystemId = 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c';
                dundasApp.viewOptions = dundas.embed.ViewOptions.TOOLBAR_ONLY;
                dundasApp.logonTokenId = getLogOnTokenResultData.logOnToken;
                dundasApp.parameterValues = 
                    [ 
                        new dundas.embed.ParameterValue(
                            "viewParameter2", 
                            "!" + 25000 + "~" + dundas.embed.tokens.basic.OPEN_RANGE
                        )
                    ];

                dundasApp.load();
            })
        });


    </script>

</body>
    

3.3.2. Methods

  Name Description Example
JsFunction load Loads the Dundas BI embedded application frame.
var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

var embedOptions =
{
    dundasBIUrl: dundasBIUrl,
    controllerType: dundas.embed.ControllerType.DASHBOARD,
    fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c'
};

// Create the Dundas Embedded application object.
var dundasApp = dundas.embed.create(
    document.getElementById('dundasBI2'),
    embedOptions
);

// * Load the application *
dundasApp.load();
                
loaded Handles the when the Dundas BI embedded application is loaded.
var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

var embedOptions =
{
    dundasBIUrl: dundasBIUrl,
    controllerType: dundas.embed.ControllerType.DASHBOARD,
    fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c'
};
// Create the Dundas Embedded application object.
var dundasApp = dundas.embed.create(
    document.getElementById('dundasBI2'),
    embedOptions
);

// * Pass a function to the loaded function *
dundasApp.loaded(function(){ alert('Dashboard is Loaded'); });

// Load the application
dundasApp.load();
                
ready Handles when the Dundas BI Embedded application is ready.CORS is required to call this method.

var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

var embedOptions =
{
    dundasBIUrl: dundasBIUrl,
    controllerType: dundas.embed.ControllerType.DASHBOARD,
    fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c'
};
// Create the Dundas Embedded application object.
var dundasApp = dundas.embed.create(
    document.getElementById('dundasBI2'),
    embedOptions
);
// * Pass a function to the ready function *
dundasApp.ready(function(){ alert('Dashboard is Ready'); });
// Load the application
dundasApp.load();
                
refresh Refreshes the Dundas BI Embedded application content.
var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

var embedOptions =
{
    dundasBIUrl: dundasBIUrl,
    controllerType: dundas.embed.ControllerType.DASHBOARD,
    fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c'
};
// Create the Dundas Embedded application object.
var dundasApp = dundas.embed.create(
    document.getElementById('dundasBI2'),
    embedOptions
);

// * Refresh the Dundas BI Embedded Application *
dundasApp.refresh(); 
                
runScript Runs a script on the Dundas BI embedded application. CORS is required to call this method.
var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

var embedOptions =
{
    dundasBIUrl: dundasBIUrl,
    controllerType: dundas.embed.ControllerType.DASHBOARD,
    fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c'
};
// Create the Dundas Embedded application object.
var dundasApp = dundas.embed.create(
    document.getElementById('dundasBI2'),
    embedOptions
);

dundasApp.ready(
    function (e) {
        // * Pop up a hello ready dialog.              
        dundasApp.runScript(
            "var viewService = " +
            "    dundas.context.getService('ViewService'); " +
            "viewService.showSignal(" +
                "'Ready'," + 
                "dundas.view.NotifyType.INFO," +
                "'Hello Ready'" + 
            ");"
        );
        
        // * Run script and send message back, 
        // and handle it with function that accepts message.
        dundasApp.runScript(
            "dundas.embed.sendMessageToDundasEmbeddedApplication(" +
                dundas.context.currentSessionId" + 
                );",
            false,
            function (message) { alert(message.detail); }
        );
    }
);
                

3.3.3. Cross-origin resource sharing (CORS)

In order to use the events the user will need to enable CORS for both on the Dundas BI application, and the application that contains the Dundas BI Embedded application.

3.3.3.1. Add origins to the Web.Config of the application that contains the Dundas BI Embedded application

Merge the following into the web.config file at the root of your application or site:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
 <system.webServer>
   <httpProtocol>
     <customHeaders>
       <add name="Access-Control-Allow-Origin" value="*" />
     </customHeaders>
   </httpProtocol>
 </system.webServer>
</configuration>

Note
The Access-Control-Allow-Origin can also be set to just the Dundas BI Url, the * indicates all domains are accepted. For more information about CORS visit: Cross-Origin Resource Sharing.

3.3.3.2. Add origins (domains) to the Admin Application Configuration in Dundas BI

Open the Admin section of Dundas BI by clicking on the Gear Icon on the left hand side of the application.

Must be logged in as Admin
Must be logged in as Admin

Under Setup select Config.

Change the Setting scope drop down from Effective to Global.

Under the Web Application Category there is a setting called CORS (Cross-Domain) Origins.

In this text field you can enter the domains that will be communicating with Dundas BI. You can hover over the text field to get a summary and examples.

Place the domain that will be hosting the Dundas BI iframe into this text field.

save changes and exit the Admin menu.

3.3.4. Working with View Parameters

View Parameters in the Dundas BI Embedded Library are defined the same way they would be defined via the query string. The following example sets a view parameter to a value then loads the Dundas Embedded application.

var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

            document.addEventListener("DOMContentLoaded", function (event) {
            dundas.embed.logon.getLogonToken(dundasBIUrl,
                {
                    "accountName": "admin",
                    "password": "1234",
                    "isWindowsLogOn": true 
                },
            function(getLogOnTokenResultData)
            {
                var dundasApp = dundas.embed.create(
                    document.getElementById('dundasBI2'),
                    {
                        dundasBIUrl: dundasBIUrl,
                        controllerType: dundas.embed.ControllerType.DASHBOARD,
                        fileSystemId: 'f22ce55f-04cd-4207-9dd7-2cadeb44b96c',
                        logonTokenId: getLogOnTokenResultData.logOnToken
                    }
                    );

            
                dundasApp.parameterValues =
                    [
                        // The object is created by passing the name, 
                        // and then the value formatted in the same way 
                        // that would be defined via the query string
                        new dundas.embed.ParameterValue(
                            // The name of the view parameter
                            "viewParameter2", 
                            // The value formatted to be passed in the 
                            // same way as if was passed via query string.
                            "!" + 25000 + "~" + dundas.embed.tokens.basic.OPEN_RANGE
                            )
                    ];

                dundasApp.load();
            })
        });
    

Note
For more information visit: Pass parameter values via query string.

For convenience purposes token helpers have been added that can be used in the values of the ParameterValue object.

Basic
        dundas.embed.tokens.basic.ALL
        dundas.embed.tokens.basic.DEFAULT
        dundas.embed.tokens.basic.NO_SELECTION
        dundas.embed.tokens.basic.NULL
        dundas.embed.tokens.basic.OPEN_RANGE
    
SingleDate
        dundas.embed.tokens.SingleDate.BEGINNING_OF_CURRENT_DAY
        dundas.embed.tokens.SingleDate.BEGINNING_OF_CURRENT_MONTH
        dundas.embed.tokens.SingleDate.BEGINNING_OF_CURRENT_QUARTER
        dundas.embed.tokens.SingleDate.BEGINNING_OF_CURRENT_WEEK
        dundas.embed.tokens.SingleDate.BEGINNING_OF_CURRENT_YEAR
        dundas.embed.tokens.SingleDate.END_OF_CURRENT_YEAR
    
DateRange
        dundas.embed.tokens.DateRange.CURRENT_DAY
        dundas.embed.tokens.DateRange.CURRENT_MONTH
        dundas.embed.tokens.DateRange.CURRENT_QUARTER
        dundas.embed.tokens.DateRange.CURRENT_WEEK
        dundas.embed.tokens.DateRange.CURRENT_YEAR
        dundas.embed.tokens.DateRange.MONTH_TO_DATE
        dundas.embed.tokens.DateRange.PREVIOUS_DAY
        dundas.embed.tokens.DateRange.PREVIOUS_MONTH
        dundas.embed.tokens.DateRange.PREVIOUS_QUARTER
        dundas.embed.tokens.DateRange.PREVIOUS_WEEK
        dundas.embed.tokens.DateRange.PREVIOUS_YEAR
        dundas.embed.tokens.DateRange.QUARTER_TO_DATE
        dundas.embed.tokens.DateRange.TODAY
        dundas.embed.tokens.DateRange.YEAR_TO_DATE
    

3.4. Hosted Dundas Embedded Library File

To use the Dundas Embedded Library, use the following:

<head>
   <script 
          src="//www.dundas.com/files/dbi/dundas.embed.js/4.0.0.1000/dundas.embed.min.js" 
          type="text/javascript" >
   </script>
</head>

Note
Speed and uptime are not guaranteed. It is recommended that you place on the dundas embedded library on your own CDN.

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours: 7am-6pm, ET, Mon-Fri