Why Power BI developers should care about the Power BI enhanced report format (PBIR)
Microsoft's introduction of the new Power BI enhanced report format (PBIR) within Power BI projects, announced in the Power BI June 2024 Feature Summary, marks a significant milestone in improving the Power BI Desktop developer mode experience. Instead of one long JSON file, like the PBIR-Legacy report format (report.json), the new PBIR report format has a folder structure, with separate files for each report component - visual, page, bookmark etc.
The new PBIR report format files:
- Offer better integration with source control systems, like Git, where you can track version history and resolve merge conflicts.
- Can, for the first time, be externally modified within a code editor such as Visual Studio Code (VS Code).
The new PBIR report format opens up a whole host of benefits for Power BI developers, which we will explore in this blog post.
Note: During the Public Preview of Power BI Desktop developer mode, the new PBIR report format is opt-in only, however, it is due to become the default report format at General Availability.
TLDR
Microsoft's new Power BI enhanced report format (PBIR) within Power BI projects, replaces the PBIR-Legacy JSON file with an intuitive folder structure, with separate files for each report component (visual, page, bookmark etc.), enabling capabilities such as:
- Enhanced collaboration with source control: PBIR report format files can be integrated with source control systems like Git. For the first time, multiple developers can collaborate on Power BI reports simultaneously, and leverage collaboration mechanisms such as performing code reviews (PR process) and resolving conflicting changes (merge conflicts).
- Tracking report changes with source control: Developers can now track version history at the granular level, compare different report versions and revert back to previous versions of reports.
- Improved report development efficiency with code editor support: PBIR report format files are publicly documented and human readable, so developers can now use code editors such as Visual Studio Code for more productive and efficient authoring of Power BI reports e.g. batch edits and copying pages/visuals/bookmarks from one report to another.
- Programmatic generation of report components: Developers can leverage re-usable component libraries and use code generation techniques to programmatically generate report components such as pages and visuals.
- Greater control over report configuration: With the new PBIR report format, developers can programmatically enforce the default configuration of the report e.g. setting a default page or slicer selection. Developers can do this manually in a code editor or by using a script that is applied before each deployment or as part of a deployment pipeline.
- Greater control over report design: The new PBIR report format offers greater visibility and control of visual properties. This means that developers can now adjust visual properties such as alignment, spacing and sizing to exact dimensions.
1. Source control
Enhanced collaboration with source control
Power BI has been a huge part of every data and analytics project we've delivered at endjin. There is no doubt that it is an extremely valuable tool, however, there has always been one big drawback - the lack of source control support for Power BI Desktop files. This has meant that only one person can work on a Power BI report at a time which has impacted productivity as report development is constrained to the speed of one developer. If we want to work on the report alongside another developer in real-time, we can only do this by screensharing whilst one person has the report open and drives. This greatly slows down the process, as two developers could have been working on the same report simultaneously, but building different pages, for example.
However, by using source control with the new PBIR report format, multiple developers can now work on the same report simultaneously. This enhances productivity as we're no longer constrained to the speed of one developer. Developers can integrate their changes using the traditional branching and merging / PR process used for other code artefacts. They can even work on the same page simultaneously. However, be cautious of doing this, as there is a risk of overlapping efforts. Although, any conflicting changes will be flagged by source control as merge conflicts, which can then be resolved. The ability to collaborate on Power BI reports is a significant benefit, and aligns with our values at endjin, where we believe in the power of working as a team.
Tracking report changes with source control
With a Power BI Desktop file, there is no meaningful way for us to track changes that have been made to our Power BI report. A .pbix file is an opaque binary file format, that cannot be parsed, visually or with common DevOps tools, and cannot be used with traditional source control systems. To work around this, between report development sessions, we've had to develop a pretty regimented process of checking .pbix files in/out of SharePoint and using the check-in comments to document changes. We can then use the version history feature within SharePoint to see the check-in comments made by each developer. However, check-in comments only provide a small textual summary of report changes. Without source control support like Git, we cannot see the report changes in granular detail, nor can we compare different versions of reports. This means that between versions of reports, mistakes could easily get introduced, for example, we could accidentally move or filter a visual during report development in Power BI Desktop. Or, when checking in a report, we could unknowingly overwrite another developer's changes.
However, with the new PBIR report format, we can now easily track changes that have been made to our Power BI reports. The PBIR report format files are source control friendly, and so we no longer need to use SharePoint as a means to track version history. Instead, we can take full advantage of the benefits of source control systems. By saving our PBIR files in a Git repository, we can granularly track version history at the code level, compare different report versions and revert back to previous versions of reports. Looking at the Git diffs, we can clearly understand report updates, as the new PBIR report format has a folder structure, with separate files for each report component - visual, page, bookmark etc.
Moreover, following standard PR based processes, we can now ensure that only intentional changes are integrated into the final report. Any proposed change to a Power BI report must be reviewed and approved before it can be integrated into the main codebase, and any conflicting changes (merge conflicts) must be resolved. This also means that developers can now be confident that when they make report updates, they will not be overwriting another developer's changes. At endjin, delivering quality work is important to us, and so source control as a quality gate is a great way for us to reduce the risk of introducing bugs or errors into our Power BI reports.
2. An alternative way to work on Power BI reports
Code editor support
In the initial release of Power BI projects, external modification to the PBIR-Legacy report format file was not supported. However, the new PBIR report format files allow modification from non-Power BI applications such as code editors e.g. Visual Studio Code (VS Code). This changes the way we might approach Power BI report development. Instead of editing Power BI reports in Power BI Desktop, we can choose to make report updates programmatically, which opens up a whole host of benefits.
The new PBIR report format files are easy to work with within a code editor. Firstly, each visual, page and bookmark has a separate individual JSON file, organised within an intuitive folder structure, so it is easy to identify the specific report component we would like to make updates to. Secondly, each report component is well documented within the PBIR report format files. Each PBIR file has a JSON schema URL at the top of the file which is publicly accessible and provides documentation for all of the available properties of that report component (all of the JSON schemas are published on GitHub). The JSON schema declaration also provides built-in IntelliSense and syntax validation, so we can easily detect when we're using an incorrect property name or type.
Note: Power BI Desktop isn't aware of changes to Power BI project files made by other tools. Therefore, if you make any changes to your Power BI report by editing and saving the PBIR report format files in a code editor, you need to re-open your report in Power BI Desktop for the changes to be applied here.
Code editor support for the PBIR report format marks a significant step towards Power BI being a developer tool. Editing our Power BI reports is now a similar experience to working with any other code base.
3. Improved report development efficiency
Leading on from this, the new PBIR report format brings several improvements to the report development experience. In our experience developing Power BI reports for our customers, we've found that certain report development tasks in Power BI Desktop can be quite time consuming. For example, manually copying and pasting visuals over to new pages/reports or consistently configuring and formatting visuals. These tasks are particularly cumbersome for reports with a high number of pages. The new PBIR report format offers ways for us to improve efficiency with these report development tasks.
Ease of copying report components
When developing Power BI reports for our customers, we've found that it is very common to have a set of visuals with exactly the same configuration replicated across all pages, for example logos, slicers, and titles. It is also very common for reports to have a set of pages that follow the same structure. However, in order to copy report components between pages or reports, we are limited to using the copy and paste functionality within Power BI Desktop, which is time-consuming and susceptible to human error.
With the new PBIR report format, there is now a more efficient way for us to copy report components between pages and reports. Now, we can simply locate the page we would like to replicate within the PBIR files and copy the 'visuals' folder containing all of the visuals for that page to other pages. Or if we would like to just copy specific visuals e.g. the title across to all pages, we can just copy the folder for that specific visual over. Copying files can be done either manually within a code editor/file explorer or using scripts.
The ability to copy report components outside of Power BI Desktop is a huge time saver, and massively reduces the risk of introducing bugs when putting together our Power BI reports, instead ensuring we have consistency across pages.
Another new benefit that the new PBIR report format brings is the ability to copy bookmarks from one report to another. The entire visual configuration is copied when you copy the visual file over, including the visual name referenced by bookmarks, so when you also copy over the associated bookmark file within the 'bookmarks' folder, this automatically syncs the two together and makes the bookmark available in Power BI Desktop.
The ability to copy bookmarks over to another report was previously not possible with Power BI Desktop files, so this is an improvement we’re happy to see with the new PBIR report format and will be taking advantage of to speed up our report development.
Batch edits
Another common report development task we carry out when developing reports for our customers is applying the same change to multiple visuals or pages within the report. For example, the customer might ask us to change the font size of the title across all pages. If we were to do this manually within Power BI Desktop, this would be very time consuming, especially if the report has a large number of pages. Manual updates via Power BI Desktop are also prone to human error. Now, with the new PBIR report format, we can make batch edits to our Power BI reports. This can be done manually by opening the PBIR files in a code editor and updating the target JSON property values, or programmatically using a script. This feature is a huge benefit, as not only does it simplify and speed up report development, it also ensures that our report updates are consistent and accurate.
Programmatic generation of report components
With the new PBIR report format, we also now have the ability to store templates for pages/visuals that we think are reusable across projects in a reusable component library. Rather than building a report pages from scratch, we can leverage these templates, using code generation techniques to build up pages/visuals from the templates. For example, we could create a template of a 'visual.json' file, with placeholders for the variable parts of the JSON structure, such as the fields and measures used in the visual, and then use a script to replace these placeholders with actual values. Using this method, we can efficiently create report components, reducing manual effort and saving development time.
4. More control over report configuration and design
Report-wide settings
The user experience is a crucial element of any Power BI report, so when creating Power BI reports for our customers, we always want to ensure that they are deployed with the configurations we expect for the end-user. In order to do this, at the end of a report development session, we have to manually check that the report is configured in the way we expect before saving the report and closing Power BI Desktop. For example, we check that we have the correct filter selection on each page and that we save the report on the cover page. This approach is prone to human error and can also be quite time consuming, especially if there are a large number of report pages. However, with the new PBIR report format, we can now enforce the default configuration/ "state" of our Power BI report programmatically.
There are several places where report-wide settings can be applied in the new PBIR report format files. In the 'report.json' file, settings such as applying a theme to the entire report or setting filters that apply to the entire report (all pages and all visuals) can be applied.
We can also apply report-wide settings in the 'pages.json' file. Here we can set our default page using the 'activePageName' property. We can also set the page order of our Power BI reports via the 'pageOrder' property which lists out the order of pages by page name. Re-ordering pages manually using the drag and drop method in Power BI Desktop is extremely time-consuming, but now we have a way to do this programmatically which is a huge win.
While we can manually apply report-wide settings by editing the PBIR files in a code editor, we also have the option to use a simple script that automates the process of applying the default configuration to our report. For example, we could use a PowerShell script that sets our default page in the 'pages.json' file, and also sets a default slicer selection e.g. setting the year slicer to the current year on all pages. This script can be applied before each deployment or as part of our deployment pipelines.
Overall, the benefit of report-wide settings, enabled by the new PBIR report format, is that it allows us to programmatically enforce the default configuration of our reports. Because we have this quality gate in place, we can now spend less time ensuring we always have the correct configuration at the end of a report development session, and more time focusing on generating insights within our Power BI reports.
Pixel-perfect design
A good design is a crucial element of any Power BI report, so when creating Power BI reports for our customers, we always want to ensure that our visuals are aligned and we have the correct spacing and sizing. In Power BI Desktop files, there is no easy way to achieve this as each visual needs to be manually checked and aligned. However, the new PBIR report format offers us greater control over visual alignment, spacing and sizing. Within the 'visual.json' file of each visual, visual properties can be adjusted to exact dimensions, either via a code editor, or programmatically via a script. This feature provides us with an easy and accurate way to ensure that we have correctly spaced and aligned our visuals.
The ability to configure visual properties using the 'visual.json' files also opens up new levels of control over the formatting of our visuals which was previously not possible within Power BI Desktop. For example, in Power BI Desktop, setting the column width of a matrix visual requires dragging the columns with your mouse and eyeballing the columns to ensure that they are of the desired width. However, with the new PBIR report format, you can specify the column width as a numeric value, or even create scripts to dynamically determine the column width. This level of precision and control the new PBIR report format brings to report design helps us to deliver more consistent and polished reports.
5. The future of Power BI projects
The new PBIR report format is currently in Preview, and you can only create or convert existing Power BI project files to PBIR using Power BI Desktop. All reports created in the Service, will continue to use PBIR-Legacy as the default report format. However, once General Availability of Power BI projects is reached, the new PBIR report format will become the default. Therefore, it is important to understand and adopt the new PBIR report format now, as it will soon be the standard for all Power BI project files. By familiarising yourself with PBIR, you can stay ahead of the curve and ensure a smooth transition when the format becomes the default.
Please be aware though that there are several Power BI Service limitations with the Public Preview PBIR report format. These restrictions will be removed in the following months, however, please read through the limitations carefully in the Microsoft documentation before you adopt the new PBIR report format.
Conclusion
The new Power BI enhanced report format within Power BI projects offers a host of features that can significantly benefit Power BI developers. From enhanced collaboration to an improved report development experience, the PBIR report format is a welcomed improvement to Power BI projects, and for us at endjin will have a positive impact on how we deliver Power BI reports efficiently and effectively for our customers. By leveraging the new PBIR report format, we can now create higher-quality reports, in a more time-efficient way, ultimately driving faster insights and decision-making for our customers.
If you want to stay on top of all the news and articles from the Power BI ecosystem, then I'd definitely recommend signing up to endjin's free Power BI Weekly newsletter.
