Extending SAP-delivered SAP Fiori elements apps using adaptation projects to create SAP S/4HANA app variants
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.
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.
In our ‘Manage Products’ reference app, we want to be able to filter products by need for approval.
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.
Nice blog on Extending Fiori apps.
I actually wanted to know how do we get the adaptation template in VS Code.
When downloading SAP Extension we get the Fiori template but not the adaptation template.
Can you help.
SAPUI5 Flexibility offers the creation of adaptation projects, so that developers can efficiently adapt standard SAP apps with custom changes. This capability is available in SAP Business Application Studio, see this blog post and this documentation.
Unfortunately adaptation projects are currently not available in the VSCode environment. The SAPUI5 team is aware of this and is looking into the respective requirements and priorities. As of now we do not have a concrete timeline yet. Once available, we will publish the plans in the SAPUI5 Road Map.
UPDATE on April 8th, 2023: Adaptation projects for VSCode are planned, see the respective item of the SAPUI5 Road Map.
Hi Oliver Graeff,
I'd like to ask You some questions about BAS and Adaptations?
SAPUI5 Visual Editor supports the project.
You use an SAP Fiori elements-based application (LR, OVP, and ALP)
You use Freestyle application
Otherwise BAS rejects to do custom coding
I recently run into this issue in BAS dealing with an Adaptation project for Manage Sales Contracts app. So do we need to go with Extension project for such applications, were the standard application already incorporates extensions into the FE app ?
Thank You very much in advance.
Our documentation on the topic of support of controller extensions was updated and fixed in some sence, I hope it is more clearer now. Now it mentions clearly that your project has to be based on Fiori Elements or Freestyle application and its that controller extensions are supported for views that are asynchronous. Have in mind that if you get notified about that during generation of the Adaptation Project, and in some cases, there might be just a single view that is synchronous (i.e. does not support controller extension) but all other to be asynchronous, so, supporting it. When you use UI5 Visual Editor to edit your Adaptation Project, the option for "Add Controller Extension" from the context menu over the application will be hidden if it is not supported.
If the case is you want to extend in such way application that has such views, and you need to extend those views, your option is to use Extension Project.
Original app was adjusted using UI Adaptation, afterwards Adaptation project created and deployed. UI Adaptation changes from original app are not present in new app variant.
Is it possible to bring automaticaly UI Adaptation changes to new Adaptation project?
The "Adaptation at Runtime" is not copied in the adaptation project.
Adaptation projects use the underlying application coding (and every UI change done by a developer), but nothing from a higher layer (namely what a key user changed, or the end users personalized).
Currently there is no way to automatically copy these changes from the original application.
I recommend recreating these directly in the adaptation project. In this way, it is part of your base coding with all its benefits:
Thank you for valuable advice.
Adaptation project was deployed from Web IDE. Now Visual Editor in Edit mode with switched - off Safe mode cannot be opened anymore. Stops on Loading. If I create new Adaptation project with different name, copy-paste changes, all works fine. Does it sound like a bug or there are known restrictions?
As a work-around, is it good practice to create change-files manually, without a help of Visual Editor? If file is created manually changes are working fine in Web IDE. Can it potentially cause issues during deployment and transportation?
The problem for Visual Editor not loading might be something connected not only with changes but with connections to destinations or user roles/rights or other very different reasons. Unfortunately, the reason for that cannot be diagnosed in a straight forward manner and you will have to create a support ticket to our component CA-UI5-FL-ADP-WDE so our support colleagues can investigate the problem and resolve it for you. Creating changes manually is definitely not good practice and it can cause problems during the lifecycle of the project.