How to adapt hybrid apps created with HAT to use Mobile Services on Cloud Foundry
Updated 18 February 2022: Added link to SAP Note regarding the status of these tools.
Updated 23 September 2020: Updated with information for exporting and importing the app.
Updated 20 June 2019: removed the requirement to download the project and modify/rebuild locally.
With SAP’s multi-cloud strategy in full swing, more and more customers are keen on using Mobile Services available on Cloud Foundry. Some of our customers are looking into migrating their existing solution from Neo to Cloud Foundry. Others have started developing their apps in a Neo environment and now want to deploy into a productive landscape based on Cloud Foundry. In this blog I will show you what can be done to resolve some of the challenges around building hybrid mobile apps for the Cloud Foundry environment.
Please note that the use of the Hybrid Application Toolkit extension in SAP Web IDE Full-Stack is no longer recommended. For more details, please you check this SAP Note.
Our current solution will not automatically create the mobile app, related configuration settings and destination in the Cloud Foundry environment. You will have to perform those steps manually.
Before I jump into the details, I want to provide you one important recommendation:
When you start developing a new mobile app, we strongly recommend that you consider developing this with either MDK (Mobile Development Kit) for cross platform applications, or our native SDKs (SAP Cloud Platform SDK for iOS or SAP Cloud Platform SDK for Android).
Starting development on Neo
When you develop an app in SAP Web IDE and use our Cloud Build Service to build the mobile app, we automatically generate the app in Mobile Services in the Neo landscape. Your mobile apps will interface with Mobile Services (on Neo) which acts as a proxy with other systems and services.
In this example, we’ll start by creating a new project in SAP Web IDE, developing the app in the Neo environment and then moving to Mobile Services on Cloud Foundry.
Creating an app based on the CRUD Master-Detail template
Let’s start in a freshly created workspace in SAP Web IDE Full-Stack.
We create a new project based on the CRUD Master-Detail Application template. Make sure you select the Neo environment in the Template Selection step.
In the next step you provide the basic information about your project.
For this example I will use the ES5 Gateway demo system. I’ve already created a Destination in SAP Cloud Platform (on Neo) to be able to use this service in SAP Web IDE (which is also residing in the Neo environment).
Unfortunately, the name of the destination I’ve used was not usable on Cloud Foundry. Please take note that you cannot use destination names that include a dash (“-“). So I had to recreate another one with the name “ES5Ludo”, which works fine, but I did not capture a screenshot.
We select the GWSAMPLE_BASIC service, which was already used in various demos, and fill in the template customisation.
After finishing the wizard, you can run the application in SAP Web IDE to see how it looks like as a web application. Make sure the app is able to run before you move to the next step. Debugging and fixing issues in a web app is much easier now than doing this further down the road when the app is running on your mobile device.
Enable as Hybrid Mobile Project
Once we have confirmed the web app works fine, we enable the project for mobile.
Once the project is enabled as hybrid mobile project, we will build the mobile app in the cloud. We could obviously change code, add more Cordova plugins, etc. But that’s not in the scope of this blog.
In this example, we will first create the app for the Neo environment. In the build wizard, please leave the options for “Save Xcode and or Android Studio project” and “Manually update configuration files” unselected. In the previous version of this blog we had to download the projects. This is no longer needed. We will automatically update configuration files (mobile/appConfig.js and config.xml) based on settings you’ve configured in the SAP Mobile Services cockpit on Neo. Later, we can use this as a reference for the configuration on Cloud Foundry.
Once the build is done, you will see the QR code and hyperlink to download the mobile app onto your device. The application will interface with SAP Mobile Services on Neo.
Mobile Services on Neo
Let’s take a look at the application that was created by the cloud build service in Mobile Services. For this, we go to the Mobile Services admin cockpit on Neo. From SAP Web IDE, you can navigate to Tools > SAP Cloud Platform Cockpit > Services > Mobile Services > Go to Service.
We can find the app in the list of Native/Hybrid applications. The Application ID here is generated by Hybrid App Toolkit.
Select the application to view the details.
An important item to check is the Connectivity feature. We will need to copy the Destination listed there.
To make it easier to migrate the application configuration, we can export it.
Creating the app in Mobile Services on Cloud Foundry
Since Hybrid Application Toolkit is actually targeting Neo landscapes, we have to create the mobile app manually in the Cloud Foundry environment. We need an exact duplicate.
Let’s open the Mobile Services Cockpit on Cloud Foundry.
We now have to create exactly the same app as available in Neo. The easiest way to do this, is by importing the application configuration we’ve exported in the previous step.
NOTE: in case you are importing an offline app, please ensure the offline feature is added in the app’s configuration, as this is likely not part of the exported configuration.
Below are the steps to create the app manually. You can skip these steps if you’ve imported the app, or just use it as a reference in case you want to troubleshoot and check the settings. It is recommended to check the connectivity settings and confirm you are able to access the data source. You might have to tweak the authentication settings here, depending on what your data source requires.
Creating the app configuration manually
Let’s start by hitting the button Create new app.
It is important to use exactly the same ID for the app.
Once the app is created, we need to add the Mobile Connectivity feature.
In the Cloud Foundry environment, you can add features as needed. In this case we only need to add the Mobile Connectivity. For offline apps, please ensure the offline feature is added.
Once added, configure the feature and create a new destination.
It is important to use exactly the same name as used in the Neo environment. And make sure the rewrite mode is the same.
Set the authentication to what your OData source requires. In this example I am using Basic Authentication to access the ES5 demo gateway system.
Once you are done, the destination is listed in the Mobile Connectivity overview.
First of all, please test whether you can reach the destination by using Ping.
Next, test the OData source using the same path as used by your application. You can find the path in the manifest.json file of the web app. You should be able to view Product data available in the sample OData source.
In this example the path is: sap/opu/odata/iwbep/GWSAMPLE_BASIC
By default, the newly created applications in Mobile Services on Cloud Foundry will use OAuth as authentication method. However, our (Neo) app is expecting to make use of SAML.
So we need to change the Security setting to use SAML.
In the tab Application Links in Mobile Services, please check the URL specified for Server API. We will need to modify the mobile app to point to this URL, instead of the URL pointing to the Neo environment.
Rebuilding the app to use SAP Mobile Services on Cloud Foundry
Following the example, now it is time to modify the project in SAP Web IDE. Open the file mobile/appConfig.js.
Ensure the ‘appID’ matches the App ID specified in Mobile Services.
The fioriURL should match the Server API URL as mentioned above. And please make sure you don’t miss the “:443” port number after the domain ! If your url contains a path, then make sure the port number comes before the path.
The auth settings should match the security configuration in Mobile Services.
Next, open the file config.xml and ensure the ‘id’ is the same as the App Id configured in Mobile Services.
Now, let’s rebuild the mobile app to consume SAP Mobile Services on Cloud Foundry.
When configuring the Mobile Build Settings, please make sure to tick the option to manually update configuration files. By default, this is option is not selected and we then automatically update configuration files (mobile/appConfig.js and config.xml) with the settings you’ve configured on the SAP Mobile Services cockpit (on NEO !). In this particular case, you want to keep the configuration files untouched as we don’t want to use the default Mobile Services.
Select Build. This will still make use of Cloud Build Services available in the Neo landscape.
Before you install the new version of the app on your device, please ensure to delete the previous version (on Android: including its data). If you skip this step, your app might have trouble starting up (blank screen).
Once the build is done, you can install the app on your device by using the QR code, or by downloading the binary via the url. Please be aware that we provide this as a convenience to developers. This should not be used for distributing the app within your company. You should be using some MDM offering for that purpose.
Once you run the application on your device, you will notice that you have to authenticate against the IDP configured on the Cloud Foundry landscape. The app should work the same way as before. You can check the logs in the Mobile Services cockpit on Cloud Foundry.
In short, the steps described are as follows:
- Create and build your application in the Neo environment
- Copy the Mobile Services app configuration to CF. You can use the export/import feature for this.
- Modify the SAP Web IDE project to use the Mobile Services App URL on CF
You could actually skip step 1 and immediately create a new app in Mobile Services on CF and then fill in the required configuration settings in step 3. However, this is a bit error prone. I therefore recommend starting in the Neo environment.
If you want to move an existing app from Neo to CF, you can also skip step 1.
Changing from Mobile Services on Neo to Mobile Services on Cloud Foundry is pretty straightforward. Just export the app configuration in the Neo environment, and import it into the Cloud Foundry environment. After changing the fioriURL, you just need to rebuild the app.
Is there no way to publish an existing Cloud Foundry project as a Hybrid App using WebIde Fullstack?
If you are able to enable your project for mobile, then you should be able to build it as hybrid app in a Neo environment, after which you can manually create the app in Mobile Services on Cloud Foundry.
What if I dont have mobile service enabled on neo but I still want to create the app on Cloud foundry mobile services?
Without Mobile Services on the Neo landscape you will not be able to make use of the Cloud Build Service to build your hybrid packaged app. In that case, even if you still have access to SAP Web IDE Full-Stack, you will not be able to use Hybrid Application Toolkit.
This blog post is targeting existing Mobile Services NEO users who want to migrate their application to Mobile Services on Cloud Foundry.
For developing new mobile apps in a Cloud Foundry environment, we recommend using MDK. If you want to continue developing hybrid cordova based apps, you will need to use the Kapsel SDK in combo with Mobile Services on Cloud Foundry.
Thank you for your guide.
Currently the only options to move a Kapsel Hybrid App from Neo to Cloud Foundry is by using WebIDE FS on Neo. I assume that Business Application Studio will have support for HAT in the future. Is this correct?
Unfortunately doing the migration to MDK doesn’t make sense and developing 2 native apps (one for Android and another for iOS) from scratch also isn’t a possibility. Does SAP intend to keep supporting Cordova based apps on SCP Mobile Services and HAT?
There are no plans to migrate HAT to Business Application Studio. The alternative is to use standard Cordova tools combined with the SAP Kapsel SDK, which is part of our Mobile Platform SDK.
HAT provides convenience to developers by helping to configure and automate some of the steps required to build hybrid apps. Without HAT, it is still possible to build hybrid apps that make use of SAP Cloud Platform Mobile Services and the Kapsel SDK. This does obviously require some more manual work.
SAP will continue supporting existing customers who are using HAT. We encourage the use of MDK moving forward.
Thank you for your blog.
I have an hybrid app on NEO with SCIM configuration for the user authentication, so the user can use the on-premise credential.
With CF I don't see the SCIM configuration, so how can I migrate this app ?
Thank you for your help.
In SAP Cloud Platform Mobile Services on Cloud Foundry, go to your application configuration and select the security tab. In Basic Settings, you can specify the URL for SCIM.
Thank you for your reply !
In case you (or others reading this) are looking for documentation:
You've mentioned that on Neo, the mobileservices destination was created automatically by enabling mobile services. This is correct. SAP Web IDE is a Neo service and the Hybrid Application Toolkit extension will make use of the mobileservices destination on Neo to find the correct Mobile Services instance to connect with. If the mobileservices destination is missing on Neo, you will see these errors.
To solve this, you should add a mobileservices destination in the SAP Cloud Platform NEO cockpit, which points to the admin API of mobileservices on Neo (not CF).
Hybrid Application Toolkit only works with Mobile Services Neo for configuring the apps and building them with the Cloud Build Service. To make your apps work with CF, you'll need the manual steps described in the blog post.
Thanks for the reply,
the problem is that I have a test acount and for the moment sap doesn't let me access the neo environment and I can't enable the mobile services.
How can I solve this problem?
With test account, you mean Trial ?
I don’t understand why you cannot access the Neo environment.
Did you raise a support ticket?
I've created a new trial account myself just now (data centre : Europe) and mobile services is enabled by default.
If you cannot get your existing account fixed, I suggest you just create a new one (you'll have to provide another email address).
Make sure you finish your migration tasks before 13 November !
Does mobile services exists on SCP Neo ?
I purchased a mobile services license but I only find access to it on the cloud foundry.
If I understood correctly all your response from comments, if mobile services doesn't exist anymore on non trial neo account we can't make hybrid app anymore ?
I cannot comment on the purchasing process. What I can confirm is that existing users can continue using SCP Neo, including Mobile Services on Neo.
For new licenses, you will probably get a Cloud Foundry license by default. If you really need a Neo license, then I recommend talking to someone from our sales team.
Hi Ludo Noens .
I'm working in a project to migrate an SAPUI5 App (HAT) from Neo to Cloud Foundry and all you explained worked perfectly. Now, I'm able to trigger de build from SAP WebiDE on Neo pointing to my CF Mobile Service.
My question for you is, do you know if we are going to have a option on SBAS to trigger the build and deploy to Mobile Service on CF?
The reason for my question is, with the current scenario I'll need to keep my Neo Subaccount only to run WebIDE and Build my App on Mobile Service meanwhile everything else runs on my CF Account.
Thanks for all the help and support!
There are no plans to add this option in SAP Business Application Studio.