Skip to Content
Technical Articles
Author's profile photo Jessica Merz

Adaptation Projects: A Tutorial

In prior blogs, I gave a high level overview of Adaptation Projects and presented a video demo.  If your interest is piqued, follow along with today’s blog to create your own application variant using Adaptation Projects.

Pre-requisites:

When creating an Adaptation Project, you must have access to an ABAP on premise system that contains some applications made with SAP Fiori elements. For this tutorial, you will need a SAP Cloud Platform Cockpit account, access to SAP Web IDE and access an SAP demo system, ES5.

  1. Don’t have access to Web IDE and SAP Cloud Platform Cockpit? Follow the instructions here to get an account.
  2. Next, sign up for a demo account on ES5 here.
  3. Next, in SAP Cloud Platform Cockpit you have to create a destination using the following data:
#
#Tue Dec 05 14:36:33 UTC 2017
Description=SAP Gateway Demo System
Type=HTTP
TrustAll=true
Authentication=NoAuthentication
WebIDEUsage=odata_abap, bsp_execute_abap, odata_gen, dev_abap
Name=ES5
WebIDEEnabled=true
CloudConnectorVersion=2
URL=https\://sapes5.sapdevcenter.com
ProxyType=Internet
sap-client=002
WebIDESystem=ES5

You can simply create a text file that contains the above mentioned data and import the destination as follows:

  1. Log in to the SAP Cloud Platform Cockpit.
  2. Select your account.
  3. Click Connectivity.
  4. Click Destinations.
  5. Click Import Destination.
  6. Select your destination configuration file and click Open.
  7. Select Save.

Exercise

Now that you’re configured, let’s create an Adaptation Project.

Scenario: you are one of Santa’s elves and you had a heck of a time finding the right sized boxes as you were wrapping gifts last Christmas.  You’d like to search for products that fit in Small, Medium and Large sized boxes to help organize your packaging when the crush happens next time around.

To do this, you are going to extend the Manage Products application that resides on ES5. This application allows users to search for products and look at the details of those products. This application was created using the SAP Fiori elements List Report and Object Page.

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 a separate set of changes created in the adaptation project. Also, if the original application is changed, the variant will incorporate those changes.  A new application ID is defined for the variant and the variant will need to be registered in SAP Fiori launchpad in order for users to access it.

  1. Open SAP Web IDE.
  2. Create a new adaptation project: File -> New -> Adaptation Project
  3. Now you need to enter a project name and application title.
    Project Name: adapt.listreport.products
    Application Title: Adapted Manage Products
    Namespace: <accept the default value>
  4. Select Next.
  5. Now we need to select a system and source application upon which to base this variant.Select SAP Gateway Demo System (that’s ES5). You may need to enter your user name and password for that system.Select the application with the Description Manage Products and select Finish.
  6. A new project is created and shows you a working application based on the source application. Any changes we make in this variant are not going to change the code of the source application.Next, let’s open up this project in the SAPUI5 Visual Editor, where we can preview what the application looks like.Right click on the project and Select SAPUI5 Visual Editor*Note: You might be prompted for a user name and password. If so, enter your user name and password for the ES5 system, which you created in the 1st pre-requisite step.
  7. You see that you can do a search for products based on a number of filters. Do a search where you filter on price range to see how it works.
  8. Let’s add another filter – one that searches on shipping box sizes.Before we start editing, let’s disable Safe Mode.When in Safe Mode, the developer can only make changes that Key Users can make in Adaptation at Runtime, and those are changes that will always work when the source application is updated.  In Safe Mode you can move sections, rename labels, etc.  However, we want to make more changes than that…Select Safe Mode
  9. De-select the Enable Safe Mode checkbox to disable it and select Apply.
  10. Go to Edit mode.
  11. In order to add a new filter, you need to add a new fragment.Right click in the filter area and select + Add Fragment menu item.
  12. Here we are going to create a new Control Configuration named boxFilter.
    From the Target Aggregation dropdown, select controlConfiguration.Select the Create new In the Add Fragment dialog box, enter a Fragment Name of BoxFilter and select Create.
  13. Now we have a new Boxfilter XML file that’s blank and we need to add some code. Copy the following code and paste it in to the boxFilter.fragment.xml in your SAP Web IDE. Then Save.
    <!-- Use stable and unique id's!-->
    <core:FragmentDefinition xmlns:core='sap.ui.core' xmlns='sap.ui.comp.smartfilterbar' xmlns:m='sap.m'>
    	<ControlConfiguration
    	id="boxFilter"
    	key="boxFilter"
    	index="20"
    	label="{i18n>BOX_FILTER}"
    	groupId="_BASIC"
    	visibleInAdvancedArea="true"
    	filterType="multiple"
    	>
    		<customControl>
    			<m:ComboBox id="boxTypes">
    				<core:Item id="smallBox" key="small" text="{i18n>SMALL_BOX}" />
    				<core:Item id="mediumBox" key="medium" text="{i18n>MEDIUM_BOX}" />
    				<core:Item id="largeBox" key="large" text="{i18n>LARGE_BOX}" />
    			</m:ComboBox>
    		</customControl>
    	</ControlConfiguration>
    </core:FragmentDefinition>

     

  14. Go back to the Visual Editor tab and accept the message that says changes were made outside the editor and let it reload the editor.  You may be asked if you want to save unsaved changes in the editor – if so, select Save.
  15. To get your new filter configured for localization, you can add keys to the i18n.properties file.   In the tree view of Web IDE, double-click on the i18n.properties for the ListReport of this project to open it in the editor.
  16. Copy the following code and replace the contents of i18n.properties and then select the Save button:
    #Make sure you provide a unique prefix to the newly added keys in this file, to avoid overriding of SAP Fiori application keys.
    
    BOX_FILTER=Box Size
    SMALL_BOX=Small
    MEDIUM_BOX=Medium
    LARGE_BOX=Large

     

  17. Go back to the Visual Editor tab and accept the message that says changes were made outside the editor and let it reload the editor.  You’ll see the new filter, but there is still no code there to control how it works.
  18. Select Edit, right click in the SmartFilter area and select Extend with Controller.
  19. Enter a name of ListReportControllerExtension and select Extend.
  20. Now you are looking at a new file, ListReportControllerExtension.js. Notice this is not an empty file, inside the comments you find documentation about which methods you can extend. There is a lot of documentation on controller extensions in the SAPUI5 documentation.For now, replace the contents with the following code and select the Save button:
    /***
    @controller Name:sap.suite.ui.generic.template.ListReport.view.ListReport,
    *@viewId:nw.epm.refapps.st.prod.manage::sap.suite.ui.generic.template.ListReport.view.ListReport::SEPMRA_C_PD_Product
    */
    sap.ui.define([
    		"sap/ui/core/mvc/ControllerExtension",
    		"sap/ui/model/Filter",
    		"sap/ui/model/FilterOperator"
    	],
    	function (
    		ControllerExtension,
    		Filter,
    		FilterOperator
    	) {
    		"use strict";
    
    		//hard coded list of shipping box sizes:
    		var BOX_SIZES = {
    			small: new Filter({
    				filters: [
    					new Filter({
    						path: "Height",
    						operator: FilterOperator.BT,
    						value1: 0,
    						value2: 10
    					}),
    					new Filter({
    						path: "Width",
    						operator: FilterOperator.BT,
    						value1: 0,
    						value2: 10
    					}),
    					new Filter({
    						path: "Depth",
    						operator: FilterOperator.BT,
    						value1: 0,
    						value2: 10
    					})
    				],
    				and: true
    			}),
    			medium: new Filter({
    				filters: [
    					new Filter({
    						path: "Height",
    						operator: FilterOperator.BT,
    						value1: 10,
    						value2: 20
    					}),
    					new Filter({
    						path: "Width",
    						operator: FilterOperator.BT,
    						value1: 10,
    						value2: 20
    					}),
    					new Filter({
    						path: "Depth",
    						operator: FilterOperator.BT,
    						value1: 10,
    						value2: 20
    					})
    				],
    				and: true
    			}),
    			large: new Filter({
    				filters: [
    					new Filter({
    						path: "Height",
    						operator: FilterOperator.GT,
    						value1: 20
    					}),
    					new Filter({
    						path: "Width",
    						operator: FilterOperator.GT,
    						value1: 20
    					}),
    					new Filter({
    						path: "Depth",
    						operator: FilterOperator.GT,
    						value1: 20
    					})
    				],
    				and: true
    			})
    		};
    
    		return ControllerExtension.extend("customer.adapt.listreport.products.ListReportControllerExtension", {
    
    			// this section allows to extend lifecycle hooks or override public methods of the base controller
    			override: {
    				// 	override public methods of the ListReport controller and its members like templateBaseExtension
    				templateBaseExtension: {
    					/**
    					 * Can be used to add filters. They will be combined via AND with all other filters
    					 * sControlId is the ID of the control on which extension logic to be applied.
    					 * For each filter the extension must call fnAddFilter(oControllerExtension, oFilter)
    					 * oControllerExtension must be the ControllerExtension instance which adds the filter
    					 * oFilter must be an instance of sap.ui.model.Filter
    					 */
    					addFilters: function (fnAddFilter, sControlId) {
    						var oComboBox = this.byId("boxTypes");
    						var sSelectedBoxType = oComboBox.getSelectedKey();
    						//lookup the filters from the definition
    						var oFilter = BOX_SIZES[sSelectedBoxType];
    						if (oFilter) {
    							fnAddFilter(this, oFilter);
    						}
    					}
    				}
    			}
    		});
    	});

     

  21. Now go ahead and preview as a web application.  Select Run-> Run as Web Application. If asked which configuration to use, select the Adaptation_index.html.

Congratulations, now you’re running your application! Try filtering on the box sizes and note the different results when you select Small, Medium or Large boxes.  If you like, you can customize the table to show the dimension columns to see whether the products will really fit in to the box sizes indicated.

Your variant of the Manage Products application is now complete and ready to deploy!  Unfortunately, the ES5 system does not allow the general public to deploy to it, so I cannot give you instructions for doing that part of the project. However, if you are curious about how to deploy a SAPUI5 application to SAP Fiori launchpad, here is an excellent tutorial that details the steps.

If you found this tutorial helpful and interesting, keep an eye out for a new OpenSAP course on SAPUI5 in early 2019. The new course will include some lessons on Adaptation Projects and other flexibility functionality.

Helpful Links:

SAPUI5 Visual Editor

Adaptation Projects for Fiori Elements Applications

Extending Delivered Apps Using Adaptation Extensions

Adaptation Extension Example: Adding a Button to the Table Toolbar in List Report

About the authors Jessica Merz and Sebastian Wennemers

Jessica is the Product Manager for SAPUI5 flexibility functionality and is always looking for ways to improve the user experience of SAPUI5 based applications.  With a background of nearly 20 years of user research and UX design, she enjoys helping people make their applications intuitive and delightful.
As Development Architect for SAPUI5 flexibility functionality Sebastian enables several people, from end users to developers, to get the best out of existing SAPUI5 apps. With the work of his team they can adapt these apps with easy to use tooling in a lifecycle stable and modification-free way, so that the apps fit best to their processes and needs.

 

 

Assigned Tags

      24 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Douglas Cezar Kuchler
      Douglas Cezar Kuchler

      This is really nice and useful!

      Thank you Jessica Merz and Sebastian Wennemers for sharing.

      I've made some experiments using it with a Fiori Elements app and really liked it. Now I am going to explore more to understand all the possibilities.

      I think it's valid to compare it with SAP Screen Personas for UI adaptation on classic ERP screens. This concept of adaptation projects makes me feel the same about the possibilities we have with SAPUI5 applications. As a developer I can say this is a great tool to increase and expand my productivity.

      Author's profile photo Jessica Merz
      Jessica Merz
      Blog Post Author

      Thank you Douglas Cezar Kuchler ! I hope your experiments are fruitful and I look forward to your feedback.

      Author's profile photo Snigdha Mallick
      Snigdha Mallick

      Hi Douglas Cezar Kuchler ,

      Can you please explain the difference between SAP Screen Personas and Adaptation Projects in terms of usage? 

      You have mentioned SAP Screen Personas is used for UI adaptation on classic ERP screens. What the Adaptation Project used on? And why is this difference?

       

      Thanks,

      Snigdha

      Author's profile photo Jason Scott
      Jason Scott

      Hi Jessica, Great post and timely as I'm about to create a whole bunch of changes to fiori elements apps. What I'm confused about however is the difference between adaption via the WebIDE as you've described here and adaption at runtime (key user tools)?

      It sounds like adaption in the WebIDE in "safe mode" is just the same as RTA - is that correct?

      Author's profile photo Jessica Merz
      Jessica Merz
      Blog Post Author

      Hi Jason,

      You are correct!  When you use the SAPUI5 Visual Editor in Web IDE and stay in Safe Mode, you have the same abilities as the key user adaptation (RTA).  Once you leave Safe Mode, you have much more flexibility.

      I look forward to hearing how this goes for you!

      Jessica

      Author's profile photo Jesse Brook
      Jesse Brook

      Hi Jessica, is it possible with the trial web ide / on premise version of web ide to do adaptations or use the SAPUI5 editor. I cannot see those features unless I'm using the Web IDE Full Stack / Cloud version.

       

      Thanks

      Author's profile photo Sebastian Wennemers
      Sebastian Wennemers

      Hi Jesse,

      sorry for the late answer. The SAPUI5 Visual Editor and Adaptation Projects are only available in the Web IDE Full Stack / Cloud version.

      Best regards

      Sebastian

      Author's profile photo Jun Wu
      Jun Wu

      Hi Jessica,

      Can I understand that the adaption project also cover what the extension project can do?

      Best regards,

      Jun

      Author's profile photo Oliver Graeff
      Oliver Graeff

      Hello Jun,

      sorry for the late reply.
      Yes. We're not there yet, but this is the direction.

      Cheers,
      Oliver

      Author's profile photo Urvish Vijay Panchal
      Urvish Vijay Panchal

      Hello Jessica,

      i am following your tutorial for my requirement to extend a controller for Fiori Elements application.

      but when i am trying to get refrence project from SAP UI5 Repository. i am getting following error mentioned in Screenshot. Kindly share your thought for this issue.

      Author's profile photo Rinaldy Alvin
      Rinaldy Alvin

      Hello Urvish,

       

      From your problem, it seems like that you are entering incorrect password for the back-end system on the destination. Try to use correct password, and the problem should be solved.

      Also, don’t forget to add /sap/bc/lrep on cloud connector so you can select what screen to adapt without showing "adaption project doesn't support the selected applications" error message.

       

      Hope this can solve your problem.

       

      Thanks!

      Regards,

       

      Alvin

      Author's profile photo Venu gopal Ghatam
      Venu gopal Ghatam

      Hi Jessica,

      I am getting Unable to determine Manifest.json file for the selected application error while creating Adaption project. Am i missing anything?

      Thanks,

      Venu.

      Author's profile photo Chandu 17
      Chandu 17

      Hello Jessica,

      Great block.Thanks for detail explanation.I was familiar with Adaption Extension but got to know few more points about safe mode.I am facing some unfamiliar issue in my web ide when i tried to use Adaption extension projects it says select a different application.Adaption project dosent support selected Application.But the same application i am able  to Adapt in other Web ide. Do you think are there any roles missing in the system.Below is the error

      Regards,

      Chandu

      Author's profile photo Rinaldy Alvin
      Rinaldy Alvin

      Hello Chandu,

       

      Please try to add /sap/bc/lrep into your cloud connector configuration. This should solve the problem. Or you can check on the Console Log for error detail.

       

      Thanks!
      Regards,

       

      Alvin

      Author's profile photo Rakesh Kumar
      Rakesh Kumar

      Hello Jessica/Experts,

      I am facing issue when trying to extend (add column) to the standard fiori elements app "Stock - Multiple Materials" for app type analytical (fiori elements). I have tried following extension project & adaptation project method as well, but i don't see any changes . Can you please check below post for same and provide any help if possible.

      https://answers.sap.com/questions/12868723/fiori-elements-app-extension-analytical-fiori-elem.html?childToView=12868751#

      Thanks,

      Rakesh

      Author's profile photo ARIJIT SARKAR
      ARIJIT SARKAR

      Hi Jessica/Experts,

      There is a requirement in my project which requires extension of a standard SAP FIORI Elements Overview Page   Application.The requirements are to extend the standard app by adding new stack card,  custom functionalities associated with the cards.

      I am using an Adaptation project in Web IDE to extend the app. I have created custom oData in the backend for the same.

      When I am trying to add a New Stack Card using the New Data Source and when I am giving the name of the custom oData it is showing an error.Please refer to error-1.jpg' attached for your reference.

       

       

      I also tried On right clicking on the project and Add New Odata Service , after clicking on finish button it throws an error mentioning 'Cannot add the service because there are no manifest.json,configuration.js,component.js or index.html files. Please refer to error-2.jpg attached for your reference.

       

      Please guide me how to resolve this issue.

      Regards

      Arijit

       

      Author's profile photo Matthias Brisseau
      Matthias Brisseau

      Jessica,

      Thanks a lot for this clear and useful blog.

      Like Chandu, I got error message: Select a different application.Adaptation project doesnt support the selected application when trying to create an adaptation project for a native app.

      Does it mean this feature is not available for all native apps? Or is there any prerequisite like minimum UI5 version?

      Regards,
      Matthias

      Author's profile photo Rinaldy Alvin
      Rinaldy Alvin

      Hello Matthias,

      Please try to add /sap/bc/lrep into your cloud connector configuration. This should solve the problem. Or you can check on the Console Log for error detail.

      And from what I read, you need at least SAP UI5 Version 1.60 to create adaption project.

      Thanks!
      Regards,

       

      Alvin

      Author's profile photo Sambhav Tripathi
      Sambhav Tripathi

      Hi Jessica,

      Thank you for sharing such a useful information.

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

      Application: https://fioriappslibrary.hana.ondemand.com/sap/fix/externalViewer/#/detail/Apps('F2445')/S14OP

      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 https://sapui5.hana.ondemand.com/#/topic/00683f95eff64d3d9e2991a7fd9f1db8

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

      Regards
      Sambhav Tripathi

      Author's profile photo Uttam Kumar
      Uttam Kumar

      thanks Jessica for the great blog,

       

      we have an error saying the application does not contain manifest.json, how to resolve this.

      Author's profile photo Nik Peters
      Nik Peters

      Hello Jessica,

      I tried to follow your steps from your block, but unfortunately I get an error in the Exercise step 6 "Select SAPUI5 Visual Editor".
      After i insert my credentials for the ES5 login I get the following error, both in the WebIDE and in the BAS:

      "Request Failed: URL: /destinations/ES5/sap/bc/lrep/appdescr_variant_prieview/"

      Therefore I am not able to enter SAPUI5 Visual Editor, can you please help me?

      Thanks, Nik

      Author's profile photo Thomas Knobloch
      Thomas Knobloch

      Hi Jessica,

      thanks for the nice post.

      I have a question regarding adding action to table of ListReport

      This would be done like this https://ui5.sap.com/#/topic/7619517a92414e27b71f02094bd08d06

      But as we have no manifest.json, how can I add an action then?

      Thanks and regards,

      Thomas

      --> I solved the problem --> just have to add a fragment 🙂

       

      Author's profile photo Srinath Velagala
      Srinath Velagala

      Hi,

      Could you please help me with Where to deploy the adaption project? - Frontend server or Backend server.

       

      Thanks in advance.

      Author's profile photo Yergali Yertuganov
      Yergali Yertuganov

      Dear Jessica,

      First of all thank you very much for your tutorial, which I have followed and got my adaptation project built usinf ES5 system. However my current task is to make an Adaptation Project to include Reuse UI Component of DMS (Document Management Service) and since this is more of a extension of this blog I have created another question under here if you could have a look:

      https://answers.sap.com/questions/13499614/adaptation-of-standard-fiori-apps-with-reuse-ui-co.html

      Many thanks in advance.

      Best regards,

      Yergali