Hi everyone, after a short break for the holidays we are back with the latest updates for Power BI Developer community. Don’t forget to check out the November blog post, if you haven’t done so already.
Power BI Embedded
Here is the list of January updates for Power BI Embedded
Embed capabilities
– Single visual embedding
– Custom layout
– Tile embedding enhancements
– Phased loading of embedded content
Automation & life-cycle management
– Update report
– Tile & Dashboard RLS support
New capacities in Azure
– ARM PowerShell
Single visual embedding
This month we are very excited to release this highly requested feature that supports visual embedding. From now on, you can give your users more than a general ‘Analytics’ page. By embedding visuals into your application, you can get in-page analytics where only the most relevant and insightful data resides next to your user’s day-to-day actions, making data-driven decisions easier than ever.
The fully flexible API gives you the capability to choose which visual to show for each user, or switch visuals in the same iframe during the user’s session. You can optimize the size and layout of each visual at any time using the new ‘custom layout’ feature, which will be further discussed in this post.
Unlike tile embedding, in order to embed a visual you specify the report and report page for the visual. From the list of visuals in a page, you define which visuals will be hidden and which will be visible. This methodology has few advantages:
- Switching visuals– by switching visuals on the same report, you do not need to generate a new embed token. Just switch the visibility definition of the visuals and you will immediately show different visuals that was already rendered.
- Displaying multiple visuals– Why settle for a single visual, if you need more than one to gain insights? As you define the visibility of each visual, you can choose to show multiple visuals on the same iframe and define in real time the size and position of each one. By showing multiple visuals, you also enjoy interactivity and cross- filtering between visuals, just like a regular report.
You can explore the new API through our Live demo tool, by choosing ‘Sample Report Visual’. You can read more on Single visual embedding in our documentation.
Custom layout
Custom layout allows you to set and change the size of a report page layout, or control the size, position and visibility of a report visual.
1. Page layout– When building a report page through Power BI Desktop, you configure the layout using two fields: page size type and page layout.
By default, each time you embed a report, it uses the configuration made in Power BI Desktop. With Custom Layout, you can dynamically set the definitions to optimize the report layout inside your application page. You can change the layout during the session, based on specific events such as content change in the application page or browser resizing.
2. Visual layout– This feature also supports single visual embedding. Through custom layout, you define which of the visuals you wish to display and specify their size and position on the canvas. Using this capability, you have full configuration control on the appearance of the visuals on the canvas dynamically during the user’s session.
For example, assume that your application’s customer has different departments. Instead of creating copies of the same report or report pages for each department and make the modifications, you can show the same report page and expose only the relevant visuals to that user. Custom layout allows you to optimize the position of each visual so that the experience will be seamless.
Another example allows users to choose which visuals they want to follow and create their own customized view of the report. Learn more on Custom layout.
An example and code snippet can be found in the Live demo tool. To use the live demo tool for custom layout, follow these steps:
- Choose ‘Sample Report’
- Click ‘Run’
- Go to ‘Interact’ tab
- Scroll and choose ‘Apply custom layout’
- Click ‘Run’ again
Phased loading of embedded content
The loading of an embedded artifact is done using ‘embed’ call, containing an embed configuration object and the <div> element that contains the iframe. Once called, the embedded object is loaded in front of the end-user, and any interaction with the object is done while shown to the end-user.
To improve the end-user experience and provide more tools for developers, we have extended this flow with more JavaScript calls that add phases to the embedding process:
- Preload– the ‘powerbi.preload()’ call uses the browser’s cache and download scripts prior to showing the embedded object itself. This can be proven useful for applications hosting several embedded reports. A ‘ready’ event will be fired once the preload is completed. You can read more details on our previous blog post.
- Load metadata– the ‘powerbi.load()’ call helps retrieve info on the embedded object, and dynamically changes the settings or the <div> element in the background, before the object is displayed to the end- user. For example, you can use this function to get pages and then decide which page to show the end-user. Or, you can use ‘get visuals’ and then decide which visuals you wish to show or hide to the users. If you used this function, you need to call the ‘render()’ function to show the embedded object. Once the load is completed, a ‘loaded’ event will be fired.
- Render object– The final call, in case you implemented the ‘powerbi.load()’ function, is ‘render()’. The render completes the last actions needed to render and show the embedded object to the end- user. A ‘rendered’ event will be fired once the render is completed.
While the 'load' and 'render' functions must be used together, 'preload' is independent of the prior two. You can use 'embed' function to show the embedded object after 'preload', as it was done until now. One can also utilize the full phased procedure by calling 'preload', 'load' & 'render' in this respective order.
Tile embedding enhancements
We added support for more tile types that can be embedded. Here are the additional tile types:
- live page tiles
- Custom visual tiles
- R visual tiles
- live stream tiles
- image tiles
- video tiles
- web content tiles
- Q&A tiles
- Visio tiles
Read more on tile embedding.
Update report
After releasing the ‘Clone report’ and ‘Clone Tile & Dashboard’ APIs, which allowed to copy content so that multiple customers can get analytics on their data with minimal API calls, we now release an API to support updating reports.
As an independent software vendor (ISV) with multiple customers, or an organization with different departments, you can hold a copy of the report connected to different data for each of them. We highly recommend saving analytical content for different customers or departments in separate workspaces.
Now let’s assume you have 20 customers (or 20 departments), you clone and rebind the source report 20 times to give each customer his own view of the data in his dedicated workspace. Now you wish to change the source report, fix some small bugs and add some customer requirements. Using the new API, you can automatically update all reports that were created from the same source report, while keeping the original report ID used for embedding and sharing. This means no effect on your code when you wish to improve your reports.
The benefits of this operation go beyond cloned/imported reports. You can update a target report by providing any source report as long as the dataset schema complies with the update. The dataset itself in the target report will not change, and the updated report will continue to be linked to the previous dataset.
Note that an update operation changes the entire content of the report. Any visual/ page that is not on the source report will be deleted once the operation takes place. We highly recommend as a best practice to keep the source and target IDs of all objects you are cloning, so that the ‘Update’ operation can be done easily and with minimal errors.
Tile & Dashboard RLS support
We now support row-level security (RLS) for Tiles and Dashboards embedding. The implementation is similar to Report RLS and is done through the embedToken. The API accepts both multiple datasets and multiple identities to support dashboards containing multiple tiles that are connected to different reports.
Here are some examples of how to change the ‘identities’ Json when calling a REST API with multiple roles or datasets:
1. Using ‘effectiveIdentities’ to generate a token which specifies using ‘userA’ with role ‘Role1’ to access a dataset, and ‘userB’ with role ‘Role2’ to access a different dataset:
var effectiveIdentities = new []
{
new EffectiveIdentity
{
Username = "userA@contoso.com",
Roles = new[]
{
"Role1"
},
Datasets = new[]
{
"1ee99c99-6475-4b62-9a55-015018cee352"
}
},
new EffectiveIdentity
{
Username = "userB@contoso.com",
Roles = new []
{
"Role2"
},
Datasets = new []
{
"c1e3dfcc-1c20-4e1d-bd35-02d2e5512480"
}
}
};
2. Using ‘effectiveIdentities’ to generate a token which specifies using ‘userA’ with role ‘Role1’ with 2 different datasets:
var effectiveIdentities = new []
{
new EffectiveIdentity
{
Username = "userA@contoso.com",
Roles = new []
{
"Role1"
},
Datasets = new []
{
"1ee99c99-6475-4b62-9a55-015018cee352",
"c1e3dfcc-1c20-4e1d-bd35-02d2e5512480"
}
}
};
Generating token for embedding a dashboard with ‘effectiveIdentities’ as specified in option #1 or #2:
var powerBIclient = new PowerBIClient(credentials);
var requestParameters = new GenerateTokenRequest(accessLevel: "View", identities: effectiveIdentities);
var token = await powerBIclient.Dashboards.GenerateTokenInGroupAsync(groupId, dashboardKey, requestParameters);
Azure Resource Manager (ARM) API using PowerShell
In November we released the ARM API to automatically manage Power BI Embedded capacities (A SKUs). This now can be done through PowerShell commands. You can find more information on ARM API in our previous blog, or through documentation. The following commands have support in PowerShell:
- Get capacity
- Create new capacity
- Remove capacity
- Resume capacity
- Suspend capacity
- Test the existence of a capacity
- Update capacity details
Power BI Embedded PowerShell cmdlets are in release 5.1.1 of Azure PowerShell.
If you are puzzled or run into few issues, be sure to check our resources that can help you get through:
- ‘Troubleshooting’ doc to help you get by all the obstacles on your way for building a great app.
- FAQ doc to answer all your question regarding the Product, licensing and Azure offering.
- Community forum for developers, to seek answers or ask any other questions you have.
Custom Visuals
API 1.10
API 1.10 is available on GitHub and adds the following capabilities:
Authentication with Azure Active Directory (AAD)
Custom visuals can call this API to get an AAD token that authenticates them, to be used with other AAD based services for Single Sign-On (SSO). This enables developers to build visuals that can be authenticated through SSO with other services. For this to work it is required that:
- The service is registered with AAD, to approve the token generation
- The service is registered in Power BI, to approve the visual to go out to request the token
If you want to use this API, contact the custom visuals support team at pbicvsupport@microsoft.com for details
Localize anything with LocalizationManager
API 1.6.2 introduces the localization of the formatting pane through the capabilities.json file. Now, developers can use the localized strings inside their TypeScript code, and practically localize any string that is being used inside the code, like tooltips, chart item names (e.g. 'axis', 'legend' , etc.). See the documentation for more details.
As always, feel free to use all the communication channels at your disposal to connect with our team, share your thoughts and ask questions:
- Community
-
Contact us for support- pbicvsupport@microsoft.com
That’s all for this post. We hope you found it useful. Please continue sending us your feedback, it’s very important for us. Have an amazing feature in mind? please share it and vote in our Power BI Embedded Ideas forum, or our Custom Visuals Ideas forum.