cancel
Showing results for 
Search instead for 
Did you mean: 
s-richert

Embed Power BI Goals in your app

Embed Power BI Goals in your app

With data flowing from every corner of an organization, it is easy to get lost in a sea of information where key data points are sprinkled across scattered reports and dashboards. Goals is a new Power BI feature that helps individuals, teams, and organizations keep track of their most important business metrics and objectives, packaged in a seamless experience anyone can use. To that end, we have introduced a new artifact type in Power BI called a “scorecard”. Scorecards hold a cohesive set of goals, presented in one unified view. A goal represents a single metric over time, which can be entered manually or automatically refreshed from an existing Power BI report.

If this sounds new to you, I encourage you to read through this introduction, discover everything you can do with Power BI Goals and what’s on our roadmap. Then, create your first scorecard and read on!

srichert_1-1628535681254.png

Example of a scorecard for the fictional Northwind company

 

In this blog post, we will walk through how to embed scorecards in your application in two different ways. A low code option via the scorecard’s secure publish url, and a more powerful option with the Power BI Javascript SDK. This is just a sneak peek; the feature is still being worked on and you can expect more control, customization options and flexibility for the public release.

Embedding a scorecard with secure publish

This is the simplest form of embedding, as it doesn’t require you to write any code with the Power BI SDK. Users will be asked to sign-in to Power BI before they can view the embedded scorecard.

 

 

 

<iframe src="https://app.powerbi.com/scorecardEmbed?scorecardId=<SCORECARD_ID>&autoAuth=true"></iframe>

 

 

 

 

As an example, let’s embed a scorecard in a SharePoint page:

1. Create a page, and add a new section of type Embed to it:

srichert_2-1628206130361.png

2. In the widget settings, paste the iframe code with the scorecard embed url:

srichert_3-1628535749690.png

 

3. That’s all, you can now publish the SharePoint page. If you intend to share it with other people, don’t forget to grant them access to the underlying scorecard

srichert_4-1628535821519.png

 

 

Embedding a scorecard with the Power BI Javascript SDK

Using the SDK enables a more seamless experience, users won’t have to sign-in to Power BI if they’re already signed-in with your application. It also provides more configuration options, letting you restrict certain scorecard features like editing or sharing.

Generating tokens for embedding

Before you can embed any kind of Power BI content with the SDK, you will need to generate an AAD token. For production use, this can be done by creating an Azure AD application and configuring it for use with Power BI:

If you just want to try out the SDK features without creating an AD application, you can use the access token from an authenticated Power BI session instead. Let’s create one using the Power BI management cmdlets:

  1. Open an admin PowerShell prompt and install the MicrosoftPowerBIMgmt module
  2. Login to Power BI using Login-PowerBI cmdlet
  3. Get the access token using the Get-PowerBIAccessToken cmdlet, and copy it (without the Bearer prefix)

srichert_6-1628206303336.png

Note: this token will expire after one hour, after what you will need to generate a new one to keep using the embedded scorecard

Using the Power BI Javascript SDK 

The SDK is web framework agnostic and will work the same whether your app runs on React, Vue, Angular, static pages etc. For simplicity, we’ll demonstrate how to use the SDK in a static HTML web page. Besides the installation and distribution process, the same steps should apply regardless of your app framework. 

1. Create a blank HTML page using your favorite code editor

 

 

 

<!DOCTYPE html> 
<head> 
    <title>Scorecard embedding</title> 
</head> 
<body> 
</body> 
</html> 

 

 

 

2. Download or install the powerbi-client npm package, and include the powerbi.js script from the package’s distribution folder in the header section of the web page:

 

 

 

<head> 
    <title>Scorecard embedding </title> 
    <script src="<url of powerbi.js>"></script> 
</head> 

 

 

 

Tip: for testing purposes, you can serve the file directly from a CDN. In this example, I’ll be using https://unpkg.com/powerbi-client/dist/powerbi.js 

3. Create a <div> element on the page, wherever you want the scorecard embedded. The SDK will replace the element with the iframed content upon loading the scorecard. 

 

 

 

<!DOCTYPE html> 
<head> 
    <title>Scorecard embedding</title> 
    <script src="https://unpkg.com/powerbi-client/dist/powerbi.js"></script> 
    <style> 
        #embedded-scorecard { 
            width: 1280x; 
            right: 720px; 
        } 
    </style> 
</head> 
<body> 
    <div id="embedded-scorecard"></div> 
</body> 
</html> 

 

 

 

4. Add the following code to the page body; replace ACCESS_TOKEN with the access token generated earlier, and SCORECARD_ID with the scorecard id:

 

 

 

<script> 
    let accessToken = '<ACCESS_TOKEN>'; 
    let scorecardId = '<SCORECARD_ID>'; 
    let embedUrl = `https://app.powerbi.com/scorecardEmbed?scorecardId=${scorecardId}`; 

    function embedScorecard() { 
        let config = { 
            type: 'report',             // Use ‘report’ as embed type (this will change to 
            tokenType: null,            // ‘scorecard’ in future releases)         
            accessToken: accessToken, 
            embedUrl: embedUrl, 
            id: scorecardId, 
            settings: { 
                hideShare: false,       // Show or hide the share button 
                hideChatInTeams: false, // Show or hide the chat in Teams button 
                disableEdit: true,      // Allow or prevent scorecard editing 
                hideSensitivity: false, // Show or hide the sensitivity bar 
            } 
        }; 

        let embedContainer = document.getElementById('embed'); 
        let scorecard = powerbi.embed(embedContainer, config); 
    } 
    embedScorecard(); 
</script> 

 

 

 

And here is the result ! 

srichert_5-1628535900957.png

Going further 

Use the scorecard object returned by powerbi.embed() to further interact with the embedded scorecard. 

Events: you can add the ‘loaded’ and ‘error’ event listeners to get notified when the scorecard loads or some error occurs in the session:

 

 

 

scorecard.on('loaded', function() { 
    console.log('Scorecard loaded'); 
}); 

scorecard.on('error', function(event) { 
    console.error(event.detail);           // Print error in the console 
}); 

 

 

 

Update settings:

 

 

 

scorecard.updateSettings({ 
    hideShare: false, 
    hideChatInTeams: false, 
    disableEdit: false,      // Users can now edit the scorecard 
    hideSensitivity: false, 
}); 

 

 

 

Refresh the access token:

 

 

 

scorecard.setAccessToken(updatedToken); 

 

 

 

 

Current limitations and  known issues

  • Only AAD tokens are currently supported. Embed tokens cannot be used with scorecards 
  • This feature is still in preview and the API is not yet stable. We may introduce breaking changes in upcoming releases 
  • Settings are currently limited to enabling or restricting certain features. In future releases, we will let you customize the experience further. For instance, you will be able to change colors and fonts so it better matches your organization branding and website styles.
  • [Bug] Embedding scorecards through SDK might hang during initialization. If this happens, try again in incognito mode. This issue has been resolved and the fix should be deployed in the coming weeks

We can’t wait to see what scorecard integrations you will come up with, and we would love to hear your feedback. Do let us know if you have any question or suggestion for improvement ! 

 

Comments