Power BI enhanced report format (PBIR) in Power BI Desktop developer mode (Preview)

Enhancing team collaboration and automation is crucial for any enterprise BI development, which is the primary goal of Power BI Desktop developer mode. The Power BI enhanced report format (PBIR) for Power BI Project files (PBIP) represents a significant milestone in that direction. This new report format offers source control-friendly file structures, facilitating co-development and improving development efficiency for Power BI reports.

Together with TMDL for the semantic model, Power BI Projects now have a great source control experience for both report and semantic model:

Watch a demonstration of PBIR in action in the June 2024 update video (minute 4:09):

How to get started?

Saving as a PBIP using PBIR is currently in preview. Before giving it a try, you must first enable it in Power BI Desktop: go to File > Options and settings > Options > Preview features and check the box next to “Store reports using enhanced metadata format (PBIR)”.

After enabling the preview feature, when saving as PBIP, your entire report metadata will be stored in a folder named “\definition”:

Existing PBIP files can also be easily upgraded to PBIR by selecting “Upgrade” during the save operation:

Warning: the upgrade to PBIR is irreversible, so please save a backup of your PBIP files in case you want to go back to PBIR-Legacy (report.json) format.

Source control and co-development with PBIR

Saving your Power BI Project files (PBIP) using the Power BI Enhanced Report Format (PBIR) stores the report metadata as properly formatted JSON files.

With a JSON schema declaration at the top of the document. This schema URL is publicly accessible and can be used to learn all the available properties and their meaning. Additionally, it provides built-in IntelliSense and validation when editing with code editors like Visual Studio Code. For more details on PBIR  JSON schemas, please refer to the documentation.

Each page, visual, bookmark, etc., is organized into separate individual files within a folder structure, which greatly helps resolving co-development conflicts.

If you save your PBIP files in a Git repository, using PBIR will enable granular tracking of every report change. This allows you to easily resolve merge conflicts and clearly understand the modifications made by Power BI Desktop to the report:

Development efficiency with PBIR

The PBIR format not only enhances source control and co-development experiences but also opens up new possibilities for improving report development efficiency. In this blog post, you’ll discover simple yet powerful example scenarios to help with your daily report development.

Note that while making external changes is supported, it is an advanced operation. Any incorrect changes may cause errors when reopening the report in Power BI Desktop. For more details on PBIR external changes, refer to the documentation.

Scenario – Ensure visuals consistency across pages

It’s very common to design a report where a set of visuals with exactly same configuration are replicated across all pages. Examples include logos, slicers, and titles.

You can replicate visuals by copying and pasting them each time you make a change. However, this can be a cumbersome task and may lead to issues such as misaligned positions or broken bookmarks. With PBIR, there’s a better way: apply your changes to one page, then copy the visuals folders to other pages either manually or using scripts.

Begin by locating the page and visual folders to be copied. In the PBIR format, each page and visual is stored in separate folders. Look for the page display name in each page.json file:

Visuals do not have a displayName, so you need to check properties such as visualType, title, and position to identify the correct visual folder.

For more convenience next time, change the name of the page and visual folder to something more descriptive (you don’t need to change the name property, only the folder name):

After renaming the folders, you must restart Power BI Desktop to ensure it preserves the new names upon saving.

Whenever you modify the visual settings on ‘Page 1’, you can easily copy and paste the visual folders into all the report pages. This ensures consistency across pages automatically, as the entire visual configuration is copied, including the visual name referenced by bookmarks. This eliminates the need to manually sync changes across all pages using Power BI Desktop. This method is particularly efficient for large reports with numerous pages.

Scenario – Batch edits

How often have you designed a report and wanted to apply certain behaviors, like removing visual interactions or hiding visual-level filters across all pages and visuals, only to give up because you realized it would take hours to configure those properties manually? With PBIR, you can now make batch edits by identifying the change and applying it across all files, either manually or using a script.

You can easily apply this configuration using a script, by looping all visual files of the report and set the ‘isHiddenInViewMode’ property as ‘true’ for all the filters. Here’s an example of a PowerShell script that accomplishes this task:

$definitionPath = "[PBIR definition folder path]"

foreach ($file in Get-ChildItem $definitionPath -Recurse -Filter visual.json) {
    $json = Get-Content $file.FullName | ConvertFrom-Json

    if ($json.filterConfig.filters) {

        foreach ($filter in $json.filterConfig.filters) {
            $filter | Add-Member -MemberType NoteProperty -Name "isHiddenInViewMode" -Value $true -Force
        }

        $json | ConvertTo-Json -Depth 100 | Set-Content $file.FullName
    }
}

Scenario – Ensure default report configuration

Have you ever wished to always ensure a default configuration for your report, such as the default page and filter selection, but ended up forgetting to reset it after a development session, resulting in publishing with the wrong configuration?

With the PBIR format, you can achieve that goal by having a simple script that always applies such configuration. Apply this script before each deployment or as part of your deployment mechanism, such as Azure Pipelines.

Here’s an example of a PowerShell script that defines the default page and slicer for all report pages:

$definitionPath = "[PBIR definition folder path]"

# Set default page

$json = Get-Content "$definitionPath\pages\pages.json" | ConvertFrom-Json

$json.activePageName = "[default page name]"

$json | ConvertTo-Json -Depth 100 | Set-Content "$definitionPath\pages\pages.json"

# Get all year slicers from all pages and set default to current year

$slicerFiles = Get-ChildItem $definitionPath -Recurse -Filter visual.json | Where-Object {

    $json = Get-Content $_.FullName | ConvertFrom-Json

    $json.name -eq "[slicer visual name]"

}

foreach ($file in $slicerFiles) {

    $json = Get-Content $file.FullName | ConvertFrom-Json

    $json.visual.objects.general.properties.filter.filter.where.condition.in.values.literal.value = "$([datetime]::Now.Year)L"

    $json | ConvertTo-Json -Depth 100 | Set-Content $file.FullName

}