How to migrate your hybrid mobile (HAT) project out of SAP Web IDE Full-Stack
Updated 21 Oct 2020: added section regarding missing features and how to solve this.
This blog post is targeting developers who have created hybrid mobile apps in SAP Web IDE Full-Stack with Hybrid Application Toolkit (HAT), and want to migrate their project to a different development environment.
There can be several reasons for migrating your project. A few practical examples that I’ve encountered with customers are:
- Submitting the application for publishing in the Apple App Store.
- The need to have full control on the project’s sources, configurations and the dependencies used (e.g. SDK updates not yet available on our Cloud Build Service).
- The ability to tweak the UI5 libraries included in the app to reduce footprint.
- Setting up a CI/CD environment.
Before we dive into the details, let’s take a look at where we are coming from.
When we started with the Hybrid Application Toolkit extension, SAP Web IDE was basically targeting web application development. With HAT, we’ve provided an extension to this use case, to allow developers to create mobile apps as well. While adding this capability, we’ve made sure developers were able to continue the development of their web application. Developers were then able to deploy the web application to a frontend server and build a mobile app from the same code base. This multichannel approach has proven to be tricky, as implementing code that is able to run in both web as well as mobile environments is hard to maintain.
In the screenshot below, you can see a project I’ve created based on the Fiori CRUD Application template available in SAP Web IDE Full-Stack. The web application’s code is residing in the folder called ‘webapp’. There are also some project related configuration files in the project’s root folder.
In the screenshot above, you’ll notice that all the source code is under revision control. The dots in front of the filename and folders indicate the status with colour coding.
Using a Git repository to manage your project
When working with source code, you should be using a revision control system. SAP Web IDE Full-Stack has built-in support for Git. If you want to learn how you can use your GitHub repository as remote repository, then please take a look at the tutorial here: https://developers.sap.com/tutorials/webide-github-import-project.html
To connect to your GitHub repository, make sure you have created a token in GitHub and use that to authenticate from SAP Web IDE Full-Stack.
By using a Git repository, you can easily track the changes made by HAT during the development process. We’ll make use of it in this blog post.
Mobile enablement of the web app project
We’ll need to add some code and configuration files before we can build a mobile app from the web application’s source code. For this, the user has to right-click on the project and select Mobile > Enable as Hybrid Mobile Project in the context menu.
In the SAP Web IDE Full-Stack console you will notice the steps taken:
16:44:22 (hat) Adding the bootstrap files into the "mobile" folder... 16:44:26 (hat) Generate and add appRoutes.js into the "/CRUD179/mobile" folder 16:44:26 (hat) Generate and add appConfig.js into the "/CRUD179/mobile" folder 16:44:26 (hat) Generate and add config.xml into the "/CRUD179" folder
This will add the Apache Cordova specific config.xml file in the project’s root, and several files in a folder called ‘mobile’ which will help bootstrap the mobile app. You can find the changes in the Git repository. You can ignore the file mobile/hybrid/pulltorefresh.min.js, as this is only used in the context of a Developer Companion app.
The config.xml file and the file mobile/appConfig.js contain placeholder values, as these are settings related to the application in SAP Cloud Platform Mobile Services. These values will be filled in automatically once the application is created in Mobile Services through our Cloud Build process.
Another file that is generated is called mobile/appRoutes.js. This contains the path and destination of the OData source used by the application.
Building the app in the cloud
In the project’s context menu, select Mobile > Build Packaged App. Make sure to select an Android and/or iOS signing profile and select “Build”.
You will notice the following steps in the console:
16:51:29 (hat) Parse config.xml to check if Android Package Name is defined 16:51:38 (hat) 16:51:38 (hat) =============================================================== 16:51:39 (hat) Create a new mobile services application for the CRUD179 app 16:51:39 (hat) The App ID in Mobile Services is com.sap.webide.x39437ec95f8449b8975342875b8fbaf2. 16:51:39 (hat) Set the security configuration of the CRUD179 app 16:51:39 (hat) Parse appRoutes.js for backend declaration 16:51:39 (hat) Configure the OData backend connectivity of the packaged app 16:51:41 (hat) Create a container for the CRUD179 app 16:51:41 (hat) Set the selected plugins for the CRUD179 app container 16:51:42 (hat) Retrieve the security configuration of the app 16:51:42 (hat) 16:51:42 (hat) Gather the information of the project and its dependencies 16:51:42 (hat) Exporting the CRUD179 project from workspace... 16:51:42 (hat) Parse and update config.xml with the latest app settings 16:51:43 (hat) Assembling dependencies into project zip... 16:51:43 (hat) Update appConfig.js with the latest app settings 16:51:43 (hat) Add the mobile specific files into the CRUD179 project zip 16:51:43 (hat) Package Cordova project source bundle 16:51:43 (hat) 16:51:43 (hat) Sending the project zip of the CRUD179 app... 16:51:45 (hat) 16:51:45 (hat) Start building the packaged app 16:51:45 (hat) Waiting for the build status... 16:51:45 (hat) 16:51:55 (hat) The CRUD179 app Android build: Queued 16:51:55 (hat) The CRUD179 app iOS build: Queued 16:52:15 (hat) The CRUD179 app Android build: Building 16:52:15 (hat) The CRUD179 app iOS build: Building
Let’s take a look at what is going on here behind the scenes:
- If the application configuration in Mobile Services is not available yet, then:
- We will generate a new one, with an App ID that is unique
- The security configuration of the app is set using default values (SAML).
- We configure the backend connectivity of the app, using the information in the appRoutes.js file. This includes creating a mobile destination.
- Application version numbers are set or increased.
- All source files related to the project are collected:
- The ‘webapp’ folder in the SAP Web IDE project
- The ‘mobile’ folder content is merged into this file structure
- If the web application is an extension project, then we fetch the parent project’s source files from the frontend server.
- If the web application makes use of a reuse library, then we fetch this as well.
- Some configuration settings are copied from Mobile Services into the placeholder values mentioned before (in config.xml and appConfig.js).
- All sources are bundled into a zip file and sent to our Cloud Build Service, through Mobile Services. Take note that Mobile Services is the central service here, where you can further configure the application (e.g. use OAuth). You will also be able to check the build results of previously triggered builds. More on this in a later section.
- Our Cloud Build Service creates an Apache Cordova project for iOS and/or Android and extracts the above-mentioned zip file into it.
- Build jobs are created, queued and executed.
- The resulting APK and/or IPA files are uploaded to Mobile Services. The file URL is provided as QR code for over-the-air installation onto a device, or as download URL.
In case you want to know the exact content of the zip file being sent from SAP Web IDE to Mobile Services, you can use your browser’s development tools. In this example I’ll use the Chrome browser’s DevTools. When you select the Network tab, you will be able to see what XHR requests are being sent. Find the request called ‘file’. Double click on this entry, and the file will be saved into your Downloads folder. You could use this zip file as starting point for a Cordova project.
Extract the file.zip and you have the contents that will be used by the Cloud Build Service.
In case you are wondering why we are not using the export feature of SAP Web IDE Full-Stack: you can export the project, but the structure is that of a web app. For a Cordova app, you would have to manually move/merge files and folders. Although in theory this is possible, we will not take this route here.
Building the app locally
The easiest way to migrate to another development environment, is by downloading the complete Apache Cordova project as generated and built on our Cloud Build Service. For this, you need to enable an option in the Build Wizard called “Save XCode and or Android Studio projects”. When you build your project with this option enabled, our Cloud Build Service will archive the complete Cordova project structure as generated for building your app. We provide this option for troubleshooting purposes. The archive is uploaded to Mobile Services and a download URL is presented as part of the build results. Do remember to disable this option afterwards, as it takes more time to process.
When your build is done, you will see the Build Results dialog. Click on the “Download XCode project” to fetch the project. For the Android Studio project, there is a link on the Android tab. Take note that these archives are several hundreds of megabytes large, so depending on network bandwidth, the download can take a while.
Building the iOS app with XCode
Assuming you are using a Mac, extract the downloaded archive to a working folder.
In the folder cordova/platforms/ios you will find your project’s XCode workspace file. Open this in XCode. You can now run your app on the simulator or your iOS device. The only tool required to be installed here, is XCode.
Take note of the project structure in the below screenshot. When you run the app, the code in the ‘Staging’ folder will be used. This folder was created by the Cordova tooling and contains everything needed for execution on your device. However, do not change any files here, unless you are making temporary changes for debugging [hint], as they will get overwritten once you execute a ‘cordova build’ or ‘cordova prepare’ (requires Cordova to be installed).
Building the Android app with Android Studio
For Android app development I will be using a Mac, but you could do the same on a Windows machine.
Extract the downloaded archive to a working folder, open Android Studio and select ‘Import project (Gradle)’.
Locate the project in the folder platform/android and select ‘Open’. Take note that similar to the XCode project, the source files in platform/android can be overwritten by the Cordova CLI tools.
Wait a bit for the import (and build!) to finish. Once this is done, you will be able to select the target device to run the app on. Take note that you probably have to upgrade the Gradle plugin. Android Studio will inform you about this.
The screenshot below shows the app running on the Android Emulator.
Build Stack on the Cloud Build Service
Your application was built using specific versions of tools and packages (e.g. specific versions of node.js, Cordova, android SDK, XCode, SAP Mobile SDK, etc.). You can find these details in the Mobile Services cockpit.
Open your SAP Cloud Platform (Neo) cockpit and navigate to Services. Select Mobile Services (part of the Extension Suite – Digital Experience category) and go to the service. Select Mobile Applications > Native/Hybrid and select the application you’ve built from SAP Web IDE Full-Stack.
In the Assigned Features, select Cloud Build.
Select the build job.
A build history list will be shown, for both Android and iOS, where applicable. Select the build version you’ve downloaded. I’ll pick the latest Android build as example here.
The overview page for this particular build provides quite some information and links. When you scroll further down, you will see which Cordova and Kapsel plugins were added to the project. And at the bottom of the page, you will find the build logs which includes a ‘Software Inventory’ structure. This list tells you which build stack was used for building your app on our Cloud Build Service, and the build options you’ve selected.
Using Cordova CLI tooling
As mentioned, building the downloaded project can easily be done using XCode and Android Studio. However, once you want to make more changes related to the Cordova project, you’ll need to use the Cordova CLI tools. In the screenshot above you can see that for building the app, Cordova CLI version 9.0.0 was used. To install this locally, you’ll first need to install Node.js. The version of Node.js is not that critical.
Once Node.js is installed, open a terminal and enter the following command:
npm install -g email@example.com
I’m using version 9.0.0, since this is the version against which the Kapsel SDK was validated. You could try other versions, but you might run into compatibility issues.
Once Cordova is installed, you are able to make changes to the Cordova project and rebuild the application.
Moving your project into Git
You’ve probably noticed that the folders containing the XCode and Android projects contain a massive number of files. Should you move all of them into a Git repository? Not really, unless you want to keep track of everything that gets generated.
To avoid files and folders getting included in your Git repository, you can specify them in a file named .gitignore. What should we specify here? At least the following folders:
An easier way get the content for your gitignore file is to leverage a community-maintained service available at https://www.gitignore.io. Search for the following (where applicable): ‘ApacheCordova’, ‘node’, ‘MacOS’, ‘AndroidStudio’. This will generate a list of items to exclude from your Git repo.
Note: a few tweaks are needed here. Open the .gitignore file and check whether there is an entry for ‘Icon’. Remove that, as we’ll need the icons. Add an entry for ‘compile.txt’.
The ‘node_modules’ folder can be re-populated automatically by using node. The platforms folder can be re-generated using Cordova. The same holds for the ‘plugins’ folder. However, some of the plugins are coming from the SAP Kapsel SDK (part of the SAP Mobile SDK). More on this in the next section.
Take note that in the folder ‘www/resources’ there is a large set of UI5 library files, based on a specific version of UI5 (as selected in the SAP Web IDE Build Wizard). Feel free to exclude this folder if you want to further customize your local build.
Rebuilding the project from Git
Let’s assume we’ve cloned the previously created Git repositories somewhere and want to rebuild the app. Before we can do this, we need to make sure that Cordova can find the Kapsel SDK’s plugins, as they are not available in a public npm repository.
Building the Android app
For Android builds, you’ll need to have Java and Gradle installed.
Assuming you have downloaded and installed the Kapsel SDK and defined an environment variable to help locate it, you can use the following command to re-generate your project:
cordova platform add android --searchpath $KAPSEL_HOME/plugins/
And to build the project:
cordova build android
At this point you can use the cordova commands to run your app, or open the project in Android Studio, using the same method described before.
Building the iOS app
Recreating the iOS app is pretty straightforward, provided you have installed Node, Cordova, the Kapsel SDK and XCode.
cordova platform add ios --searchpath $KAPSEL_HOME/plugins/
And to build the project:
cordova build ios
At this point you can use the cordova commands to run your app, or open the project in XCode, using the same method described above.
Now that you have moved your project out of SAP Web IDE Full-Stack, you might be missing features that made the whole developer experience more convenient.
Signing your apps was never an easy topic, especially for iOS. Using XCode, Apple does make it easier. More information is available here.
For your Android apps, Google is also providing tools in Android Studio and the Android SDK. More information is available here.
Some of our users have been relying on the QR codes generated by our tooling to distribute mobile apps. We’ve provided this as a convenience for developers to quickly load and test their apps. This feature was never intended to be used for distribution of the apps within your company. You are advised to use an MDM service for distribution.
For iOS apps, you can use Apple’s Testflight service. Google is providing a similar service with Google Play Console. There are plenty of third party services available that offer similar capabilities. Please do a search on “TestFlight alternatives” to find out more.
There are also ways to make use of (cloud or on-premise) storage services to help distribute your apps. I am not going to recommend any third party services here. Please do a search on “install APK IPA ota”.
Adding Cordova plugins
Once you have installed the Cordova tooling, it is quite easy to add plugins to your project via the command line tools. More information is in the Apache Cordova CLI documentation.
To browse for publicly available plugins, you can use the online plugin search tool provided by Apache Cordova.
Since you have most of the code already managed in Git, it should be quite straightforward to set up a Continuous Integration environment. If you want to learn more about this, please check these blog posts by Michael Jess : “Continuous Integration (CI) Best Practices with SAP: Fiori Hybrid Apps with SAP Mobile Platform SDK” and “Continuous Integration (CI) Best Practices with SAP: Custom Fiori client“.
With Hybrid Application Toolkit we have provided web application developers a simplified workflow and developer experience to create hybrid mobile apps from SAP Web IDE Full-Stack. We have provided this as a way to lower the learning curve for mobile development.
If you want to have more control on the build process, you’ll need to migrate your project out of SAP Web IDE Full-Stack. With the steps described in this blog, you will be able to do this and take your projects to the next level.