Today we are excited to announce the release of our new JavaScript API, which provides bidirectional communication between Power BI reports and your application. The JavaScript API enables you to more easily embed reports into your applications and to programmatically interact with those reports so that the applications and the reports are more integrated. Two of the key features to call out with today's release are: much more advanced filtering of reports, and control over page navigation.
With this new functionality your application can open reports with the correct context for your users, as well as change that context after the report has already been loaded. For example, you could open a report to a specific customer and change that customer automatically as the user interacts with other parts of your application.
How does embedding with Power BI work?
To best understand the benefits of the Power BI JavaScript API, let’s examine how embedding in Power BI currently works. Embedding a Power BI report in your application is done with an iframe, which is hosted as part of the app. The iframe acts as a boundary between your application and the Power BI report. With no way to pass infromation through the iframe, the report cannot interact with your application and your application can’t interact with the report. While the iframe can make the embedding process a lot easier, this lack of interaction between your application and the Power BI report can sometimes make it feel like the report is not really part of your application.
Now the new Power BI JavaScript API will allow you to write code that can securely pass through the iframe boundary, so that your application can programmatically perform an action in a report and listen for events from actions that users make from within the reports themselves.
What can you do with the Power BI JavaScript API?
With the JavaScript API you can manage reports, navigate to pages in a report, filter a report, and handle embedding events. The following diagram shows the structure of the API:
Manage Reports
The JavaScript API enables you to manage behavior at the report and page level:
- Embed a specific Power BI Report securely in your application – try the embed demo application
- Set access token
- Configure the report with the following settings:
- Enable and disable the filter pane and page navigation pane – try the update settings demo application
- Set defaults for pages and filters – try the set defaults demo
- Enter and exit full screen mode
Learn more about embedding a report
Navigate to Pages in a Report
The JavaScript API enbales you to discover all pages in a report and to set the current page. Try the navigation demo application.
Learn more about page navigation
Filter a Report
The JavaScript API provides basic and advanced filtering capabilities for embedded reports and report pages. Try the filtering demo application, and review some introductory code here.
Basic Filters
A basic filter is placed on a column or hierarchy level and contains a list of values to include or exclude.
const basicFilter: pbi.models.IBasicFilter = {
$schema: "http://powerbi.com/product/schema#basic",
target: {
table: "Store",
column: "Count"
},
operator: "In",
values: [1,2,3,4]
} Advanced Filters
Advanced filters use the logical operator And or Or, and accept one or two conditions, each with their own operator and value. Supported conditions are:
- None
- LessThan
- LessThanOrEqual
- GreaterThan
- GreaterThanOrEqual
- Contains
- DoesNotContain
- StartsWith
- DoesNotStartWith
- Is
- IsNot
- IsBlank
- IsNotBlank
const advancedFilter: pbi.models.IAdvancedFilter = {
$schema: "http://powerbi.com/product/schema#advanced",
target: {
table: "Store",
column: "Name"
},
logicalOperator: "Or",
conditions: [
{
operator: "Contains",
value: "Wash"
},
{
operator: "Contains",
value: "Park"
}
]
} Handling Events
In addition to sending information into the iframe, your application can also receive information on the following events coming from the iframe:
- Embed
- loaded
- error
- Reports
- pageChanged
- dataSelected (coming soon)
Learn more about handling events
Next Steps
For more information about the Power BI JavaScript API, check out the following links: