Product Information
Migrate SAP Fiori projects from SAP Web IDE to SAP Business Application Studio
Since the release of SAP Fiori tools, we have invested heavily in the SAP Fiori Application Generator to create new SAP Fiori applications. The feedback and participation from the SAP community has been nothing short of amazing, which has enabled the SAP Fiori Application Generator to grow, as shared by my co-product owner Ian Quigley here. But what about your existing projects that you created in SAP Web IDE and you wish to migrate to SAP Business Application Studio?
In this blog, I will be explaining the steps you can take to migrate your projects and make use of the tools and wizards offered by SAP Fiori tools for the entire development lifecycle of your SAP Fiori application (See the feature matrix of SAP Fiori tools). My focus in this blog will be the SAP Fiori tools Migration tool and not topics like destination configuration, authorization, etc.
For migrating HTML5 ppplications in SAP BTP from the Neo Environment to the SAP BTP Cloud Foundry Environment, please check the respective help page and guide here.
SAP Fiori tools comes with Migration tool
SAP Fiori tools comes with a Migration tool which will help you move your SAP Fiori projects from other development environments, such as SAP Web IDE, to either run on SAP Business Application Studio or Visual Studio Code (VS Code).
To get you started on migration path, it is very important that if you are new to SAP Fiori tools or SAP Business Application Studio, I would highly recommend you to spend some time on familiarizing yourself with the tools. Here are some great resources to get you started (not limited to):
- Create a List Report Object Page App with SAP Fiori Tools
- openSAP: Developing and Extending SAP Fiori Elements Apps
- Create an Incident Management App with SAP Fiori Elements for OData V4
- Simplify Development of SAP Fiori Apps with OData V4
- Extend SAP S/4HANA with a Custom UI on SAP Business Technology Platform
- Create Analytical SAP Fiori Apps Quickly and Efficiently
Differences from Web IDE projects
Before you migrate your existing projects, let me highlight the main project structure difference in comparison to what you were used to when using SAP Web IDE. Now, projects created/migrated with SAP Fiori tools will be structured as a NodeJS project, which means it has a node_modules folder, a package.json and associated yaml config files.
Package.json
– Scripts to build, test, preview, deploy, undeploy, etc.
– Dependencies:
- @sap/ux-specification: SAPUI5 version-specific module for Fiori elements application configuration
- @sap/ux-ui5-tooling: Preview and command line interface tools
- @sap/ux-ui5-fe-mockserver-middleware: OData Mock Server
ui5-*.yaml
– Preview configuration for UI5 version and theme
– Configuration for destination. E.g., deployment configurations
Migration tool simplifies the process
As mentioned earlier, SAP Fiori tools come with a migration tool which will help you in migrating your SAP Fiori apps. Over the past few months, based on our interaction with customers, we have covered multiple new scenarios to enable a smooth migration experience. Currently, you can use SAP Fiori tools migration tool for migrating applications which are:
- SAP Fiori elements V2 & V4
- SAPUI5 Freestyle
- SAPUI5 Adaptation projects for use in SAPUI5 Visual Editor tool (not part of SAP Fiori tools) in SAP Business Application Studio
Set up your development environment
First, let’s ensure you have the right development environment set up including SAP Fiori tools installation. Depending on whether you are using SAP Business Application Studio or VS Code, here are some of the helpful links:
- SAP Business Application Studio: Follow the Getting Started steps to launch SAP Business Application Studio and create a dev space of type SAP Fiori. Dev space of type “SAP Fiori” already comes with SAP Fiori tools (along with other relevant extensions) installed.
- VS Code: For VS Code, you would need to do some prep work like installing VS Code, NodeJS, mta tools, SAP Fiori tools extension pack, etc. It’s typically a one-time set up and you can find the steps here.
Import your existing project (and add version control)
Next, before you import your project to be migrated into your workspace, I would recommend that your project is under a version control system. Why? Because some of your project’s files will be changed so that they are compatible with SAP Fiori tools. You can easily do a diff and review the changes before finalizing the migrated project.
SAP Business Application Studio already allows you to connect to private or public repositories (See details here).
SAP Business Application Studio – Clone Git project
Alternatively, you can simply drag and drop your project from your local file system to the workspace.
The Migration Prompt gets things started
Once you have cloned your project into the workspace, you will see a prompt from SAP Fiori tools which is notifying that you have projects in your workspace which have been identified for migration.
SAP Fiori tools Migration Prompt
Start Migration: Clicking on this button will take you to the Migration View from where you can migrate one or more projects at once.
Don’t ask again: Clicking on this button will stop the migration prompt from appearing again whenever you import a project into your workspace. You can disable/enable migration prompts from the extension settings as shown below.
SAP Fiori tools – Extension settings for Migration Prompt
Migration View lets you migrate multiple projects
In case you do not start migration right away when prompted, you can always use the command “Fiori: Migrate Projects for use in Fiori tools” which will open the same migration view from where you can migrate your projects.
Let’s talk about the Migration View now. The migration view has been designed to accommodate migrating multiple projects at once with some input from the user for each project, if needed.
SAP Fiori tools – Migration View
In my example above, I have one project in my workspace that can be migrated, and it’s listed in the migration view. As a user, I can fill in the columns and then click on “Start Migration”. When I select a project from the list by clicking on the checkbox, this project will be migrated when the Start Migration button is clicked. Note: The Start Migration button will be disabled until at least one project has been selected.
In Migration view, columns represent the following:
Column Name | Description |
Module Name | Module name comes from the manifest.json id or pom.xml |
Project Path | The file path to the location of the project |
SAP System | A dropdown detailing the SAP system that should be used in migration. The dropdown lists all the saved systems in VS Code or all the destinations available in SAP Business Application Studio. Selecting an SAP System from the dropdown sets the hostname and client automatically |
Destination | A free-text field that by default contains the system name from the project being migrated. It should default to the destination from the source project neo-app.json. Destination is only used by Fiori tools in SAP Business Application Studio and not in VS Code. To allow a project to be compatible with SAP Business Application Studio and VS Code please provide a Destination and Hostname that is accessible to both. It is recommended to use a destination for the Frontend Server which has SAPUI5 libraries installed rather than connecting to the backend OData server directly. |
Hostname | An input box detailing the backend hostname to be used in migration. Should be a valid URL or blank. This hostname is only used by SAP Fiori tools in VS Code. |
SAP Client | An optional numeric field detailing the SAP client to be used in migration. Should be provided in case the client is not the system default. |
UI5 Version | An optional field detailing the UI5 Version to be used in migration. Defaults to the version from neo-app.json if defined. Otherwise, “Latest”. |
Once you click on the “Start Migration” button, the selected projects will be migrated by the SAP Fiori tools migration tool.
SAP Fiori tools – Migration Results View and Application Information Page
After the project or projects are migrated, you can expect the following:
- Migration Results view will show you the result of the migration process.
- “Application Information” will be open automatically if only one project is migrated. If multiple, you can click on the “View Info” under Actions column to open Application Information page of respective project.
- A new terminal tab for each migrating project outputting logs for the npm install process.
Last, but not least, after migrating your project(s), please make sure that your application runs locally, and you are able to use the SAP Fiori tools options. The easiest way is to launch the “Application Information” page of each project and run some options like Preview Application, Open Page Map, Open Guided Development, etc.
So, let us wrap up some pre-requisites for a successful migration process:
- Make sure you have an active subscription to SAP Business Application Studio.
- We recommend you get some hands-on practice with SAP Fiori tools and SAP Business Application Studio.
- Verify that the destination in your SAP BTP subaccount is configured correctly. Any issue with destination will prevent you from previewing applications with live backend data.
- Set up a version control system for the project you will migrate.
A note on re-usable libraries in migrated projects
Please note that migration of SAPUI5 re-usable libraries is not required for use in a migrated SAP Fiori application using Fiori tools. But loading re-use libraries has changed. Routing is no longer performed by the neo-app.json file. So, when you want to preview your application, you have 2 options here based on your use case:
- Reuse library will be loaded automatically from the Frontend server based on the “Destination” you had chosen in the migration view during migration. Migrated project’s webapp/utils/locate-reuse-lib.js attempts to load the reuse library from the Frontend server.
- Reuse library can be loaded from workspace too. After migration, you can clone a Reuse library in your workspace and follow these instructions for using a wizard to configure new routing. Routing is configured in ui5*yaml file(s) as described here https://www.npmjs.com/package/@sap/ux-ui5-tooling#3-serve-static.
What’s Next?
- Your feedback is important. Please reach out to us if you have any issues during the migration process.
- You can create incidents with SAP Fiori tools using component “CA-UX-IDE”
- Feel free to contact myself Sushant Priyadarshi, Ian Quigley or Austin Devine (send us an email)
- If you haven’t already signed up, I would also like to invite you to participate in the SAP Fiori elements and SAP Fiori tools Roundtable, where you can share your experiences with the development team and other SAP Fiori development experts.
- And stay tuned! We have lined up some nice blogs on topics around Deployment, Destination validations, etc.
For the SAP UX Engineering team,
Sushant Priyadarshi
Amazing blog, great for learning SAP Fiori. Thank you.
Thanks for sharing in detailed information on migration.
Thank you,
Syam
@Sushant Priyadarshi
Can you please clarify, does this only apply to cloud-based scenarios?
For those of us with on-premise environments, should we still be looking to migrate from WebIDE to BAS, or is that not possible?
For on-premise, is the runtime environment always Neo or can it change? If so, how?
Thanks
Hi Ramin,
Yes this migration also works for on-premise Fiori projects migrating from WebIDE to BAS.
The runtime can be changed from neo to cloud foundry.
https://blogs.sap.com/2022/01/14/designing-ui5-apps-for-sap-launchpad-service-part-1/
https://help.sap.com/viewer/b98f42a4d2cd40a9a3095e9f0492b465/Cloud/en-US/b1763fd06421457b9970a3555020e750.html
Could Fiori Tools import prototype project created using SAP Build?
Hi Adi,
Yes it is possible to export a prototype from SAP Build and import it into Fiori tools.
You should be prompted to migrate it.
Note the npm run start preview will not work well as there is no service connected to the prototype.
Instead use npm run start-mock to preview the prototype in Fiori tools.
Regards,
Austin
WHen We migrate an app with more than one service. It returns metadata 404 . Can you please help Sushant Priyadarshi
Hi Akshaya,
Can you provide more information on this issue?
What steps did you perform?
If you are running "npm start-mock" or "npm start-local" then you may want to right click on the manifest.json and choose "Open Service Manager" to sync the metadata.xml from the backend server. It will copy the metadata.xml to the local project.
Thanks,
Austin
Hi Austin
Thanks for the response. The app works perfectly fine in the local and also when run from the ""HTML5 Applications" in our subaccount. But when it is deployed to cloud foundary launchpad , it throws 404 error.
HI Akshaya,
we had a similar issue. If you check the network tab and check the "metadata" call, does it have the ID of your deployed app in the URL - and your odata calls don't but have cp.portal instead?
... launchpad.cfapps.eu10.hana.ondemand.com/cp.portal/sap/opu/odata/sap/...SRV
If yes, that's the same issue we had and I fixed it by setting the URLs via controller during the runtime of the app by fetching the model's relative path during runtime like this:
Here's what helped me: Calling Service using AJAX in Fiori Elements Extension doesn't work in Launchpad | SAP Community
Good look and best regards,
Lisa
removinf front slash in oData reference solved the issue
sap/opu/odata instead of /sap/opu/odata
Hi Sushant Priyadarshi Ian Quigley Austin Devine
I am facing issue when creating Fiori List and Object Page application using Business application Studio... Application never shows data on Object Page...
Please suggest.
Thanks-
Abhishek
Hi Sushant Priyadarshi
Thank you for this blog!
Is it possible to perform the migration via commands in the terminal? My goal is to automate this process and this is only possible, if I know which commands the UI is executing in the background.
Best Regards,
Daniel
Hi Daniel Krancz ,
No we don't provide a terminal migration option.
However if you have a batch of projects to migrate, cloning all the git repos into your workspace then open the migration command all the supported projects will be listed for migration.
You can provide the appropriate inputs for each (if the defaults are not ok) and migrate them all in 1 batch.
Would this work for your use case?
Kiind regards,
Austin
Hello Austin Devine
thank you for your fast response!
Too bad that the migration cannot be started via the command line. The problem is that the migration of our HCM apps is recurring. (Unfortunately) The apps must still be developed in the WebIDE. The apps are deployed to our S/4HANA system and to the CF. Whenever a new version of an app exists, they have to be manually exported from the WebIDE, imported into a BAS, migrated, and then converted into an MTA project with a managed app router, in order to publish the app in SAP Build Work Zone, Standard Edition. I would have liked to automate this process via CI/CD, so commands would have been helpful. Because of compatibility issues, it is currently not possible to have a content federation between our on-prem. FLP and the SAP Build Work Zone, Standard Edition (formerly Launchpad Service).
I think I need to keep brainstorming how to automate these manual steps! Do you have any ideas or suggestions?
BR
Daniel
Thank you for such informative discussion. I have an application with minUI5Version - "1.34" and contains 4 list report within the custom application. When I started migration it got stuck in an infinite loop of EOF syntax error. Any leads would be much appreciated. Added the screenshot for reference.
Kind regards,
Vishrut