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):
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:
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:
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:
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).
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.
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.
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.
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:
Once you click on the “Start Migration” button, the selected projects will be migrated by the SAP Fiori tools migration tool.
After the project or projects are migrated, you can expect the following:
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:
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:
What’s Next?
For the SAP UX Engineering team,
Sushant Priyadarshi
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,quiggs1000 or austin.devine2 (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
- SAP Managed Tags:
17 Comments
