Embed Options

This applies to: Managed Dashboards, Managed Reports

You can use a number of available methods to embed views such as dashboards and reports, individual visualizations, or a simplified, self-service dashboard creation experience, directly in your own web application without using iframes. These are powered by the JavaScript API, which you can also access with this embedding method.

Alternatively, embed the entire application or any page from it using other embedding methods. Take advantage of white labeling, API, and extension support, depending on your scenario and preferences.

Set Up IFrameless Embedding

The first step to embedding Managed Dashboard content directly on your page is to add dundas.embedded.min.js. This file is included in your Dundas BI instance installation at the following location on disk:

[Instance Root]\www\BIWebsite\wwwroot\Scripts\Embed\dundas.embedded.min.js

This can be accessed under a Symphony instance URL as /Scripts/Embed/dundas.embedded.min.js. For example, if Symphony is available as https://dbi.example.com/ , your page might add:

<script src="https://dbi.example.com/Scripts/Embed/dundas.embedded.min.js" type="text/javascript"></script>

This is different from the use of dundas.embed.min.js, the embed library used to embed Symphony via an iframe on your page.

There is a single method to call, which sets up Symphony on your page by adding and loading all CSS and JavaScript dependencies:

// Relative or absolute URL to Dundas BI:
let promise = window.setupDundasEmbedded('https://dbi.example.com/');

The following table describes available options for these properties and objects.

Property/Object Default Description
dundasBIUrl

none

The relative or absolute URL to access the root of the Symphony application from the current page.

Type: string
doNotAutoCreateBootstrap none

Optional. By default, a new dundas.views.embedded.Bootstrap is created immediately. If the document is not yet ready, pass true for this parameter and call this bootstrap's constructor at a later point.

Type: boolean

This returns a Promise object that resolves once the Dundas JavaScript API bootstrap is ready for use. This is not a jQuery.Promise: third party libraries are not yet loaded when this method is called.

If the Symphony URL has a different domain or origin from your page, cross-origin resource sharing (CORS) must be set up. Browsers such as Chrome also require both sites use the HTTPS protocol for cross-origin sharing.

Use the JavaScript API

When the setupDundasEmbedded method's Promise resolves, you can access the JavaScript API via dundas.context the same way as on a page within the Symphony application, and access its services.

Most actions require authentication, so first use the LogOnService to log on using a one-time token obtained from the Symphony server like in the following example, or another available LogOnService method:

let logonToken = myApp.getLogonTokenFromServer();
let promise = window.setupDundasEmbedded('https://dbi.example.com/');
promise.then(() => {
	dundas.context.getService("LogOnService").logOnByToken(logonToken).done((result) => {
		if (result.sessionId) {
			// Logon successful!
		}
	});
});

The result of a log on method has the properties defined by LogOnResultData (beginning in lowercase in JavaScript). If a session ID is not populated in the result, the log on was likely not successful and the other properties will contain details about the reason.

After a successful log on, set the session ID so that you can embed content or access other services. You can call setSessionId on dundas.context, or pass the session ID into one of the embedding methods as a shortcut.

Embed Content

When Symphony is embedded directly onto your page, dundas.context is a dundas.views.embedded.Bootstrap.

Call its embedView method to embed an existing dashboard, report, or other view type by its ID, which you can find from its URL or properties dialog. It is rendered inside the DOM element you specify, which should have some set size independent of its contents (i.e., not auto). The following embeds a dashboard:

let element = document.getElementById("viewContainer");
dundas.context.embedView(element, "bdba4200-8d2d-0f90-0049-cfbe81e00004", {
	sessionId: sessionId
});

The third argument is an object specifying additional optional values. Important options include passing sessionId as an alternative to first calling and waiting for setSessionId, and viewTypewhen embedding a type of view other than a dashboard like in the next example. A jQuery.Promise is returned that you can use to wait for the embedding to complete.

Content is always embedded on its own without other interface elements like the application's toolbar or main menu, but with most functionality accessible by default as usual from the context menu via right-click or long-tap.

Alternative Embed Methods

The entire application or any desired page from it can also be embedded via an iframe, or a WebView or similar component in mobile or desktop apps, or by simply linking to a Symphony URL.

  • In a web page or web application, the Symphony-provided embed library can make this process easier, including helper methods facilitating any needed communication between your application's JavaScript and the Symphony embedded application.

  • Alternatively, create an iframe element or WebView component yourself if desired, and load a URL including optional parameter values. You can still communicate with an embedded Symphony application using script as shown in the article Using cross-origin resource sharing.

You may also need to communicate with a Symphony server from your application instead of or in addition to embedding it on the page. You can do this within a web application by embedding the JavaScript API directly onto your page as shown earlier, or you can also use the REST API directly from all types of applications. The .NET API is available to use from .NET-based applications.

You can make the Symphony interface match your own branding using white labeling support including custom CSS, JavaScript, HTML, and interface text, with support also for separate branding per tenant. You can plug in any custom functionality you might need via extensions anywhere from data providers, transforms, formulas, and visualizations through to export and notification delivery providers.

Besides logging your users in with one-time tokens, other single sign-on options are available including federated authentication with another identity provider you may already be using such as Azure Active Directory or Okta, or another provider using standard protocols such as SAML 2.0 and OpenID Connect (OIDC).

Technical Notes

There are technical notes that can apply in specific cases when embedding included in Product Notes in the Browser and General sections.

The following apply when embedding Symphony on your page without an iframe as described above:

  • Only one ad hoc dashboard editor can be embedded on a page, but the embedView and embedMetricSet methods can be called multiple times per page.
  • Only one user session is supported at a time within a single open page in a browser.
  • As this is an experimental API, there may be breaking changes in a future version if needed based on feedback and for added enhancements.

For more information, see the following topics: