Skip to Content

Back to Getting Started With Kapsel

SAP Web IDE, Fiori Mobile and the Hybrid Application Toolkit(HAT)

The SAP Web IDE provides a browser based integrated development environment(IDE) for creating SAPUI5 web based applications that additionally can be extended to support hybrid apps through Fiori Mobile and the Hybrid Application Toolkit(HAT).

Hybrid applications display their UI with HTML but enable access to native functionality such as accessing the device’s contacts or scanning a barcode through a JavaScript API that each plugin provides. This enables the same application to run on Android, iOS and Windows with no or minimal code changes.

This blog post will demonstrate how to create a SAPUI5 OData based application using the SAP Web IDE and then deploy it as a hybrid app using Fiori Mobile and the HAT.

SAP Web IDE
Fiori Mobile (Cloud Builds)
Hybrid Application Toolkit(HAT) and the Companion App
Enhance the app with a Barcode Scanner
Hybrid Application Toolkit(HAT) and Local Builds
Offline Enabling the Application
Alternate Method of Offline Enabling the Application
Updating a Deployed Hybrid App with the AppUpdate plugin (Deploy to CP mobile services)

 

SAP Web IDE

Some additional tutorials on the SAP Web IDE at SAP Tutorial Navigator are listed below.
Sign up for a free SAP Cloud Platform account
Enable the Web IDE in the SAP Cloud Platform
Create a Destination in SAP Cloud Platform

Note there are a series of videos included in the Learning Center area shown below of the Web IDE.

This section will demonstrate how to create and run a web application using the SAP Web IDE. This example will use the OData service that is included in Mobile Service for Development and Operations.

  • Open the Development and Operations cockpit.

    Under Developer the sample OData service is available.
    Note, you may need to press the button  to reset the data to the initial state if you are seeing no data or are seeing data with mixed languages.This OData service can be accessed by the following URL after correcting the XXXXXXX values.
    https://hcpms-XXXXXXXtrial.hanatrial.ondemand.com/SampleServices/ESPM.svc
    This OData service is useful as it provides each user with their own OData service whose values can be updated and easily reset.
  • Next, create a destination to this OData service in the SAP Cloud Platform Cockpit.
  • Open the SAP Web IDE by clicking on the following link.https://account.hanatrial.ondemand.com/
    Navigate to Services and the SAP Web IDE. Enable it if it is not already enabled.  Note, that there is a new Web IDE available named Multi-Cloud Version.  This blog post currently uses the older SAP Web IDE.
    Click on Open SAP Web IDE.
  • In the SAP Web IDE, under Tools, Preferences enable the below plugins.

    and
  • Create a project from template via the File, New, Project from Template menu. Select SAP Fiori Worklist Application.

    Specify the project name to be Productlist.
    Select the Data Connection as shown below.
    Specify the application settings and bindings as shown below.
    Run the application.
    Note a few minor changes were made to the labels as described below.
  • A few minor tweaks can be made to the application.
    • Modify the i18n.properties file and tweak some of the names to be more descriptive.
      worklistViewTitle=Products
      worklistTableTitleCount=Products Found ({0})
      tableNameColumnTitle=Product
      tableUnitNumberColumnTitle=Price
      objectTitle=Product Details
    • Optionally modify Component.js below the this.setModel call and add the below code which will cause the OData requests to be made individually rather than as batch requests.
      this.getModel().setUseBatch(false);
    • Modify Object.view.xml and change the ObjectHeader to display different content.
      <ObjectHeader
          id="objectHeader"
          title="{LongDescription}"
          number="{
              path: 'Weight',
              formatter: '.formatter.numberUnit'
          }"
          numberUnit="{WeightUnit}">
      </ObjectHeader>
  • Note, when the HAT plugin is enabled, an additional setting appears when running the app as shown below.

    Enabling this will include the JavaScript files added by Cordova plugins enabling additional mobile qualities such as being able to scan a barcode.

Fiori Mobile (Cloud Builds)

This section will demonstrate how the previous application can be packaged as a hybrid application and will use the Fiori Mobile build service to build the application.

The following are some related links on the topic.
SAP Fiori Demo Cloud takes on a mobile focus
What’s new in the SAP Web IDE Hybrid App Toolkit, 1703
How to use SAP HCP, mobile service for SAP Fiori
Mobile Service for SAP Fiori

The Fiori mobile service developer experience has arrived!

The Fiori Mobile Service has a link to Go to Admin Console, which has the following Getting Started link.

For Fiori Mobile to package the application as a hybrid app it must first be deployed to the SAP Cloud Portal.

  • In the SAP Cloud Platform Cockpit enable the following two services.

  • Click on the Portal service tile then click on Go to Service.
    Click on Create New Site choose SAP Fiori Launchpad as the template.
    Select the site and make sure it is published and set to be the default.
  • Optionally, right click on the previously created project and choose Fiori Mobile, Select Cordova Plugins and optionally add any additional plugins desired.

  • Right click on the Productlist project and choose Deploy, SAP Cloud Platform and register it to the SAP Fiori Launchpad.



  • Here is the app running in the SAP Fiori Launchpad. The URL can also be found in the Portal Service cockpit.
  • Right click on the Productlist project and choose Fiori Mobile, Build, Build Packaged App. When using the SAP Cloud Platform trial, a maximum of two apps can be created. The following instructions describe how to delete a previously deployed Fiori Mobile app.

    Note, the Companion App is covered in the next section but basically adds a refresh button in the top right that when pressed will reload the HTML resources of the app. In the Companion App the HTML and JavaScript files are not included in the app but are loaded from the SAP Fiori Launchpad enabling changes to be tested by simply reloading the page rather than requiring a rebuild and redeploy.
    Building a packaged app creates an apk(Android) or ipa(iOS).

    The Packaging tab chooses between having a single app or an app that has a launchpad with a tile for each app. Note you need to double click on an available app to move it to the Selected Applications table.
    The below screenshot is an example of multiple tiles being shown in a launchpad.
    Push notification support can be added to the application.
    The console shows the build process which is happening in the SAP Fiori Mobile clould build service.
    Once the build is complete the apk file can be downloaded by clicking on the Productlist.apk link.
    Note, the above screen can be reopened by choosing the Show Build Results menu item.
    After the apk file has been downloaded it can be installed onto an Android device with the below command.

    adb install Productlist.apk

    The QR code contains the below URL which shows the app on Mobile Place. The app can also be installed directly by pressing the INSTALL button.

    Building a Packaged app will also create a non-editable application for the app in the Development and Operations cockpit.

    This app configuration can be edited (or deleted) in the Fiori Mobile Admin Console. Note the delete button becomes enabled after deleting any entries shown below that are not in a Ready to build status.

  • Here is the app that is deployed to the device.




    Note this app is a packaged app and contains many of the same plugins that are included in the SAP Fiori Client which provide a passcode screen and enable the app to access native functionality through JavaScript calls.
    The passcode policy can be set in the Mobile Secure Admin Console as shown below.
    The screen shot below shows the WebInspector invoking the device plugin to find information about the Android device the app is being run on.

    Note also that all the files that make up the app are loaded from file://.
  • After following the above steps, a hybrid application has been built in the cloud and then installed on an mobile device using the Fiori Mobile build service. The deployed app can be a single app or it can display a local launchpad allowing access to multiple Fiori apps. The app can also make use of mobile qualities such as receiving push notifications or many of the other mobile qualities available via Cordova and Kapsel plugins. For additional details on push see Easily add Push Notifications to your mobilised Fiori app with Fiori Mobile DevX

Hybrid Application Toolkit(HAT) and the Companion App

The following instructions describe how to install the HAT components onto your computer that enable the deployment to the companion app or as discussed in the next section how to create and build a local project.


The companion app shown above is a prebuilt app that includes common Cordova and Kapsel plugins and can be configured to load a URL. When a hybrid app is run in the companion app, changes can be made in the Web IDE and then seen in the companion app by simply double tapping and pressing the refresh button. It can be built locally which enables the debugging of JavaScript through the Web Inspector or a non debuggable version is available at the app stores.
SAP Hybrid App Tool Companion at Google Play Store
SAP Hybrid App Tool Companion at Apple iTunes

The following are some additional links on the topic.
Installing and Setting Up HAT
How to install Hybrid Application Toolkit on Windows
How to use Hybrid Application Toolkit (HAT) and test the apps

    • Download the installer from store.sap.com.
    • Run SAP_HAT_local-1.25.3\setup.cmd

      The above screen checks the versions of the various required components.
      Each version of HAT is tested to work with specific versions of Node, Cordova and the Kapsel SDK. The version of node, Cordova and Kapsel can be determined by running the following commands.

      node -v
      cordova -v
      kapsel -v

      The check for the node version occurs in SAP_HAT_local_1_25_3\setup\scripts\win\check_env.cmd

      The following are some commands to uninstall and install a specific Cordova version.

      npm uninstall -g cordova
      npm cache clean
      npm install -g cordova@6.3.1
      

      Finally, the version of Kapsel can be determined by the following items.

      echo %KAPSEL_HOME%
      C:\SAP\MobileSDK3\KapselSDK
      

      The Kapsel command line interface (CLI) is installed with the following command.

      cd %KAPSEL_HOME%\cli
      npm install -g
      

       

    • The following screen downloads a copy of SAPUI5 that will be included in applications that use the local build and configures the HAT Connector that enables communication between the Web IDE and the build environment installed on your computer.

      Note that on step 3, the URL for the Web IDE needs to be provided.
    • Finally the Companion App is built which is an application that contains many of the Cordova and Kapsel plugins commonly used in a hybrid app. Applications can be deployed to this pre-built companion app reducing the time needed to build and deploy a Cordova app during development.
    • Once the HAT install completes, start the HAT Connector.
    • Enable the HAT Local Add-on and connect to the HAT Connector in the SAP Web IDE via the Tools, Preferences menu.

 

  • Modify the index.html file and change the setting frameOptions setting to be allow rather than trusted.
    For further details see Frame Options.
  • Run the application in the Companion App.

    Note, that the app being run in the Companion App is loaded over the internet rather than loading the HTML and JavaScript content locally from a file:// URL. This enables the development/deployment cycles to be quick as the APK file does not need to be rebuilt and reinstalled after making a change to the HTML or JavaScript of the application.
  • Note the companion app is a hybrid app and the list of plugins included in it can be seen as shown below.
    You may wish to remove the privacy screen plugin which on Android prevents screen mirroring with apps such as Vysor.

    cordova plugin remove cordova-plugin-privacyscreen

Enhance the app with a Barcode Scanner

This next section demonstrates a simple change to the application that adds the ability to scan a QR code and have the returned value be placed in the Search field. This change can be quickly applied and tested in the Companion app without having to rebuild and redeploy the application.

  • Edit Worklist.view.xml.
    After SearchField, add the following button.

    <content>
    	<Button id="barcodebutton" icon="sap-icon://bar-code" press="onBarcodeScan"></Button>
    </content>
  • Edit Worklist.controller.js and add the following method.
    onBarcodeScan: function() {
        var that = this;
        var code = "";
        if (!cordova.plugins.barcodeScanner) {
            sap.m.MessageBox.alert("Barcode scanning not supported");
            return;
        }
        cordova.plugins.barcodeScanner.scan(
            function(result) {
                code = result.text;
                that.getView().byId("searchField").setValue(code);
                var oTableSearchState = [];
                var sQuery = result.text;
                if (sQuery && sQuery.length > 0) {
                    oTableSearchState = [new Filter("Name", FilterOperator.Contains, sQuery)];
                }
                that._applySearch(oTableSearchState);
            },
            function(error) {
                sap.m.MessageBox.alert("Scan failed: " + error);
            }
        );
    },
  • Notice that the change can quickly be tested by double tapping in the Companion App and choosing the refresh button.

    Notice the barcode scanner button now appears to the right of the search field.
  • If the Refresh is failing, the following trick might help. In the Chrome Web Inspector (chrome://inspect), switch to the Network tab and disable the cache. Then select the Refresh menu again.

Hybrid Application Toolkit(HAT) and Local Builds

  • Right click on the Productlist project, choose Project Settings, Hybrid App Toolkit, Hybrid App Configuration (Local Add-on).
    Specify an App ID such as com.sap.productlist.
  • Under the Plugins section check the Logon Manager, Offline OData, Barcode Scanner and under Cordova select Network Connection.
    Select SAP Cloud Platform mobile services.
    Under Logon Options, the Logon screen can be further customized.
  • Under OData Endpoint, select SAP Cloud Platform mobile services.
  • In the Mobile Service for Development and Operations cockpit create a new application with an App ID of com.sap.productlist.
    Set the security configuration to be Basic.
    Set the Endpoint URL to be

    https://hcpms-p174XXXXtrial.hanatrial.ondemand.com/SampleServices/ESPM.svc

    Set the Proxy Type to be Internet
    Ensure the Rewrite mode is Rewrite URL (required for offline apps).
    Add an SSO Mechanism of type Basic.

  • Run the app.
    Note, the console shows the results of the build and deployment process but is truncated after a few screens of output. To see the complete log see C:\Temp\SAP_HAT_local_1_25_3\logs\command.log.

Offline Enabling the Application

Note, there is an issue using older versions of the Kapsel Offline plugin with Android X86 emulators. This is fixed in recent SP 14 PLs.

The following blog posts may also be of interest.
Creating Offline Application based on SAP Web IDE CRUD Master-Detail Template using Hybrid App Toolkit
Creating an offline app with the mobile service for SAP Fiori – Part 1
Approve Purchase Order Offline for Mobile
Getting Started with Kapsel – Part 10 — Offline OData(SP13+)

  • In Component.js, comment out the following line.
    //this.getModel().setUseBatch(false);
  • Modify the manifest.json.
    Add the following new section.

    "sap.mobile": {
        "_version": "1.1.0",
        "definingRequests": {
            "Products": {
                "dataSource": "mainService",
                "path": "/Products?$expand=StockDetails"
            }
        }
    },

    In the sap.app section add the below entry.

    "offline": true, 

  • Run the project on a device or emulator.

    Notice above that the device after the offline store has been initially created can be put in airplane mode and the product data is still available if the app is closed and reopened.
  • The following bits may be of interest for Kapsel developers.
    The following files do not appear in the SAP Web IDE but in the hybrid project.

    • www\mobile.json Contains the appID, serverHost, custom fields for the logon plugin etc as well as some HAT specific settings like proxy and serviceUrl.
    • www\hybrid\sap-mobile-hybrid.jsThe bootStrap method adds a function that is called by the deviceready event that reads mobile.json and loads hybridodata.js and logon.js
    • www\hybrid\kapsel\logon.js Contains methods to initialize and use the logon plugin.
    • www\hybrid\odata\hybridodata.js and offlineStore.js Contains methods to initialize and use the offline plugin.
  • At this point a hybrid project is created and the regular Cordova commands could be used to deploy the project.

    The project can also be recreated via the Prepare Hybrid Project menu item.

Alternate Method of Offline Enabling the Application

The following steps take the output from the Web IDE generated project and place it into a project created from the command line. Then some code is added to register the application with the SCPms server and open an offline store. After following these steps, you will have a better appreciation for what the HAT automates.

  • The following steps create a hybrid or Cordova project, add the Android platform and add the plugins.
    cordova create C:\Kapsel_Projects\ProductList2 com.sap.productlist2 ProductList2
    cd C:\Kapsel_Projects\ProductList2
    cordova -d platform add android
    cordova plugin add cordova-plugin-network-information
    cordova plugin add kapsel-plugin-barcodescanner --searchpath %KAPSEL_HOME%/plugins
    cordova plugin add kapsel-plugin-odata --searchpath %KAPSEL_HOME%/plugins
    cordova plugin add kapsel-plugin-logon --searchpath %KAPSEL_HOME%/plugins
    
  • Export the source code from the Web IDE.

    Place the contents of the webapp folder into the www folder.
  • Modify the index.html file to initialize the logon plugin and open the offline store before starting the app.
    Add the following include.

    <script type="text/javascript" charset="utf-8" src="cordova.js"></script>

    Then add the following code replacing the existing sap.ui.getCore().attachInit method.  Also update the serverHost, user and password values.

    document.addEventListener("deviceready", myInit, false);
    var appId = "com.sap.productlist"; 
    var applicationContext = null;
    var context = {
        "serverHost": "hcpms-p174XXXXXXtrial.hanatrial.ondemand.com",
        "https": true, 
        "serverPort": 443,
        "user": "dan",          
        "password": "mypwd",
        "custom": {
            "hiddenFields": ["farmId", "resourcePath", "securityConfig", "serverPort", "https"],
            "disablePasscode": true
        }
    }
    
    function myInit() {
        console.log("In deviceready/myInit");
        var oCore = sap.ui.getCore();
        oCore.attachInit(myRegister);
    }
    
    function myRegister() {
        console.log("In register");
    
        var registerSuccessCallback = function(result) {
            console.log("In registerSuccessCallback");
            applicationContext = result;
            openStore();
        };
    
        var registerErrorCallback = function(error) {
            console.log("In registerErrorCallback");    
            console.log("An error occurred:  " + JSON.stringify(error));
            navigator.app.exitApp();
        };
    
        sap.Logon.init(registerSuccessCallback, registerErrorCallback, appId, context);
    }
    
    function openStore() {
        console.log("In openStore");
        jQuery.sap.require("sap.ui.thirdparty.datajs");  //Required when using SAPUI5 and the Kapsel Offline Store
        var properties = {
            "name": "ProductsOfflineStore",
            "host": applicationContext.registrationContext.serverHost,
            "port": applicationContext.registrationContext.serverPort,
            "https": applicationContext.registrationContext.https,
            "serviceRoot" :  appId,
            
            "definingRequests" : {
                "ProductsDR" : "/Products?$expand=StockDetails"
            }
        };
            
        store = sap.OData.createOfflineStore(properties);
    
        var openStoreSuccessCallback = function() {
            console.log("In openStoreSuccessCallback");
                sap.OData.applyHttpClient();  //Offline OData calls can now be made against datajs.
                myAppStart();
            }
    
        var openStoreErrorCallback = function(error) {
            console.log("In openStoreErrorCallback");
            alert("An error occurred" + JSON.stringify(error)); 
        }
    
        store.open(openStoreSuccessCallback, openStoreErrorCallback);
    }
    
    
    function myAppStart() {
        sap.ui.require([
            "sap/m/Shell",
            "sap/ui/core/ComponentContainer"
        ], function (Shell, ComponentContainer) {
            // initialize the UI component
            new Shell({
                app: new ComponentContainer({
                    height : "100%",
                    name : "com.sap.products"
                })
            }).placeAt("content");
        });
    }
  • Modify the manifest.json file.
    Remove the following line.

    "sap-documentation": "heading"

    Modify the dataSources uri as shown below.

    "dataSources": {
        "mainService": {
            "uri": "https://hcpms-p17XXXXXXtrial.hanatrial.ondemand.com/com.sap.productlist/",
  • Try it out.
    cordova run android
    

Updating a Deployed Hybrid App with the AppUpdate plugin (Deploy to CP mobile services)

The AppUpdate plugin enables a deployed app that has registered with an SMP or SCPms server to receive updates to the HTML and JavaScript of the application. When the application starts it checks with the server if there are any updates and if there are, downloads them and then requests permission from the user to apply them.

For additional details of the App Update plugin see Getting Started with Kapsel – Part 3 — AppUpdate (SP13+).

  • The development version of the app contains a lot of extra SAPUI5 files in the project\hybrid\www\resources folder.
    We will reduce that amount by using the SAPUI5 library included in the Kapsel UI5 plugin which contains a smaller subset.

    • Create a zip file named sapui5-mobile-custom.zip containing the contents of the following folder.
      C:\SAP\MobileSDK3\KapselSDK\plugins\ui5\www\resources
    • Place that file in the following folder
      C:\Users\user_name\SAPHybrid
    • In the Web IDE, in project settings select Hybrid, and choose to use a custom build.
    • Choose release mode since the custom build does not contain all of the SAPUI5 debug libraries

     

  • Add the App Update plugin to the project and set the Hybrid Revision to be 0.
  • Deploy the app to the device or emulator.

    Notice the size of the resources folder is much smaller (32 MB vs 194 MB) and that the deployment to the device is much faster.
  • Make a change to the app that you wish to have updated on the deployed version of the app. For example, remove the barcode scanner button by deleting the barcodebutton in Worklist.view.xml.
  • Deploy a zip containing the www folder of the application to the SCPms server.
    Browse to the generated zip file and press the Deploy button.
    Note if the upload fails the HTML5.SocketReadTimeout setting can be increased on the mobileservices destination.
  • Navigate to the management cockpit for the Mobile Services server and deploy the change.
  • The next time the app starts, it will check with the Mobile Services server and send down the updates.

Back to Getting Started With Kapsel

To report this post you need to login first.

3 Comments

You must be Logged on to comment or reply to a post.

  1. Andreas Pöschl

    Hi Daniel,

    thank you for this great introduction to Web IDE in combination with HAT.

    I have a question about something that is still unclear to me. In my scenario I would like to use Web IDE with HAT and an SAP Mobile Platform 3.0. So far everything works, but I’m searching for a best practice for handling the destination urls of the odata service.

    From Web IDE I’m using a the Cloud Platform Connector to connect an ABAP backend.

    In your example you wrote to change the url in the manifest.json to something like https://<mobile_server&gt;:<port>/<application_name>
    but when I use the absolute url to my mobile platform and the corresponding service, Web IDE is no longer able to connect, as the mobile platform is in my local network and not reachable for Web IDE. Therefore I’m not able to run my application for testing in Web IDE.

    Is there any other way (something like a best practice), as constantly switching the uri in the manifest.json?

    I hope I wrote my question clearly enough 🙂

    Thank you!
    Andreas

    (0) 
  2. Diego Borja

    Hi Daniel,

    Do you know if there is any documentation available on how to perform flush and refresh for offline applications completely built on the cloud using Fiori Mobile?

    Also, I’ve only found this document regarding the sap.mobile namespace for the manifest.json file.

    https://help.sap.com/viewer/0ce0b8c56fa74dd897fffda8407e8272/7.5.6/en-US/7701636d088147569d99b4f08d418bd9.html

    But a lot of the possible parameters you can use as shown in many different blogs are not listed there. For instance I saw in one of the blogs you referenced for the offline section, that includes “stores” as an element in the json file.

    Thanks in advance for your help,

    Diego

     

    (0) 

Leave a Reply