My Tips for Migrating very old Fiori Apps to BTP Cloud Foundry

[AlessandroSpadoni]

Introduction

Migrating SAP Fiori applications to the BTP Cloud Foundry environment can be a complex but necessary task, especially given the impending sunset of the SAP NEO environment on December 31, 2028. This blog aims to share my personal tips for migrating older SAP Fiori apps, whether from on-premise systems or from the NEO environment.

The official SAP docu.mentation, "Migrating Applications in SAP BTP from the Neo Environment to the SAP BTP Cloud Foundry Environment," is a comprehensive resource that covers all aspects of the migration process, starting from project migration using the Business Application Studio (BAS). 

While the official guide is exhaustive, my blog provides additional help based on my field experiences. These tips might prove useful for someone in a similar situation, offering practical insights to navigate the migration process more smoothly.

Your app may not have the manifest.json : Creating a Descriptor File for Existing Apps

You might not find the manifest.json in the app you need to migrate.

In this case, you have to create it manually (this is also mandatory for the migration of the project with BAS). This link in the SAPUI5 documentation, 'Creating a Descriptor File for Existing Apps,' is very useful, and I recommend starting here.

Some points to watch out for:

• be careful with the '/' in the uri section of dataSources, remove it to have relative URLs instead of absolute ones

• pay close attention to correctly set up the 'models' part under 'sap.ui5,' because the big difference is that the framework creates the models for us, so you need to define them correctly based on the models that were previously created manually in the Component.js, where you should remove the creation of models (this part is also in the UI5 documentation, but it is easy to make mistakes in manual creation)

• Remember to also include sap cloud service:

"sap.cloud": {
"service": "yourservice"
}

Identify Endpoints dinamically created via JavaScript

You might have destinations defined in xs-app.json for APIs that are invoked from JavaScript, for example with $.ajax or simply via window.open for downloading an attachment or other purposes.

The path in these cases is often constructed dynamically via JavaScript, following the pattern defined in your xs-app.json that points to the external system destination.

Make sure to identify these cases because you need to remove the initial '/' here as well to correctly identify the route

Workzone

Add the inbound intent in your manifest.json

If you are going to use Workzone, you also need to include in your manifest.json the intent details and description, icon, subtitle, etc., that will be used in the tile. For this, you need to define the crossNavigation Inbound section

"crossNavigation": {
  "inbounds": {
    "your-inbound": {
      "signature": {
        "parameters": {},
        "additionalParameters": "allowed"
      },
      "semanticObject": "yourSemanticObject",
      "action": "Display",
      "title": "{{appTitle}}",
      "subTitle": "{{subTitle}}",
      "icon": "sap-icon://wallet"
    }
  }
}

If you need multiple intents for the same app

It is very common to want different tiles with different parameters for the same App.

While it was easier to configure this scenario in the old Neo Cloud Portal Service or on-premise Launchpad, it seems not possible to have multiple Intents for the same app in Cloud Foundry.

Here is an interesting Question by @MikeDoyle   where the only solution seems to be create a “Local Copy” and then defining a new “Tile” with different parameters locally https://community.sap.com/t5/technology-q-a/how-to-deploy-multiple-intents-of-same-fiori-app-to-work...

Order of Tiles

Another common aspect is that you will be asked to replicate the same order of the Tiles that is already present in the old Cloud Portal Neo or the on-premise Launchpad.

It is very important to maintain a consistent order of Tiles and configuration with the past. For this topic, the great blog by @NabiZamani at this link https://community.sap.com/t5/technology-blogs-by-members/changing-the-order-of-groups-and-tiles-in-y... is very useful.

In my case, replicating the order of Tiles in a group seems simpler than you might think: the order of the Tiles is determined by the order in which the app is saved within the group.

Stable UI5 Version

In some situations, you may need to use a stable SAPUI5 version to run the migrated applications, which might not work correctly with the latest SAPUI5 release.

This happened to me, for example, with a rather complex custom control. In this case, the quickest way to get the app working is to set a UI5 Stable Version.

For this, two community links helped me: this Question by @miltonc https://community.sap.com/t5/technology-q-a/stable-sapui5-version-for-custom-apps-in-sap-build-work-... and the answer by @Ivan-Mirisola at this question https://community.sap.com/t5/technology-q-a/how-to-fix-sap-ui5-version-in-sap-btp-launchpad-service/...

the main points are:

• Set your stable version in the manifest.json of your app, taking into account the patches, to avoid hardcoding a specific version. You can specify an "x" to always use the latest patch. For example:

"sap.platform.cf": {
  "ui5VersionNumber": "1.108.x"
}​

• Use the same stable version for all the apps that will go into the same Workzone Site; otherwise, the most recent release will be used
• If you try to execute the command sap.ui.version from the console, it will always return the most recent version used by Workzone, making you think the stable version is not being used. See the first comment in the link I posted where you can execute Shift + Ctrl + Alt + P to bring up a Technical Information Dialog and check if your UI5 Stable Version is being used

ShellUIService

You might find ugly code like this in the old application:

sap.ui.getCore().byId("shellAppTitle").getModel().getData().application.title = ' ..... ';
sap.ui.getCore().byId("shellAppTitle").getModel().updateBindings();

with the purpose of dynamically updating the title of your app within the Launchpad. The correct way to do this in Workzone is described very simply in the overview of the class sap.ushell.ui5service.ShellUIService

Declare the usage of the service in the manifest:

"sap.ui5": {
"services": {
"ShellUIService": {
"factoryName": "sap.ushell.ui5service.ShellUIService"
}
}
}

and in your controller

this.getOwnerComponent().getService("ShellUIService").then(
						function (oService) {
				oService.setTitle('....');
						},
						function (oError) {
				console.log("Cannot get ShellUIService");
						}
					);

User API Service

If the app you need to migrate from Neo used the userapi service, you need to adapt it to use the corresponding Cloud Foundry service. Besides the official documentation here, I found the documentation on npmjs here very useful.

Essentially, you need to add the routing to the user API in your xs-app.json

{
  "source": "^/user-api(.*)",
  "target": "$1",
  "service": "sap-approuter-userapi"
}

This way, you can use /user-api/currentUser or /user-api/attributes to call from your app.

Attention point: the JSON returned is not identical in the attributes. For example, in the Neo app I migrated, the attribute 'login_name' was used, which in Cloud Foundry becomes simply 'name’

Protect HTML5 Apps with XSUAA

Another issue that may arise is protecting access to Fiori Apps if they are run via direct link without Workzone.

While in NEO there was a configuration in the cockpit where you could associate a Role to enable authorization for opening the App, in Cloud Foundry this is a bit different.

HTML5 Permission in NEO

If you use the managed approuter of Workzone, your Apps will be in the HTML5 Repository without being able to define any roles, but you can protect the application using an xsuaa scope within the xs-app.json.

So, in the xs-security.json you can define a scope (e.g. frontendscope)

{
"xsappname": "testprotectedapp",
"tenant-mode": "dedicated",
"description": "Security profile of called application",
"scopes": [
{
"name": "$XSAPPNAME.frontendscope",
"description": "Protected App Admin"
}
]
}

This scope then needs to be defined in a role template and role collection. To protect the app, you just need to define the scope in the xs-app.json in the route for the HTML5 Runtime.

{
"source": "^(.*)$",
"target": "$1",
"service": "html5-apps-repo-rt",
"authenticationType": "xsuaa",
"scope": "$XSAPPNAME.frontendscope"
}

Users who do not have a role with this scope will receive a 403 Forbidden error when opening the link.

sap.ca.scfld

Last but not least, the nightmare sap.ca.scfld. If you don't know it, consider yourself lucky. However, if you do know it and need to migrate old apps using it to Cloud Foundry, you might face many problems. As rightly mentioned in this old blog, the only consideration to make is 'don't use it!'

These are libraries that SAP used in very old Fiori apps to accelerate the development of applications, especially Master/Detail.

The particularity is that the routes are configurable and predefined in the Component.js, while the OData services are in the Configuration.js file.

In simple terms, I tried to be as conservative as possible and used the jQuery.sap.getModulePath function to get the complete endpoint at runtime for the OData because I wasn’t able to define the models in manifest.json

You might also encounter errors like this when the app is added to Workzone

The way I found to resolve this is to disable the 'Asynchronous Module Loading' option in your Workzone Site settings

In conclusion, you should not migrate Fiori applications that use the sap.ca.scfld library but instead recreate them from scratch. However, I understand that in some situations, you might have to take the 'mandatory migration of the old app' approach because Neo is being retired, there is no time, the client's IT department demands it, or for many other reasons beyond our control. In this case, with these adjustments, the app can be opened, but this can only be a temporary solution and it's important to emphasize this.

I will try to update this blog with new insights based on the experience of future similar projects if there are other interesting points.

Happy migrating!