Adaptation Projects – it’s time for a new way to extend your Fiori Elements applications
Do you have Fiori Elements applications you use but you really wish you could extend in some way? For instance, perhaps you have an application that uses the List Report Fiori Element and you’d like to add a couple of filters to the Smart Filter bar? As of Web IDE version 1809, you can do that!
In Web IDE, you can create a new Adaptation Project, indicate what application you’d like to base it upon, and then easily create a new variant, using the new SAPUI5 Visual Editor.
When you create an Adaptation Project, you are creating a new variant of an existing application. The app variant refers to the original application but contains separate set of changes created in the adaptation project. Also, an application ID is defined for the variant and needs separate registration in Fiori Launchpad.
In our aforementioned use case of adding some filters to the Smart Filter of a Fiori Elements List, you would do the following steps:
- Create a new adaptation project
- Name the new project’s name and choose the application upon which you want to base the variant. A new project is created and listed in your Web IDE workspace.
- Right click on the project and select, SAPUI5 Visual Editor to make changes to the project.
- This brings up your project in the SAPUI5 Visual Editor. This editor was formerly known as the UI Adaptation Editor, but the name has changed as its abilities have grown. In the past, you could preview the application, make changes to the properties of controls in a Fiori Elements application, see an outline view of the controls and see a list of changes that had been made. That functionality still exists, but now you can also add code fragments and extend with a controller.
Again, changes made via the SAPUI5 Visual Editor are saved to a Changes folder and saved in the layered repository to be applied when the application is run.
From the editor you can preview your changes and ensure everything works. Once you’re satisfied with your changes, you can easily deploy your application and, because it has a different Application ID than the original application, both the original application and the new variant’s tiles will be available.
Technical notes for this initial release:
- Source applications must be located on an ABAP repository.
- You can create variants of Fiori Elements based applications. In a future release we will add support of SAPUI5, “freestyle,” applications as well.
MMmmm... Now I'm wondering if I can do this on-premise. I think I can. I just haven't had time to play with our FiORI yet. For new development - right now - we do it in ABAP and then link a transaction to the new tile. I'm trying to find as much as I can - so I can start being more sophisticated.
One step at a time.
Hi Michelle! Yes, if you're on-premise and have Fiori Elements applications in your ABAP repository, you can definitely use Adaptation Projects. I'd love to hear how it goes! Best, Jessica
I'll let you know. I just watched a Teched session about Fiori Elements. Between watching that and reading this - perhaps I can get something accomplished.
Hi Jessica, very informative blog. I was having a questions. what is the difference between Adaptation and Extension projects in the Web IDE and will upgrade for any standard application will work for both projects ? TIA.
Thanks! So some key features of Adaptation Projects are:
With adaptation projects, you do not need extension points, which is a difference from extension projects as well.
Application variants created with adaptation projects will continue to work when the original application is updated, as the changes made in the variant are simply applied atop the original application.
Currently, in this initial release of adaptation projects, the original application must use Object Page and/or List Page Fiori elements. In future releases we will support applications made with the Overview Page as well as “free style” applications.
Thank you so much Jessica for the information.
I assume we are below the required software components. Can you please help and drive me in the right direction to validate the system requirements on non-HANA stack ?
I adapted the layout and the controller of a Fiori Elements application created by myself within the same project. I deployed to the ABAP Front-End Server / GW. The controller extension is working, but the layout adjustments not unfortunately. In SAP WebIDE everything was working fine. We have SAP Front-end server 3.0 installed with NW 7.51 Innivation package and SAP_UI 7.51 sp6 components. UI5 version is 1.44.
I spoke with one of our architects and the problem is likely that you need to upgrade to a newer version of SAPUI5 -- version 1.56 at least.
Best of luck,
Many thanks Jessica!
very Nice and informative blog.
As for my knowledge We can also create app variant with fiori launchpad also from 1809 on premise.
I tried so but after creating a app variant one pop up message displays with ''Please contact your administrator to add the tile to Fiori launchpad home page(appid:"************").
I am not able to find that app id and didn't know how to create a tile with that app id.
attaching the the screenshot for ref.
if you created an extension project and deployed to ABAP repository, then the app ID displayed in the dialog needs to be added in the FLP Designer into the target mapping configuration the Tile refers (plus referring the SICF end-point of the application deployed. ) I assume.
So launch FLP Designer, select the appropriate catalog and define target mapping, where you find the ID:
Thenyou create a tile referring the target mapping.
If this is a kind of other in app extensibility feature(I am not aware of due we are not on HANA or S/4HANA), then it might you need to refer the target mapping of the standard application in your tile, and add a kind of ID parameter in the tile configuration. We are not on the minimum system requirement level, so I cannot test this for you. But looking in that direction would be a good idea.
In what way did you create the variant? Was this from within the application (ie launching the application from Fiori Lauchpad and then selecting Adapt UI from the Me area) or from Web IDE?
I created the variant through fiori launchpad by selecting Adapt UI.
Okay, if you did it via the Key User adaptation (also known as Adaptation at Runtime), then the variant was created and got an automatically generated application ID. You'll need to contact the administrator of your FLP to get them to add that new variant to the catalog (so that people can see it as an app to add to their FLP).
I have tried to extend the section of the Fiori Element application (Manage Purchase Contract Version.2) but the changes are not reflecting.
I'm not sure if there is any issue with the application or may be I'm missing something.
Can you please share any useful link/document/information to extend the section of the application using Adaptation project?
Hmm! A few questions for you:
When I first was learning how to use adaptation projects, I would run in to situations where the controller extensions I added didn't appear to work and the reason was that I had put the wrong project name in the code. I.e. the project name in the code did not match the actual project name of the adaptation project in which I was working.
Please find my response below:
I faced a similar issue when I tried to add a new section via fragment. The reason why it was not working for me was incorrect control aggregations in the fragment.xml. After I fixed the aggregations it started working for me.
Please refer the following screenshots for fragment.xml code snippet and the added section.
Hope this helps.
Thanks Bhuban. It's working now.
Are you still having the problem? I sent you a direct message with some suggestions.
Thanks Jessica. Problem resolved.
This is a really informative blog. I was able to follow through all the instructions that has been provided here for adaptation project but I am now stuck as to how to deploy the adaptation variant. The deploy option in WEBIDE gives me two ways to deploy i.e.
'Deploy to SAP NW Application Server' - Could not figure out how to proceed here as it only gave me an information dialog having link to navigate to 'Development Process' which did not seem to have any information on deployment of adaptation project.
'Register to SAP Fiori Launchpad' - Here, I got the error stating 'This is not an SAP Fiori-like application. The Component.js file was not found.'
It would be great if you could guide us on this deployment process for the adaptation variants from WEBIDE.
Thanks with Regards,
Please find below information if this is useful for you:
1. In your workspace, from the adaptation project context menu, select Deploy Deploy to SAP NW
Application Server ABAP .
2. Confirm the System and Namespace selection by choosing Next.
If you have already deployed the adaptation project in the past, steps 3 and 4 are skipped automatically.
The deployment uses the same package/transport that you selected for the earlier deployment.
3. Select a package.
a. For an existing package, choose Browse, search for an existing package and choose OK. Then, choose
Next and continue with step 4.
b. For a local object, choose $TMP. Then, choose Next and continue with step 5.
4. If you have selected an existing package from the list, select or create a transport and choose Next.
5. Choose Finish.
The UI changes you made in the adaptation project are applied to the layered repository in the selected
SAP NetWeaver Application Server ABAP for your application.
Thanks a lot for your prompt reply. I believe, the following screenshot highlights the deploy option mentioned in step 1 ( 'Deploy to SAP NW Application Server ABAP' )
But, selecting this option results in an information dialog as shown below.
Since I am not getting any option to confirm system and namespace as suggested in step 2, I am unable to proceed further.
Is there an explanation as to why I am getting this information dialog instead and how to proceed from here?
please follow the SAP internal Fiori build infrastructure processes as described in the dialog otherwise you will create inconsistent content.
very interessing blog. Thanks a lot.
I've created an adaptation variant in WEBIDE and deployed to SAP NW Aplication Server. It was successfully - I got information that my change files were uploaded.
How can I now configure a tile using this app variant? Where could I see the app variant id?
Sebastian Wennemers Can you please take a look at this? Thanks!
I have a requirment to extend Overview app with additional filter.Tried following your blogs but i am unable to procedd.I am not getting control aggregation in Target Aggregation selection.Should i change anything at annotation file.Please help
as said before thank your for your really informative blog.
Right now I`m facing exact the same situation as Anastasiia.
I'm wondering how the changes are applied to the adapted app on the launchpad. In this blog it sais, as for my understanding, that the changes are applied automatically after deployment.
Unforunately nothing happened to the app on the launchpad nor does the "Adapt UI" editor offer me a new "App Variant" while using the "Adapt ui at runtime" functionality.
An answer to this question would be highly appreciated, as I am a little in a hurry because I have to finish the deployment until tomorrow. 🙂
I've tried with another App and figured out hopefully how it's working.
After deployment you have to configure a tile with your variant.
In manifest.appdescr_variant file you get an App ID.
This App Id (Variant ID) must be set as ID in a new tile configuration. So a new version of App with your variant is created.
The experimental way show that variants created like a DTA aren't displayed in the Overview of App Variants, only variants created in the runtime adaptation.
this worked like a charm, thank you.
Could you please provide details on how you have configured a tile using app variant.I found the app variant id as well i would like to know what are the next steps.
I have a trial version of Web IDE on premise. And, I can't seem to find / use SAP Visual Editor or create an Adaptation Project for Fiori Elements. Do those features only exist on the Full Stack Cloud version of Web IDE?
If so, how long will it be before the on premise version can have those features?
sorry for the ate reply. PLease see https://blogs.sap.com/2019/01/14/adaptation-projects-a-tutorial/comment-page-1/#comment-466158
This is regarding safe mode and advanced mode option available in WebIDE Adaptation Project. In the help.sap document, It is mentioned that "Safe mode allows an app variant to stay fully compatible with future upgrades of the source application".
For one of the standard app (F1982), we have custom requirements like showing a table referring custom table, perform some calculation in UI dynamically etc. These requirements are not possible in safe mode.
Does this mean, if I go with advanced option, the new features added as part of new releases will not be there?
Since adaption project is layer on top of standard with out affecting the standard source code, just want to know about the implications in using advanced option.
Thanks in advance.
Informative blog! I have a requirement and i am not sure if this can be achieved using the adaptation project method as described above. We want to add a column to the app Stock-Multiple Material which is a analytical (fiori elements) app.
I know we can add fields to it and all, but is it possible to add a column using above method or we have to go for extension project for fiori elements in web-ide ?
I have tried to follow the Adaption project and tried to hide a card in overview page and wanted to deploy it back to abap repository getting below error.
Could some one suggest how to go ahead with this issue.Below is the error are there any authorizations missing.
Request your immediate support
There is a requirement in my project which consists of a standard SAP FIORI Element Overview Page.The requirements are to extend the standard app by adding new stack card, bar chart list card and custom functionalities associated with the cards.
I am using the Adaptation project for the extension. When I am trying to add a New Stack Card or edit an existing Card using the SAP Visual Editor, in preview it is showing the new card added at that moment but after saving and when trying to run the application through Web IDE the changes/cards are not reflecting in the application though I can see the changes are added inside the ‘changes’ folder in the WEB IDE project .
Can you please guide me how to resolve the issue.
very informative blog. Thank you very much!
in adaptation project folder does not exist mockserver.js metadata.xml.
do you know, how can I create OPA5 test for one adaptation project?
may I use MockServer for adaptation project?
have you maybe one example?
thanks and best regards,
We are facing an issue with the i18N texts:
We added a new section using below fragment to the purchase contract item page:
As you can see the smartform group labels should be retrieved from the i18n file.
Texts are added to the i18n of the contract item object page:
When running the application the texts are not found:
Do you or somebody else have a solution for this? It seems the i18n file of the C_ContractMaintainItem is not bound to the view fragment?
Thanks in advance!
I have to add new facet on Object page , I have created adaption project but not able to see object page controls only List Report controls are visible . When I go to Visual Editor Preview page and click on GO button it does not go to Object Page.Could you please help on this .Below are screen shots.Fiori Element App Name is PS_WBS_OVWS1.
the idea is that you use the preview mode to navigate to the object page, and then toggle to edit mode to do your changes.
So when click on 'Go' in Preview mode, you should see the list of WBS elements getting populated. Then select one of them, navigate to its object page and then edit that page.
Hope this helps.
Hi Oliver ,
Thanks for reply . When I click on “Go” Button in preview mode , WBS elements are not getting populated . Table is empty , I did F12 and checked network tab , cant see any odata service call .
Could you please help on this .
very interesting blog and many interesting informations in the q&a.
Based on this all and addtional documentation i created an adaption project for the salesorder.factsheet. I created a new section and i even created a Controller-Extension to react on lifecyle-events (in my case onInit).
But the question i have (and where i did not find an answer so far) is, how to access the data-model of the app. So to use data-binding in my xml-fragment and/or to have access to the models/data in my extension-controller.
Any help would be great,
Hello Jessica, Great Blog. And very opt to my current requirement.
But in the first step I’m stuck with the below error.
“The Selected Application Doesnot have a Manifest.json file.”
But when I checked the Original app in WebIDE, masmifest.json exit. App is Cash Flow Analyzer.
Does it mean one cannot adopt this Project?
Thanks in Advance.
could you solve this issue, I am facing the same issue.
How do you fix this issue?
Same with fin.ap.paymentproposal.schedule
So overall, what are the main differences between an adaptation project and an extension project and which one should we use when extending an standard app ?
Even I have the same exact question.
What is the main difference between an adaptation project and an extension project ?
Both the approaches are modification-free.
We are not touching the std fiori code.
Both will get the latest updates anyhow.
What special adaptation project is providing ?
Did you get any answer on this Question?
Hi Javier, Vaibhav, Mark,
Extension project and adaptation project pursuing different approaches: While with the extension project you create your own “slim” app that needs to be loaded with the original app, the adaptation project creates a semantic app variants with a separate app descriptors and a change file per adaptation which are merged during runtime with the original app.
A major benefit of the adaptation project is that you are not restricted to one extended/adapted standard app but you can create as many app variants as you need and that your are not restricted to extension points to be able to make your changes.
I’d rather use the adaptation project than the extension project, also because there are no further improvements planned with the extensibility concept while adaptation project evolves.
For standard fiori elements based applications only adaptation option available?
With standard Fiori element based applications you have more or less the same options than with standard Fiori freestyle applications. You can adapt the UI but you can also do controller extensions and add custom logic to your app.
See also this more recent blog post from my colleague Hristo Tsolev.
Hi @Jessica Merz,
I have followed your blog. It looks awesome.
I was trying to use this adaption project for Manage decision app, we are already on 1909. https://fioriappslibrary.hana.ondemand.com/sap/fix/externalViewer/#/detail/Apps('F2345')/S15OP
But, I while creating adaption project, I am facing below error: Our UI version 1.71+
select a different application. application project does not support the selected application.
Can you suggest any possible issue?
i have created Adaptation project adding facet.
Sometimes i am getting "Merged descriptor could not be fetched from backend, falling back to non-merged execution"
error, resulting its not able to load the extended change.
I see this message is getting populated from adaptation_index.js file. This is very unsual.
When i open visual editor in the preview mode , i see my new added facet but when i run in the browser, i see this error and extended facet is not visible .
Could you please help here.
Getting above error in adaptation project from application md_bps1.
It is not a known issue. Can you please submit support ticket to CA-UI5-FL-ADP-WDE , your issue will be handled right away.
Issue is resolved now. I changes sapui5 version to 1.78.
SAP Folks, you need to update 2964080 - SAPUI5 Visual Editor cannot load app in adaptation project.
Here is how I solved it:
Now you should be able to launch SAPUI5 Visual Editor.
The whole blog and comments chain was very informative.
I have a requirement where I need to conditionally hide fields in one of my application. Application title is Manage Purchase Requisition Professional. This is a standard fiori elements application in which we need to do some semantic changes. I created a new adaptation project for the same. Now in object page based on document type we need to hide few fields.
Any suggestion for this.
SAP Folks, Any help would be appreciated over here.
While using the Visual Editor of the Adaptation Project, did you try selecting the fields you want to hide and change their Visibility property to false ?
Please share how it went for you,
What you suggested I am able to do. But my ask is different. I need to hide a field based on the value of document type. I am not able to achieve conditional hide.
Then you have to use the business logic adding ability of Adaptation Project - i.e. adding your own custom controller code which will (lets say OnLoad or whenever you need it) hide/show fields based on your conditions. You can check the documentation for it here :
Hi Jessica Merz,
Thanks for such a Great explanation.
I am having a requirement.
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.
Do I have to use the same "semanticobject - action" for the extended app as standard app and remove the standard app from my launchpad? Or is there any better option?
You need to create new semantic object which refere to your adpated project.
And reuqired a metadata extension for every Apps' CDS Where the orginal semantic object and action is used, and to extend it with new semantic and action that refere to your adapted app.
If you have better way kindly share with us.
How to retrieve adapted project (apps) ?
What do you mean by 'retrieve adapted project (apps)' , can you be more specific please? Thanks.
Thanks for your replay.
We have the following case; currently let's say I'm creating new adapted project for a standared fiori app.
Then after some time X devloper want to do more enhancment in the same app.
1- How X can get to know that this fiori app already has existing adaptation project ?
2- How can he import this adapted project to work on new requirements?
*We are using WebIDE.
This very much clarify my doubts.
I hope that SAP make it possible to retrieve adapted project directly without the need to use git.
Thanks very much.
How to disabled the navigation from list page to Object page.
It should not navigate to object page.
This should be option for the grid, please check in UI5 documentation which property is regarding the navigation and try to disable it in EDIT mode of the Visual Editor of Adaptation Project.