Using cross-origin resource sharing in Dundas BI

Contents[Hide]

1. Overview

The goal of this article is to explain the necessary steps to enable and use Cross-Origin Resource Sharing (CORS) in Dundas BI. This allows a web application to communicate with Dundas BI while embedding it.

2. Application configuration

Dundas BI needs to be configured for cross-origin resource sharing. You must be a member of Dundas BI's System Administrators to do this.

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

Log on as an administrator and choose Admin
Log on as an administrator and choose Admin

Click to expand Setup and select Config.

Find the setting CORS (Cross-Domain) Origins in the Web Application category. (Select the Show Advanced Settings checkbox if needed.)

Edit this setting to enter the domains that will be communicating with Dundas BI.

Place the domain that will be hosting the Dundas BI iframe into this text field, then click the submit button at the bottom of the dialog to save your changes.

3. Cross-origin script example

The following is an example of cross-origin resource sharing, where an application that embeds Dundas BI communicates with it.

For details and examples on embedding Dundas BI, see Using the Dundas BI embed library or Dundas BI viewer integration sample.

3.1. Create a new dashboard

On a new dashboard, add a chart (with Script Name chart1) and a label (with the Script Name label1).

For this example, we will be altering the text in the label and unhiding the chart. This will be done by sending a script from the host site into the iframe containing Dundas BI.

Select the Hidden property of the chart, which is located in the Properties window in the Layout tab.

Chart Hidden property
Chart Hidden property

In the Dashboard's properties, copy the dashboard ID from the Main tab.

Copy the dashboard ID
Copy the dashboard ID

Now check in the dashboard, and use as the file ID in your web application that embeds Dundas BI.

3.2. Add the CORS JavaScript

This script assumes a jQuery library reference is included in your <head> section.

In another script element in the <head> section, script like the following can be used:

$(document).ready(function () {
    // Synchronous Example
    var element = $("iframe").get(0);
    $(element).load(function () {
        // Since the iframe will have loaded before the dashboard has,
        // we need to pass in a function that runs when the dashboard is ready.
        element.contentWindow.postMessage({
            "isAsync": false,
            "script": "\n\
                window.dundas.context.ready(function () {\n\
                    var myView = dundas.context.baseViewService.currentView;\n\
                    var myLabel = myView.getAdapters().filter(function(a) { return a.name == \"label1\" })[0];\n\
                    var myChart = myView.getAdapters().filter(function(a) { return a.name == \"chart1\" })[0];\n\
                    myChart.hidden = false;\n\
                    myLabel.labelText = \"There it is!!!\";\n\
                });\n\
            "
        }, "*");
    });
});

The code waits for the dashboard to load, then finds and modifies the properties of the chart and label.

The \n\ is required to include the line breaks in the string.

3.3. Test sample

Build and publish your project's server-side changes (if applicable).

You should now see the new label text and the chart should be visible.

Viewing the result
Viewing the result

4. Other CORS JavaScript examples

4.1. Change view options and return data

The following example changes the view options of a dashboard to hide the menu, toolbar and taskbar, then sends a message back to the parent application.

$(document).ready(function() {

    // Hook up to receive window postMessage calls.
    $(window).bind("message", function (e) {
        var result = e.originalEvent.data;
        // result will be ‘hi’
    });

    // Synchronous Example
    var abc = $("#iFrame").get(0);
    $(abc).load(function() {
        abc.contentWindow.postMessage({
            "isAsync": false,
            "script": " console.log(e);
            window.dundas.context.baseViewService.viewOptions = dundas.ViewOptions.VIEW_ONLY;
            window.dundas.context.updateViewFromViewOptions();
            return 'hi';
            "
        }, "*");
    });
});

4.2. Change view options and return data asynchronously

The following example changes the view options of a dashboard, then sends a message back to the parent application asynchronously.

$(document).ready(function() {

    // Hook up to receive window postMessage calls.
    $(window).bind("message", function (e) {
        
        var result = e.originalEvent.data;
        // result will be ‘hi’
    });

    // Asynchronous Example
    var abc = $("#iFrame").get(0);
    $(abc).load(function() {

        abc.contentWindow.postMessage({
            "isAsync": true,
            "script": " console.log(e);
            window.dundas.context.baseViewService.viewOptions = dundas.ViewOptions.VIEW_ONLY;
            window.dundas.context.updateViewFromViewOptions();
            var result = new $.Deferred();
            window.setTimeout(function() {
                result.resolve('hi')
            }, 500);
            return result.promise();
            "
        }, "*");
    });
    // Note that ‘e’ is the original message's event, so you can also use e.source.postMessage(..)
    // to send a message back in addition to returning a value.
});

4.3. Use the REST API to download a dashboard file

The following example sends a /Dashboard/ request.

$(document).ready(function() {

    // REST API example
    var def = $.ajax("http://server:[port]/api/dashboard/[dashboardId]?sessionId=[sessionId]");
    def.done(function (dashboard) {
        // perform action here. 
    });
    // Note the ‘dashboard’ object that this method returns is not a Dundas JavaScript API object
});

5. Troubleshooting

Use your browser's developer tools, and check the console for errors.

If everything went well, in the console you should see "Running window message received from origin '[domain]' which was in the accepted list. If this was not expected, this might be an XSS attack."

If you see "Attempt to post message from origin '[domain]', but this is not in the allowed list from configuration. Post ignored." there was probably a problem with the CORS application configuration setting you entered.

6. 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