For years, Microsoft hasn’t had a good story about embedded interactive reporting. If developers wanted to distribute interactive reports with their applications, they had to use third-party components. The good news is that Power BI supports this scenario! The bad news is that, at least for now, report embedding is limited to Reading View. This means that users can enjoy report interactive features, such as filtering and highlighting, but they can’t change the report layout, such as to add new fields or to change the visualizations.
Regardless of this limitation, many scenarios will benefit from embedding Power BI reports.
NOTE Supporting Editing View for embedded reports (to allow the user to change the report layout) is high on the Power BI wish list, and Microsoft is working on implementing this feature!
12.2.1 Understanding Embedded Reports
Power BI includes report APIs that allows you to embed specific reports in your
applications. For example, your application can present the user with a list of reports that he’s authorized to see. When the user selects a report, the application can embed the report on a web page.
Understanding embedded features
Figure 12.2 shows the Internet Sales Report, from which the “Sales vs Orders” tile was pinned. When the user clicks the “Sales vs Orders” tile, the app embeds the report in the same iframe element. Note that the report supports the same features as when you open the report in Reading View in Power BI Service. For example, you can sort data in visualizations that support sorting.
To demonstrate that interactive highlighting works, I clicked a bar in the “Sales
Amount by Product” chart, and this action cross filters the other visualizations. The Filters pane is also available to allow me to apply page-level and visualization-level filters. If the report has multiple pages, I can navigate through the report pages. Users can also pop out visualizations to examine them in more detail. Currently, embedded reports don’t support interactive events, such as to do something when the user clicks a visualization on the report.
Figure 12.2 The Internet Sales Analysis report is embedded on a web page.
Understanding implementation steps
Embedding reports involves similar steps as embedding dashboard tiles:
Obtain the report identifier – Your app can call the “List All Reports” method to present a list of reports to the end user. Once the user selects a report, the app has the report identifier.
Embed the report – Once you have the report identifier, you can embed the report in your app, such as by showing the report content in an iframe.
Next, I’ll explain the two implementation steps in more details.
12.2.2 Enumerating Reports
Remember from the previous chapter that Power BI includes a REST API method for
enumerating reports. Your application can call this method to show a list of reports that the user can access.
Enumerating reports in My Workspace
The “List All Reports” method returns all the reports that are available in the user’s My Workspace. It has the following signature:
https://api.powerbi.com/beta/myorg/reports
The resulting JSON response is a collection of report elements. Each report element has id (report identifier), name, webUrl, and embedUrl properties. Here’s the definition of the Internet Sales Analysis report:
{
“id”:“b605950b-4f18-4eba-9292-82720f215693”,
“name”:“Internet Sales Analysis”,
“webUrl”:“https://app.powerbi.com/reports/b605950b-4f18-4eba-9292-82720f215693”,
“embedUrl”:“https://app.powerbi.com/reportEmbed?reportId=b605950b-4f18-4eba-9292-82720f215693”
}
Enumerating reports in another workspace
Chances are that your users will share their content. Similar to the “List All Dashboards”
method, the “List All Reports” method supports enumerating reports in another workspace by passing the group identifier. For example, if the group identifier of the Finance
workspace is e6e4e5ab-2644-4115-96e0-51baa89df249 (remember that you can obtain the group identifier by calling the “List All Groups” method), you can get a list of the reports available in the Finance workspace by using this signature:
https://api.powerbi.com/beta/myorg/groups/e6e4e5ab-2644-4115-96e0-51baa89df249/reports
TIP To show all the reports that the user can access, you need to enumerate the reports in the user’s My Workspace and the reports from all the groups (workspaces) that the user belongs to.
12.2.3 Embedding Reports
When the user picks a report, your application can use client-side JavaScript to embed the report. This is very similar to embedding dashboard tiles.
Requesting a report
If you report-enable a web application, you can display the report in an iframe element.
You need to use client-side JavaScript to communicate with Power BI Service and to pass the access token. As a first step, you need to reference the iframe element and handle its events:
var iframe = document.getElementById(”iFrameEmbedReport’);
var embedTileUrl = document.getElementById(‘tb_EmbedURL’).value;
iframe.src = embedTileUrl;
// iframe.src = embedTileUrl + “&width=” + width + “&height=” + height;
iframe.onload = postActionLoadReport;
You must handle the onload event in your code by defining an event handler for
iframe.onload. In this case, the postActionLoadReport function is the event handler.
Handling client-side authentication
Once the iframe triggers the load event, you need to send the access token to Power BI Service:
function postActionLoadReport() { // get the access token.
accessToken = ‘<%=Session[“authResult”]==null? null:
((Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationResult)Session[“authResult”]).AccessToken%>’;
// return if no access token if (”” === accessToken) return;
// construct the push message structure
var m = { action: “loadReport”, accessToken: accessToken};
message = JSON.stringify(m);
// push the message.
iframe = document.getElementById(‘iFrameEmbedReport’);
iframe.contentWindow.postMessage(message, “*”);;
}
First, the code obtains the access token from a session variable that stores the authentication result from the OAuth flow. The code creates a JSON push message structure to instruct Power BI Service to load the report, and then it passes the access token. Then the code posts the message to Power BI Service. At this point, the report should render on the page.
Filtering the report data
Similar to tiles, reports support limited filtering capabilities. This could be useful when you want to further filter the report content based on some user-specified filter, after the report filters are applied. You can pass a filter on the embed URL by using this syntax:
https://app.powerbi.com/reportEmbed?reportId=<report_id>&$filter={FieldName} eq ‘{FieldValue}’
Again, you can filter on any field in the underlying model, even though the field might not be used in the report itself.