Using the Dundas BI embed library

1. Overview

The Dundas BI embed library is designed to make embedding Dundas BI views (such as dashboards and reports) 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 embed library

The Dundas BI embed 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="/Scripts/Embed/dundas.embed.min.js" type="text/javascript"></script>
</head>
    

2. Embedding without JavaScript

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

The following example will embed a Dundas BI instance located at https://placeholder.dundas-bi-url.com, and a dashboard with the specified ID:

   ...
<head>
    <script src="/Scripts/Embed/dundas.embed.min.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:

AttributeDescription
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 possibilities: Dashboard, Scorecard, Report, SmallMultiple, Slideshow or Shortlink.
data-file-system-id The ID of the file you are embedding if data-controller-type is set to a file type such as a dashboard.
data-shortlink The short link value following the /Link/?shortLink= portion of the link (e.g., ae6swdok5p5r3mm3m4oaguqujo) if data-controller-type is Shortlink.
data-logon-token-id (Optional) The logon token ID.
data-view-options (Optional) The view options for the Dundas BI embedded application. The following are the possibilities: menuonly, menutoolbar, menutoolbartaskbar, none, toolbaronly, or viewonly. By default, this property is set to viewonly.
data-parametervalue-1 (Optional) The way to set view parameter values. You can use multiple of these attributes by increasing their number (data-parametervalue-2, data-parametervalue-3, etc.) The values are in a similar format as when passed via query string E.g., viewParameter2=$Today$.
data-urlparameteroption-1 (Optional) The way to add other URL parameters. You can use multiple of these attributes by increasing their number (data-urlparameteroption-2, data-urlparameteroption-3, etc.) E.g., cultureName=fr-FR

The following example will create a Dundas BI embedded application for the Dundas BI instance located at https://placeholder.dundas-bi-url.com, displaying the dashboard with the specified ID. It will log on automatically with the logon token by a specified ID, set two view parameters, and set the culture to fr-FR:

...
<head>
    <script src="/Scripts/Embed/dundas.embed.min.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"
        data-logon-token-id="13ECB6B5-8324-473B-BCA5-6D18E2DC3988"
        data-parametervalue-1="viewParameter2=$Today$"
        data-parametervalue-2="viewParameter4=2500~3700"
        data-urlparameteroption-1="cultureName=fr-FR">
    </div>
</body>


    

3. Embedding with JavaScript

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

  • Set view parameters
  • Load and refresh the view
  • Hook into dashboard events
  • Run scripts and get messages sent back

3.1. Getting a logon token

Important
When getting a logon token, it is best practice to do it at the server-side. The method below provides a way to get this at the client-side, however this is not recommended as the credentials are technically made available to users. For more information about calling the REST API to get a logon token, see POST /LogOn/Token.

This example gets a logon token for use with a Dundas BI embedded application at the client-side, which is not recommended if the specified credentials should not be generally available:

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

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

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

    // *****************************************************************************
    // It is best practice to get the logon token at the server-side.  
    // The client-side method below is not recommended if the specified credentials
    // should not be freely available to users.
    // *****************************************************************************

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

    </script>
</body>
    

Note
In version 4.0.2 and above, when getting a logon token to a site using HTTPS, the xmlHttpRequest adds the withCredentials flag with a true value. This was done to ensure the origin header is sent. In version 5 and above, we have added the property dundas.embed.logon.disableWithCredentialsFlag. When set to true, it will not send the withCredentials property when getting the logon token.

3.2. Creating an embedded application object

The embedded application object can be used 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="/Scripts/Embed/dundas.embed.min.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 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

 NameDescription
JsProperty controllerType Gets or sets the controller type to load. Possible values:
dundas.embed.ControllerType.DASHBOARD 
dundas.embed.ControllerType.REPORT
dundas.embed.ControllerType.SCORECARD
dundas.embed.ControllerType.SHORTLINK
dundas.embed.ControllerType.SLIDESHOW
dundas.embed.ControllerType.SMALL_MULTIPLE
JsProperty dundasBIUrl Gets or sets the Dundas BI URL to connect to. For example, http://somedomain.com:8080/
JsProperty fileSystemId Gets or sets the file system entry ID of a dashboard, scorecard, report, small multiple, or slideshow, if controllerType is one of those file types.
JsProperty id Gets the ID for the Dundas embedded application.
JsProperty logonTokenId Gets or sets the logon token ID.
JsProperty otherUrlParameterOptions Gets or sets other URL parameter options.
JsProperty parameterValues Gets or sets the parameter values.
JsProperty shortLink Gets or sets the short link value following the /Link/?shortLink= portion of the link (e.g., ae6swdok5p5r3mm3m4oaguqujo) if controllerType is SHORTLINK.
JsProperty viewOptions Gets or sets the view options. 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 a Dundas embedded application, sets some properties, and loads it:

<head>
    <script src="/Scripts/Embed/dundas.embed.min.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) {

            // *****************************************************************************
            // It is best practice to get the logon token at the server-side.
            // The client-side method below is not recommended if the specified credentials
            // should not be freely available to users.
            // *****************************************************************************
            dundas.embed.logon.getLogonToken(
                dundasBIUrl,
                {
                    "accountName": "viewer",
                    "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.otherUrlParameterOptions = [
                        new dundas.embed.UrlParamterOption(
                           "cultureName",
                           "fr-FR"
                        )
                    ];
                    dundasApp.load();
                }
            )
        });

    </script>
</body>
    

3.3.2. Methods

 NameDescriptionExample
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();
                
JsFunction loadAndCreateShortLink Creates a shortlink and loads the Dundas BI embedded application frame.
var dundasBIUrl = 'https://placeholder.dundas-bi-url.com/';

var logonToken1 = '1fb29869-b276-41ab-9cbd-098d17b675b4';
var logonToken2 = 'cb316db8-5b6d-488f-8c31-fa20c8d66524';

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

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

var logOnOptions = {
    logOnTokenId: logonToken2,
    deleteOtherSessions: true 
};

// * Load the application *
dundasApp.loadAndCreateShortLink(logOnOptions);
                
loaded Handles when the Dundas BI embedded application is first 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 the Dundas BI application and the application that embeds it.

3.3.3.1. Add origins to the web.config of the application that embeds Dundas BI

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 Dundas BI's configuration settings

Open the Admin section of Dundas BI by clicking on the gear icon in the main menu on the left.

Must be logged in as an administrator
Must be logged in as an administrator

Expand Setup and select Config.

Select the Show Advanced Settings checkbox.

In the Web Application Category, there is a setting called CORS (Cross-Domain) Origins: click the edit icon for this setting.

Select Edit value, enter the domain that will be hosting the Dundas BI iframe into this text field, then click the submit button at the bottom.

For more information about application configuration settings, see the article Configuration settings

3.3.4. Working with view parameters

View Parameters in the Dundas BI embed 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) {

    // *****************************************************************************
    // It is best practice to get the logon token at the server-side.
    // The client-side method below is not recommended if the specified credentials
    // should not be freely available to users.
    // *****************************************************************************
    dundas.embed.logon.getLogonToken(
        dundasBIUrl,
        {
            "accountName": "viewer",
            "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.3.5. URL path length restrictions

If the URL query generates more than 2,083 characters (for example because of view parameters), an error will be thrown. To work around these browser limitations, you should create a short link, and then load the Dundas BI application. The following example uses two logon tokens to create a short link and load the Dundas BI embedded application:

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

    var logOnTokenOptions = { "accountName": "viewer", "password": "1234", "isWindowsLogOn": false };

    // Gets two logon tokens: one to generate the shortlink, and one that then
    // loads using the shortlink.
    // *****************************************************************************
    // It is best practice to get the logon token at the server-side.
    // The client-side method below is not recommended if the specified credentials
    // should not be freely available to users.
    // *****************************************************************************
    dundas.embed.logon.getLogonToken(
        dundasBIUrl,
        logOnTokenOptions,
        function (logonTokenResultData1) {

            // *****************************************************************************
            // It is best practice to get the logon token at the server-side. 
            // The client-side method below is not recommended if the specified credentials
            // should not be freely available to users.
            // *****************************************************************************
            dundas.embed.logon.getLogonToken(
                dundasBIUrl,
                logOnTokenOptions,
                function (logonTokenResultData2) {

                    var dundasApp = dundas.embed.create(document.getElementById('dundasBI2'));
                    dundasApp.logonTokenId = logonTokenResultData1.logOnToken;
                    dundasApp.dundasBIUrl = dundasBIUrl;
                    dundasApp.controllerType = dundas.embed.ControllerType.DASHBOARD;
                    dundasApp.fileSystemId = '460ebfa5-116a-489b-9440-87e1c18ef957';
                    dundasApp.parameterValues = [
                        new dundas.embed.ParameterValue(
                            "viewParameter2",
                            "!" + 25000 + "~" + dundas.embed.tokens.basic.OPEN_RANGE
                        )
                    ];

                    var logOnOptions = { 
                        'logOnTokenId': logonTokenResultData2.logOnToken, 
                        'deleteOtherSessions': true 
                    };

                    dundasApp.loadAndCreateShortLink(logOnOptions);

                }
            );
        }
    );
});

3.4. Hosted Dundas embed library file

You can also use the Dundas embed library from dundas.com using the URL in the following HTML:

<head>
    <script src="//www.dundas.com/files/dbi/dundas.embed.js/6.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 the Dundas embed library on your own CDN.

4. See also

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