Introducing the new Power BI JavaScript API

Written by Josh Caplan as seen on MicrosoftCorporation

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:

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"
    }
  ]
}

Learn more about filtering

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

Get started with Power BI

Microsoft Power BI helps you stay up to date with the information that matters to you. With Power BI, dashboards help you keep a finger on the pulse of your business. Your dashboards display tiles that you can click to explore further with reports. Connect to multiple datasets to bring all of the relevant data together in one place.

Need help understanding the building blocks that make up Power BI? See Power BI - Basic Concepts.

If you have important data in Excel or CSV files, you can create a Power BI dashboard to stay informed anywhere and share insights with others. Do you have a subscription to a SaaS application like Salesforce? Get a head start by connecting to Salesforce to automatically create a dashboard from that data, or check out all the other SaaS apps you can connect to. If you are part of an organization, see if any organizational content packs have been published for you.

Read about all the other ways to get data for Power BI.

Step 1: Get data

Here's an example of getting data from a CSV file. Want to follow along with this tutorial? Download this sample CSV file.

Sign in to Power BI. Don’t have an account? You can sign up for Power BI for free.

1. If you're in your workspace, select Get Data at the bottom of the left navigation pane.

   

2. Select Files.

3. Select Local File, browse to the file on your computer, and choose Open.

   

4. Power BI uploads the CSV file and adds it as a new dataset (the yellow asterisk indicates a new item). Since we did not already have a dashboard, Power BI also created a new dashboard for us. In the left navigation pane, the new dashboard is listed under the Dashboards heading, and the new dataset appears under the Datasets heading.

   

Step 2: Start exploring your dataset

Now that you have connected to data, explore to find insights. When you've found something you want to monitor, you can create a dashboard to keep up-to-date with changes.

1. Select the dataset image on the dashboard to explore the data you just connected to or, under the Datasets heading, right-click the dataset name and select Explore.

   

   Another way to explore your data is Quick Insights. For more information, see Introduction to Quick Insights

2. In the Fields list on the right side of the page, select fields to build a visualization. Select the checkbox beside Gross Sales and Date.

   

3. Power BI analyzes the data and creates a visual. If you selected Date first, you'll see a table. If you selected Gross Sales first, you'll see a chart. Switch to a different way of displaying your data. Try changing to a line chart by selecting the line chart option.

   

4. When you have a visualization you want on your dashboard, hover over the visualization and select the Pin icon. When you pin this visualization, it will be stored on your dashboard so you can track the latest value at a glance.

   

5. Because this is a new report, you need to save it before you can pin a visualization from it to the dashboard. Give your report a name (e.g., Sales Over Time) and select Save and Continue.

   

   The new report appears in the navigation pane under the Reports heading.

6. Pin the tile to an existing dashboard or to a new dashboard.

   

   • Existing dashboard: select the name of the dashboard from the dropdown.

   • New dashboard: type the name of the new dashboard.

7. Select Pin.

   A Success message (near the top right corner) lets you know the visualization was added, as a tile, to your dashboard.

   

8. Back on your dashboard, you can see your new visualization. Make your dashboard even better by renaming, resizing, linking, and repositioning tiles.

   
   You can select the new tile on your dashboard to return to the report any time.

9. For a quick exploration of your data, try asking a question in the Q&A box. For example, try typing "what segment had the most revenue".

   

Step 3: Continue exploring with Q&A

1. Select the pin icon to show this visualization on your dashboard too.

2. Pin the visualization to the Financial Sample dashboard.

   

3. Select the back arrow to return to your dashboard where you'll see the new tile.

Ready to try more? Here are some great ways to explore more of Power BI.

• Connect to another dataset.

• Share your dashboard with your colleagues.

• Read tips for designing dashboards.

• View your dashboards with a Power BI app on a mobile device.

Not quite ready to jump right in? Start with these topics designed to help you feel comfortable with Power BI.

• Learn how reports, datasets, dashboards, and tiles all fit together

• Power BI videos

• See what samples we have available for you to use

Source: powerbi.microsoft.com

Watch Microsoft Mechanics for Power BI updates

On October 22, 2015 marks the launch of Microsoft Mechanics, an official new show and video platform for IT professionals and tech enthusiasts. Shows comprise informative demos, how-tos and insights from the engineers and tech leaders behind our technology each Wednesday or as news breaks, all in around ten or so minutes.

Beyond the news and blog announcements, it’ll help you to see the technology for yourself, get broader context and understand the potential application so that you can decide whether or not to explore further.

Stay informed, subscribe to Microsoft Mechanics to get updates.