Breaking changes in UI5 – PDFViewer

Updating SAPUI5 should not introduce breaking changes. UI5 uses semantic versioning, and as long as the major release does not change, you should be safe: update UI5, and get automatically the latest features, while your old apps continue to work. The app might drift away further and further from the current best practices, but continue to work. That’s the theory. And in reality? It is a rare occasion that updating the UI5 library gets you into trouble while coding close to the UI5 API and best practices. But it can happen.

PDFViewer enhancement

A recent example of this is the UI control PDFViewer. PDFViewer was enhanced, and the property isTrustedSource introduced (since states 1.121.1, but also made available for lower releases). Documentation for version 1.120.6. Parameter is not available in 1.120.4.

The default value of this parameter is false. Introducing the parameter is not a breaking change. Introducing new features is what you want, that’s what makes semantic versioning great. What breaks the behavior of PDFViewer is that the default value is set to false. The previously default behavior was true. SAP Note 3429273: starting with SAPUI5 version 1.120.7, the newly introduced parameter is taken into consideration.

The (new) default value causes the PDFViewer to NOT continue to display the PDF directly (true: embedded). It will only show the download (false: link mode) button. Therefore, changing the default behavior of earlier versions and what users used to see: no PDF, but a download link.

This is the breaking change: apps that showed the content embedded to the user won’t do this after the UI5 update. For the users, this is a breaking change. To have the old behavior, the newly introduced property needs to be set to true. This will open the PDF directly in the PDFViewer as it was the default behavior before the change. To solve this, developers need to adjust their app: include the parameter isTrustedSource and set it to true. This is a (rare) case where updating UI5 includes adjusting UI5 apps to have the same behavior as before.

Breaking change?

Is this now a breaking change? Depends on your interpretation. From the API level, no. It is not a breaking change. A new feature is introduced, not removed, nor an existing changed. However, the behavior of the app is changing. Why SAP did this is nicely explained in SAP Note 3446076. A security issue was found when opening PDFs directly. The fix is to outsource the solution to the app developer: make sure the PDFs shown are safe.

Security

SAP did not have many choices here. Introducing a new parameter and setting the default value to not load the PDF is more or less the only alternative. The link option – the user clicks on the link to open the PDF – makes it not safer than before. In the browser, this opens the PDF in the same PDF viewer as in the embedded mode: the PDF viewer of the browser, e.g. Chrome. Users would need to set the Chrome property to download PDFs by default to not open it in Chrome. Opening a compromised PDF in Chrome should cause the same harm as in the PDFViewer. To get a higher level of security, the link should open a separate PDF viewer app. Decade(s) ago this was common, but nowadays? Why the link option? The difference: the user clicked the link. OK, we can now blame the user when something goes wrong (why did you click the link?), but honestly: if there is an app I write, and it loads content, it only should load content I trust and that therefore should be secure to access / load. As said already: not easy to handle by SAP. Their choice is better than nothing (for SAP).

Communication

The behavior breaking change was introduced in UI5 1.121.1. The version was released on March 11 2024.

The note 3429273 version 1 is from 5. February 2024.

All of this happened before UI5con 2024. Would have been nice to get some updates on breaking changes introduced in the last 12 months in UI5, e.g. in the keynote. Or having at least one session at UI5con that talks about these kinds of changes. Honestly, even one session like: “What happened in the last 12 months in UI5” would be nice. Enhancements that change the expected behavior of apps bear the risk to undermine the confidence users have into UI5 apps.