Skip to Content
Technical Articles
Author's profile photo Vishal VK

Adaptation Project: Get to know how to extend a Fiori Elements app

In this blog post, we will understand what are the different types of users of Fiori applications and what options are available to them to create their own extensions. We will also learn in detail on how to create an Adaptation project, and get to know how customers can create their own extensions to standard fiori apps without creating modifications.

Different Personas and their needs

There are different types of users for Fiori applications. Each type of user has their own requirements, and they can be broadly classified into the following categories.

Extensibility options in S/4HANA

S/4HANA provides different options for creating extensions based on the kind of user.

S/4HANA provides Runtime Extensibility option for Key Users (Business Experts).

Key Users of Fiori applications can extend an application and incorporate additional changes at runtime.

This can be achieved using the Adapt UI option in Fiori Launchpad.

S/4HANA also provides Design Time Extensibility option for Developers, which provides additional freestyle capabilities compared to the Adapt UI option.

Layering Concept

SAPUI5 flexibility uses Layering concept to store the UI changes.

The changes are stored in Layered Repository (LREP) in respective layers.

Understand more about Layering concept here.


Used by


Type of changes

USER Customer End users User Personalization settings
CUSTOMER Key users UI Changes to adapt apps for all users
End users Views that the end user saves as Public
CUSTOMER_BASE Developers UI changes made with SAPUI5 Visual Editor
VENDOR SAP SAP Example: Update of an app

Design Time Adaptation (DTA) for extending Fiori Elements Application

How can customers extend a Fiori Elements application and add custom logic to it which is modification-free?

As of S/4HANA 1809, this can be achieved with…… Adaptation Project!!

When an Adaptation Project is created, a new variant of the existing application is created. The app variant has a reference to the original application but contains only changes created in the adaptation project. Hence, any new changes made in the original application are automatically available in the adaptation project as well. The changes made in the variant are applied on top of the original application.

Some key features of Adaptation Project are:

  • Semantic changes can be done to applications (Ex. Hide a field based on certain condition)
  • Control properties and bindings can be changed (Ex. Enable or disable Excel Export for Smart Table)
  • Custom XML fragments can be added to extend views (Ex. Open a custom dialog on click of a button)
  • Custom business logic (JavaScript) can be added (Ex. Call an odata service on click of a button)
  • Extend I18n texts (Ex. Translation for labels of custom buttons)
  • Move controls/sections (Ex. Place a custom field in between 2 standard fields in object page)

How is Adaptation project different from Break-outs (template extensions)?

  • In a Fiori Elements application, break-outs are created for adding custom UI (XML) and business logic (JavaScript) to the smart template.
  • Break-outs are a part of the actual application. Hence, if an application development team creates a Fiori elements app, and a customer wants to add custom logic via break-outs, then that would be a modification.
  • Break-outs are extensions to the smart template and are a part of the original application, whereas adaptation project is an “extension” of the application!

Creating an Adaptation Project

An Adaptation project can be created in WebIDE, by selecting a source application which needs to be extended.

Provide the requested details and follow the configuration in the wizard.

Open the project using SAPUI5 Visual Editor.

We can Preview and Edit the application. When in Safe mode, only semantic changes (changes possible during the application runtime) can be made.

Safe mode provides less freestyle capabilities but allows you to stay fully compatible with a future upgrade of the source application.

Click on Safe mode button and then disable the safe mode. Once Safe mode is disabled, it cannot be enabled again.

If you use the SAPUI5 Visual Editor without Safe mode, you are responsible for any changes that you make to the project.

Once the app is deployed to the system, changes made using the Visual Editor are saved in the Layered Repository (LREP).

Use case: Add a custom button to open an email

In the Visual Editor, disable the Safe Mode and go to Advanced Mode.

Click on Edit button to make the changes.

  • The Outline tab shows the hierarchy of the controls in the screen.
  • The Changes tab shows the currently applied changes.
  • The right side pane shows the properties that can be changed for the selected control.

Select the control where the button is to be added.

The custom button needs to be added in the table toolbar of the list report. So the table toolbar should be selected.

Click on Add fragment.

Select the Target aggregation and position where the new fragment needs to be added.

Click on Create new to create a new fragment.

Provide a fragment name and click on Create.

The new fragment is created.

Add the XML logic to add a button. Use Stable IDs in the XML code.

changes folder gets created in the project. The fragment is saved in fragments folder.

A change file is created to apply the XML fragment on top of the source application.

The layer property in the change file indicates the layer at which the change was made.

Save the changes made and click on Preview. The newly added button would be visible.

Now let us extend the controller to handle the click of the button.

Click on Edit button. Click on the newly created button and select Extend with Controller.

Provide a controller name and click on Extend.

coding folder is created, under which the extension controller file is saved.

A change file is created to apply the extension controller logic on top of the source application.

In the controller extension file, add a function and write the logic to open an email.

Add the press event to the button in the XML fragment.

Ensure that the event handler is provided correctly. It has to begin with .extension.

Save the changes.

Run the Adaptation_index.html to execute the application in WebIDE.

Click on Send email button.

An email opens in outlook!!

Deploying the application

Now let us deploy the application to the ABAP repository.

Right click on the project > Deploy > Deploy to SAP NW Application Server ABAP

Follow the steps prompted.

Provide the Package and TR details if you are using one.

In this case, let us go ahead with a local object.

Click on Finish to deploy.

Once the deployment is successful, success message is displayed!

The application would be saved in the Layered repository. It can be opened using transaction SUI_SUPPORT.

Provide the application variant ID and click on execute.

The list of files would be displayed from the Layered Repository.

Fiori Launchpad Tile configuration

A new tile can be configured using the Fiori Launchpad Designer (Transaction Code /UI2/FLPD_CUST or /UI2/FLPD_CONF).

Open the catalog where the tile is to be added.

Add the details for the tile and target mapping.

Provide the ID from the manifest app descriptor in the project.

  • The recommended way is to use the same Semantic Object as the source application, but a different Action. This ensures that whenever there is a navigation implemented using CDS annotations, then both (the source application and the variant) appear in a popup.
  • Another way is to use the same semantic object and action as that of the source application, along with the sap-appvar-id parameter.

Add the tile to the required group.

The tile will appear in the Fiori Launchpad.

With this, the adaptation project has been deployed to the system and it can be accessed from the Fiori Launchpad.


Currently, few of the limitations of Adaptation Project are listed below:

  • Supports Fiori Elements applications. Not all Free style apps are supported.
  • Supports only smart controls.
  • Not all properties of a control can be changed.
  • App to App navigation is not supported in WebIDE.
  • Other Reuse components cannot be embedded in an Adaptation project.
  • Not all properties of a table Column can be changed.
  • It is not possible to change the OData service that is used in the source application.

(Some of these limitations might be addressed in future).


With a vast range of freestyle capabilities, Adaptation project is a go to option for customers to implement their own custom extensions to standard Fiori applications.

Further Reads

The following links would help you to understand more about Adaptation project.


Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Gaurav Karkara
      Gaurav Karkara

      Thanks Vishal for this blog.

      Many of the image/snapshots don't appear in blog. They are being shown as sort of broken links. Do you see all the images perfectly fine?


      Author's profile photo Vishal VK
      Vishal VK
      Blog Post Author

      Hi Gaurav,

      I have updated the images again. It should be fine now.


      Thanks & Regards,

      Vishal V K

      Author's profile photo Amrutha S
      Amrutha S

      Very nice and helpful blog Vishal!

      Author's profile photo Rathakrishnan Porchezhian
      Rathakrishnan Porchezhian

      Nice blog.. Thanks for sharing it.

      Author's profile photo Jasjeet Singh Sachdeva
      Jasjeet Singh Sachdeva

      Very informative!! Thanks for sharing it Vishal!!

      Author's profile photo Syambabu Allu
      Syambabu Allu

      Hi Vishal,

      Excellent Blog with detailed information.

      Thank you,


      Author's profile photo Chaitra A
      Chaitra A

      Hi Vishal,

      Thanks for the blog.

      Can freestyle Fiori apps too be extended using In-app Extensions?

      Thank you,



      Author's profile photo Vishal VK
      Vishal VK
      Blog Post Author

      Hi Chaitra,

      Please refer below help documentation.

      Hope this helps.

      Thanks & Regards,

      Vishal V K

      Author's profile photo Sambhav Tripathi
      Sambhav Tripathi

      Hi Vishal,

      Thank you for sharing such a useful information.

      We have a requirement for Hiding cards in OVP application for users.


      Using adaptation method for extending OVP apps we need to add “requireAppAuthorization” property for each card so that visibility can be controlled as mentioned here

      Can you please, guide if this is possible using adaptation method ?
      or is there any different method for extending manifest app for OVP apps ?

      Sambhav Tripathi

      Author's profile photo Aman Khanna
      Aman Khanna

      Many thanks for your support and this blog, Vishal!

      Author's profile photo Aruna Mada
      Aruna Mada

      Hi Vishal,

      Your blog is very informative.

      I tried extending the same fiori app, but getting the below error. Can you please help me

      Can you please help/guide me .

      Thanks & Regards


      Author's profile photo Haythem SAHLI
      Haythem SAHLI

      I am facing the same issue, any news ?

      Author's profile photo Vishal VK
      Vishal VK
      Blog Post Author

      Hi Haythem,

      Could you please check if the metadata of the odata service is loaded correctly?

      Thanks & Regards,

      Vishal V K

      Author's profile photo Lukas Huber
      Lukas Huber

      Hello Vishal VK,

      I have the same issue.

      How do you mean to check if metadata is loaded correctly? Is it a problem when the app is not configured on the system so far?

      Thanks a lot!

      Author's profile photo Vishal VK
      Vishal VK
      Blog Post Author

      Hi Lukas,

      Please ensure that the base application is working.

      Author's profile photo Deepesh Saxena
      Deepesh Saxena

      Check this note: If UI5 editor doesn’t load,

      This is a known issue, Change the SAP UI5 Version in Project --> Project Settings --> SAPUI5

      Author's profile photo Deepesh Saxena
      Deepesh Saxena

      Check this note: If UI5 editor doesn’t load,

      This is a known issue, Change the SAP UI5 Version in Project --> Project Settings --> SAPUI5

      Author's profile photo Haythem SAHLI
      Haythem SAHLI

      i am facing the same issue, any news ?

      Author's profile photo Lukas Huber
      Lukas Huber

      Haythem SAHLI

      sorry for disturbing? Did you already found a solution for the problem - I have the same!

      Thanks a lot!

      Author's profile photo Ramesh Yuvashree
      Ramesh Yuvashree

      Hi! Thanks a lot for such an informative blog. Quick question, once deployed can it be imported (into WebIDE)  from ABAP repository to make changes on top of any existing adaptation project?

      Author's profile photo Vishal VK
      Vishal VK
      Blog Post Author


      Are we not using tools such as Git repositories to store the application code?

      Author's profile photo Ramesh Yuvashree
      Ramesh Yuvashree

      Oh alright. Yes, Git repository can be used. And, just for confirmation. All future standard app upgrades will still be available, right? Since this adaptation project is a variant of standard app, like a custom layer on top, so I assume that future standard app upgrades will be as it is.

      Author's profile photo Vishal VK
      Vishal VK
      Blog Post Author


      Yes, future standard upgrades would be available in the adaptation project.

      Author's profile photo Andre Filatov
      Andre Filatov

      Here is how I solved it:

      1. Do not run SAP WebIDE in incognito mode in Chrome!
      2. In Chrome go to Settings, cache. In the popup window titled "Clear browsing data" select "Advanced" tab. In "Advanced" tab select all items and click "Clear data" button.
      3. Close all and re-open  a Chrome browser session.
      4. Launch SAP WebIDE. Re-create your adaptation project from a standard Fiori App you want to adapt.
      5. Right click on your project and go to  Project Settings --> SAPUI5. Set your project SAPUI5 version to 1.78.18 .
      6. Next, here in "Project Settings" go to "Project Types" and make sure to uncheck "Smart Project".
      7. Save the Project Settings and exit back to your project in SAP WebIDE. Right-click on the project and select "Refresh Workspace Items".

      Now you should be able to launch SAPUI5 Visual Editor.

      Author's profile photo rakesh baggam
      rakesh baggam

      Hi Vishal,

      Thanks for the blog it really helped me in my development.

      I am facing some dilemma here. can you help me out?

      There is standard fiori app. I have extended that using adaptation extension. Now I am facing a problem. That standard app is actually calling from several other standard apps. so how can I enable those apps to call my  extended app instead of standard app.

      I have to use the same "semanticobject - action" with app-var-id   for the extended app as standard app.

      Now do i have to  remove the standard app from my launchpad? so that my extend app can be called from other standard apps?  Or is there any standard way?

      because if i am keeping both intents in launchpad designer (in catalog) its always navigating me to standard app.

      Author's profile photo Jeelani Kattubadi Basha
      Jeelani Kattubadi Basha

      iam not able to apply the style in custom fragment.

      created CSS file under WEBAPP folder and defined css file in manifest.json but style is not applying , please guide me.

      Author's profile photo Roshan Pillai
      Roshan Pillai

      Hi ,

      How can we disabled the Navigation option from adaptation project.

      As it should not navigate to Object page

      Author's profile photo Vijay K
      Vijay K


      I have extended a standard App using Adaptation method.  This standard App is called from another standard OVP app.  How to assign the intent / fiori launchpad settings for this variant, so my new variant will be called from OVP instead of the standard app.




      Author's profile photo Ajay Gupta
      Ajay Gupta

      Hello Vishal,

      Thanks for a very good documentation. Jocelyn Dart would be very helpful if we could also add this to the Wiki page.

      One update from SAP_UI 7.55 onwards, it is also now  possible to delete the adaptation project by running the below report in the onPremise system.