Bind datasets dynamically to a paginated report

  • Article

Power BI reports and paginated reports are built based on an existing dataset. That dataset defines the data schema that the report visuals use. By using dynamic binding, you can select a dataset on the fly when you embed a paginated report visual.

The datasets that you select need to use the same data schema. If you have multiple datasets with the same data schema, your report can connect, or bind, dynamically to each of those datasets. You can then display different insights, depending on your needs.

Dynamic binding offers other advantages, too. You don't need to create a copy of the same report with a different dataset for each user. One report can serve multiple users. This feature then reduces the number of maintained items and improves the application life cycle handling. As a result, dynamic binding simplifies onboarding for new customers.

How to connect a report to multiple datasets dynamically

Your reports and datasets can be in separate workspaces, however both workspaces must have a capacity.

When you embed for customers, the embed token must include permissions for both the report and the dynamically bound dataset. Use the new API to generate an embed token that supports Power BI items, such as reports and dashboards.

When you embed for your organization, the user's Azure Active Directory (AD) token that you use must have appropriate permissions for all Power BI items.

Example 1: Embed a paginated report with dynamic binding

To implement an embedded paginated report using dynamic binding add the datasetBindings property to the embed configuration object, as shown in the following example.

let config = {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: "reportId",
    permissions: permissions,
    datasetBindings: [{
            sourceDatasetId: "originalDatasetId",
            targetDatasetId: "notOriginalDatasetId"
        }]
};

// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, config);

Example 2: Embed a paginated report visual with dynamic binding

A paginated report visual is a paginated report embedded in a Power BI report. To implement an embedded paginated report visual using dynamic binding, add the datasetBinding property to the embed configuration object, as shown in the following example.

let config = {
    type: 'report',
    tokenType: models.TokenType.Embed,
    accessToken: accessToken,
    embedUrl: embedUrl,
    id: "reportId",
    permissions: permissions,
    datasetBinding: {
        datasetId: "notOriginalDatasetId",
        paginatedReportBindings: [{
            sourceDatasetId: "originalDatasetId",
            targetDatasetId: "notOriginalDatasetId"
        }]
    }
};

// Get a reference to the embedded report HTML element.
let embedContainer = $('#embedContainer')[0];

// Embed the report and display it within the div container.
let report = powerbi.embed(embedContainer, config);

Considerations and limitations

  • The dynamically selected dataset must use the same data schema in the report.
  • When embedding for customers, generate an embed token using the new API.
  • When embedding for your organization, ensure the user has permissions for both the report and dataset.
  • The datasetBinding property can't be empty. It should contain, datasetId, paginatedReportBindings, or both.
  • The values for datasetId and targetDatasetId don't have to be the same. Binding works independently for .pbix and paginated reports.
  • The datasetBinding property can contain multiple objects.

Next steps