Business agility is more important than ever as the pace of change accelerates. Companies need to minimize the time they spend on system upgrades and software updates, so they can focus on innovation that benefits their customers. SAPUI5 flexibility provides the capability to extend an SAP Fiori app in the UI layer modification-free, i.e. without risking incompatibilities and thus ensuring lifecycle stability when the original app is updated. This approach works well with SAP Fiori elements apps, which comprise the majority of the apps we ship with SAP S/4HANA.
In this blog we deep-dive on the UI part of extending an SAP-delivered Fiori app in an OnPremise environment as a developer, i.e. using adaptation projects. And we focus on SAP-delivered apps that were built using SAP Fiori elements. It’s the same approach as for SAPUI5 freestyle Fiori apps, but there are a few differences – and those are the focus of this blog. Find out more about adaptation projects in general in units 3 & 4 of week 4 of the Developing and Extending SAP Fiori Elements Apps openSAP course.
It is always worth checking the app-specific extensibility documentation, which is available via the SAP Fiori reference library per app on the implementation information tab.
Note: If you want to learn about how to extend a SAP Fiori app in SAP S/4HANA Cloud, please check the extensibility explorer
When to use adaptation projects (developer adaptation)
To extend SAP’s standard apps, SAPUI5 Flexibility offers capabilities not only for developers but also for key users and end users using simple visual / WYSIWYG tools. Key user adaptation and developer adaptation are modification-free, upgrade-safe and can extend standard apps without the need for pre-defined extension points. Both will result in a variant of the original app, and you can also combine them as they are based on a layering concept – meaning that adaptations done by different user types (= on different layers) are compatible and complementary.
If your requirements can be covered by either key user or developer adaptation, it is up to you who shall be in charge: the key user (typically someone from the business department) or the developer (usually from the IT department). Using key user adaptation of course has the advantage that it is a no-code environment, easy to use for business experts and it comes without the need to set up an IT project. Hence most customers opt to use key user adaptation as much as possible.
App before key user adaptation
App after key user adaptation
Here is an overview of the features supported by key user vs developer adaptation:
| Use Case | Key User Adaptation | Developer Adaptation |
| Ensure that the most relevant information to your team is in the right place | Moving UI elements (fields, sections, etc.) | Moving UI elements (fields, sections, etc.) |
| Useful for e.g. removing unnecessary elements from the screen to save space and increase usability | Adding and removing UI elements | Adding and removing UI elements |
| Make the UI more understandable and accessible for your team | Renaming UI elements | Renaming UI elements |
| Bring related information together to simplify your screens | Combining and splitting fields | Combining and splitting fields |
| Change e.g. which columns are displayed on a SmartTable based on your team’s needs | Changing settings of UI elements | Changing properties of UI elements |
| Enable, for example, the display of a map from an external provider based on an available address | Embedding external content (for example, external web pages) | Embedding external content (for example, external web pages) |
| Easily switch between different screen layouts (views) for different business contexts | Adapting views | Creating control variants (views) |
| Extend your application with new controls and custom logic | Adding fragments to extension points or aggregations & Controller Extensions | |
| Especially important for international teams – you can ensure that custom elements are also available on your users’ languages | Adding internationalization to make apps translatable | |
| Enable handling of different data sources on the same application | Replacing the OData service of an app | |
| Extending the available data sources for an existing application | Adding an OData service and a new SAPUI5 model to an app | |
| Make use of the power of annotations to easily tailor the custom application | Adding local annotation files |
Applications modified using developer adaptation / adaptation projects are called App Variants.
The full scope of what can be achieved with adaptation projects and the relevant prerequisites are described HERE.
Example
Use Case
In our ‘Manage Products’ reference app, we want to be able to filter products by need for approval.
Implementation
We need to create an adaptation project for our app in SAP Business Application Studio and use the Visual Editor to create the changes to your original app. These changes are saved separately to ensure upgrade compatibility (i.e. the original app remains untouched). We need to
- Add an XML fragment to extend (= create a change for) the existing SmartFilterBar control.
- Add a custom controller extension to define the behavior of the fragment.
- Implement the relevant extension points to enhance the app state management to include our new filter to ensure that the filter state remains intact when navigating between pages, bookmarking, sharing a link or saving it as title.
- make the fields translatable (enhance i18n file)
For a detailed step-by-step guide on how to implement this use case, please refer to this blog by Vitor Eduardo Seifert Bazzo.
Additional options & some special considerations for SAP Fiori elements apps
- A full list of available standard controller extension methods for list report, analytical list page, object page and overview page can be found in our documentation. Kindly note that only those methods that are listed here are supported.
- You can add and configure a new sub-object page for an additional node in the backend via the adaptation project manifest configurations. Defining configurations is also possible for existing pages. For details, please refer to the relevant section in our documentation.
Note: Currently we support adaptation projects for SAP Fiori elements floorplans for OData V2, but since we are increasing the number of SAP Fiori apps using the SAP Fiori elements floorplans for OData V4, we intend to support adaptation projects also for OData V4 based app soon as well. Please note that this is the current state of planning and can be changed by SAP at any time without further notice.
How to find out if an SAP-delivered Fiori app is based on SAP Fiori elements?
The easiest way to find out if an app uses the SAP Fiori elements framework is to check in the SAP Fiori App Reference Library:
- Open your SAP Fiori app, go to your profile menu and select ‘About’ from the drop-down menu. A Popup opens that lists the Fiori ID of your app
- Go to the SAP Fiori Reference Library click on ‘All apps’ and search for your Fiori ID
How to find out about app-specific extensibility features of an SAP-delivered Fiori app?
Go to extensibility section in the SAP Fiori reference library, which you can find in the implementation information tab
Integrating App Variants into SAP Fiori Launchpad (FLP)
Now that you finalized your modified application (App Variant), it’s time to bring it to a system and make it available to other users. These are the required steps:
- Deploy the adaptation project
The modified application (App Variant) needs to be deployed to a system so other users can have access to it. This is done using the Template Wizard as described here. - Configure target mapping on the SAP Fiori Launchpad
Once the App Variant is deployed, you need to make it available to your users by bringing it to the SAP Fiori Launchpad. This is done by configuring a target mapping as described in Settings for SAPUI5 App Variants - (Optional) Create a tile on the SAP Fiori Launchpad home page
To make your App Variant easily reachable to Launchpad users, you can create a static app launcher tile. Follow the steps on this page on the section Special Case: App Variants
Adaptation projects give you the ability to extend SAP-delivered Fiori apps in an upgrade-safe way. How will you use it? We are very interested in your use cases and look forward to your comments and questions!
Special thanks to Vitor Eduardo Seifert Bazzo from the SAPUI5 flexibility team – don’t forget to check his blog for a detailed sample implementation.
For the SAP UX Engineering team, Stefanie Hager.
