Technical Articles

July 13, 2015 7 minute read

How to install Hybrid Application Toolkit (HAT) on Windows (part 1 of 3)

* This blog post is outdated. We have reached end-of-maintenance for HAT local add-on. You can no longer download this tool from the SAP Store. We no longer support this tool. You are strongly advised to make use of our Cloud Build Service provided through Mobile Services. More information can be found here: https://blogs.sap.com/2018/08/16/announcing-end-of-maintenance-for-hybrid-app-toolkit-local-add-on-local-builds-only *

Introduction

Today I’m gonna show you how to install the Hybrid Application Toolkit (HAT) on a Windows machine. Hybrid Application Toolkit (from now on simply HAT) is the tool which allows you to deploy SAP Hybrid applications on mobile devices. Hybrid application (also known as Kapsel applications) can be created by using SAP Web IDE and then deployed on mobile devices with this tool. In order to get more information on this tool and on SAP Web IDE I suggest you to give a look to this page (SAP Web IDE – Overview). Here you can find a lot of other useful resources for SAPUI5 application development.

This blog is just for Windows: if you want to know how to do the same on Mac please also follow this blog: How to install Hybrid Application Toolkit (HAT) on Mac.

HAT installation is NodeJS based: it guides you through all the steps for a successful result. However in order to avoid the needing to start the installation and then going back and forth installing the missing components, with this blog, I’m giving you a sort of good starting point so that when you start the HAT installation it will be as smooth as possible and you will be no longer required to leave the installation process for installing other mandatory software.

This blog has been split in 3 parts:

Link	Content
Part1	Install JDK, Android SDK and Apache ANT
Part2	Install NodeJS, Cordova, Kapsel, Git, Plugman and configure environment variables
Part3	Install HAT and test it

Prerequisites

In this blog I would like to start with a very blank Windows machine, so I’m gonna show you how to install all the needed tools for SAPUI5 application development. We will go through the installation of the following components:

Java JDK 8
Android SDK rel. 24.4.1
Apache Ant 1.9.6
SAP Kapsel Plugin SP10 PL1
Node.JS v.0.12.7
Git client
Hybrid Application Toolkit 1.9.7
Cordova 5.2.0
Plugman

The prerequisites here are nothing more then the following ones:

Windows 8.1 64bit
Google Chrome browser
An account on the SAP HANA Trial Landscape accessible by this link (SAP HANA Cloud Platform)

Further recommendations:

UAC must be set as by default

All the commands in the Terminal window must be executed WITHOUT administrator’s rights, otherwise you won’t be able to perform HAT setup.

Getting started

As I said, for your comfort, I will start from the very beginning, so with a very blank machine. I’ve split the complete how-to-guide over 3 parts. This is the complete list of the steps we will go through:

Part 1:

Install Java Development Kit (JDK)
Install Android SDK
Install Apache Ant

Part 2:

Download and install SAP Kapsel Plugin
Configure some environment variables (JAVA_HOME, ANT_HOME, KAPSEL_HOME, ANDROID_HOME and PATH)
Install a GIT client
Install Node.js
Install Kapsel CLI
Install Cordova
Install Plugman

Part 3:

Download HAT
Setup HAT
Run HAT and test its connectivity with SAP Web IDE
Deploy your first Kapsel app to local Hybrid App Toolkit

So, let’s focus here just on the first part!

Install Java Development Kit (JDK)

Java Development Kit is required by the Android SDK, so as first step we need to install this component. In this guide I’m using JDK 8, but 7 is fine as well.

1) Go to JDK download page “Java SE Development Kit 8 – Downloads“, accept the license agreement and download the JDK according to your Windows platform (32 or 64 bit)

2) Once the download is finished double click on the downloaded file to start the installation

3) Leave all by default and click Next at every step. When you reach the step where you can change the installation path, take note of this path because it will be required later when you are going to configure the JAVA_HOME system variable

4) When the installation finishes, you can check that all worked fine by opening a Terminal window and typing the command “java -version“. You should get something like this

Install Android SDK

For the Android SDK you can go to the following URL: Download Android Studio and SDK Tools | Android DevelopersNow you have two possibilities:

download the complete Android Studio suite which contains in bundle the Android SDK
download the stand-alone version of SDK without the Android Studio.

In this guide, I’ll follow the second approach, but the first one is fine as well: just write down the path where the bundled SDK tool is installed.

1) Go to the download URL and click on Other Download Options

2) Choose the recommended download option (for Windows), which is the one by the installer

3) Once the download is finished, double click on the downloaded file to start the installation

4) Accept the UAC request by clicking on Yes

5) Click on Next on the Welcome screen

6) Click on Next on the screen where the current installed Java version is verified

7) Choose if you want to install this just for you or for everyone and click on Next

8) Take note of the installation path (it will be required later) and click on Next

9) Click on Install

10) When the installation is completed click on Next

11) Choose to Start the SDK Manager and click on Finish

12) The SDK manager starts: if you get an error like this, it’s because most probably you are behind a firewall and you need to configure your proxy settings; so click on Close and read the APPENDIX to this section named Configure proxy for Android SDK Manager.

If you have no “Failed to fetch” error, you can continue with next step

13) Now you need to specify the packages you want to install. For this H2G we will choose to install Android 5.1.1 (API 22). This because, at moment, this is the highest supported Android version by the latest Kapsel plugin. You can install newer versions of Android, but the installation process will always check and require the presence of API 22 to work. In my case these are the packages I’m going to install:

Tools

Android SDK Tools (it comes already installed)

Android SDK Platform-Tools

Android SDK Build-Tools

Android 5.1.1 (API 22)

SDK Platform

ARM EABI v7a System Image

Android 4.4.2 (API 19)

SDK Platform

ARM EABI v7a System Image

Extras

Android Support Repository

Android Support Library

Google Play Services

Google Repository

Google USB Driver

I’ve just 11 packages to install. Click on the Install 11 packages button

NOTE: After the installation of Google USB Driver, in order to have it fully working with your mobile device, you have to follow the instructions reported at this link: OEM USB Drivers | Android Developers

14) Select the root Android SDK License, click on Accept License and then on Install

15) The installation of the required packages starts. It might require some time depending on your network speed, so be patient. If you get an error saying “Stopping ADB server failed (code -1)” at the beginning of the installation process, don’t worry, it’s normal!

16) When the installation finishes, you might need to restart your Android SDK manager

17) We need to create an Android Virtual Device(AVD) in order to test our Android applications. Of course, this shouldn’t be mandatory, because I could test my applications just by using my Android phone, but at moment the HAT setup looks for it, so we need to configure it. In the future probably this won’t be a mandatory step.

In order to create your first AVD, select Tools –> Manage AVDs, click on the Device Definitions tab, select a suitable device for your Android emulator (i.e. Nexus 4) and click on Create AVD

18) Specify the required parameters (this is just an example and click on OK)

19) When the summary screen appears click on OK

20) You should be able to get your emulator in the list

21) You can close the tool.

NOTE: Using the Android Emulator with this kind of ARM processor might result very slow. I suggest you to use (if possible) Virtual Machine Acceleration as explained here. In this way you can have a better emulated device for your development.

Install Apache Ant

For the Apache Ant software installation, you can download it from Apache Ant – Binary Distributions

The latest version at the time I’m writing this guide is 1.9.6.

1) Download this version

2) Select the downloaded zip file, right click on it and choose Extract All

3) Just put the extracted folder on your C: drive’s root. A subfolder will be automatically created

4) Rename the new folder simply with “apache-ant“

Good job so far! Please continue with the part 2 of this H2G!

APPENDIX

Configure proxy for Android SDK Manager

1) Click on Tools –> Options

2) Enter your proxy settings (i.e. for SAP Network proxy:8080)

3) Close SDK Manager and reload it by double clicking on the SDK Manager executable

29 Comments

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

Georgi Nushev

November 17, 2015 at 5:23 pm

Hi Simmaco,

thanks for the great blog, but could you please post the exact version prerequisites, because here you are installing all the latest components, but I do have most of them already installed on my computer. Do I need Windows 8.1 machine, or it is also possible to install it on Windows 7?

Regards,

Georgi

SIMMACO FERRIERO

Blog Post Author

November 18, 2015 at 8:13 am

Hi Georgi,

Windows 7 is also fine! You can find all the prerequisites in the installation guide here

SAP Web IDE Hybrid App Toolkit Add-on

The installation process, however, which is web based, will guide you through the installation of all the missing or old components you have on your machine.

You can start the installation and do a preliminary check to see what is missing and what is not up to date.

Regards,

Simmaco

Georgi Nushev

November 18, 2015 at 8:39 am

Hi Simmaco and thanks for your replay,

could you also please check my discussion with an issue I got during installation:

Re: Problem installing HAT, bower cannot be installed

Regards,

Georgi

Georgi Nushev

November 18, 2015 at 12:24 pm

Hi Simmaco,

i fixed the above issue, but now in the web based installation check, I get issue in the Cordova Build Android Project with Error: "please install android target : "andoird-22".

For Andoird 5.1.1(API 22), i do have installed the SDK Platform, I also have installed the latest Andoird SDK Platform and Build-tools.

Here is a screen shot from the issue:

Georgi Nushev

November 19, 2015 at 2:03 pm

Thanks to Simmaco, we solved the above issue.

For the Android version, somehow I had 2 Android SDK installed, so the path pointed to the wrong one, so I just needed to add the right path.

Also if you had a older version of the KapselSDK installed, you need to type in the cmd :

npm -g install C:\KapselSDK\cli (or you installation path) to install the new version.

You could check the installed version by running: kapsel -v

Regards,

Georgi

IBsolution Bulgaria

Former Member

January 6, 2016 at 3:07 pm

Hello Georgi,

I have the same problem.

What do you mean that you just had to add the right path? My ANDROID_HOME path is correct.

Regards,

Andreea

Dimitri Gurewitsch

November 20, 2015 at 10:11 am

Why do we need some local tools while developing in WEB IDE??? Are there any plans privide cordova build in the cloud?

SIMMACO FERRIERO

Blog Post Author

November 20, 2015 at 10:24 am

Hi Dimitri,

at the moment we need this local tool. Very soon there will be Cloud service for this. You can get a sneak preview of it by taking a look to the SAP TechEd 2015 Barcelona Keynote video you can find here:

SAP Executive Keynote: Björn Goerke, Barcelona 2015 | SAP TechEd Online</title></head><body> …

Starting from the minute 34 you can see it.

Regards,

Simmaco

Dimitri Gurewitsch

November 20, 2015 at 10:33 am

fine! Thanks a lot 🙂

Former Member

November 30, 2015 at 11:52 pm

Hello Simmaco,

I installed HAT as described in this and the preceding tutorials.

Then I used web IDE to convert a SAP UI5 app to a Kapsel app. The app is very simple it displays a dropbox and displays some text depending on the selected entry on the dropbox. The app does not use ODATA.

I ran the app as Web Application in WEB-IDE. It works there.

Then I deployed the app on the device. I did not select any plugin.

I can see that the app is available in the SAPHybrid directory on my local pc. When I use web-ide to run the app on an Emulator I see in the WEB-IDE console that the apk file is built and the app is installed successfully on the emulator. However when I click on the icon for the app in the emulator a white screen is displayed and then the following error message is displayed in the emulator: Application Error The connection to the server was unsucessful. (file:///android_asset/www/index.html).
In the WEB-IDE console I can see the following entries:

12:17:33 AM (hybrid-toolkit) Unlocking screen...

12:17:33 AM (hybrid-toolkit) deploying...

12:17:34 AM (hybrid-toolkit) Launching application...

12:17:43 AM (hybrid-toolkit) LAUNCH SUCCESS

12:17:43 AM (hybrid-toolkit) emulate android process exited normally

Can you please tell me how I can debug the application in the emulator in order to find the reason for the application error? (As mentioned before the kapsel application works if you run it as an web application in WEB-IDE)

Kind regards,

Matthias

SIMMACO FERRIERO

Blog Post Author

December 1, 2015 at 7:11 am

Hi Matthias,

in order to debug the app you need the Android Device Monitor.

If you have installed all correctly, you should be able to call it by typing "monitor" in the Command prompt window.

Regards,

Simmaco

Former Member

December 5, 2015 at 12:50 am

Hi Simmaco,

thank you for your help. When I run the app on the on the emulator I can see the following error message in the emulator screen:

Application Error

The connection to the server was unsuccessful. (file:///android_asset/www/index.html)

In the Android Device Monitor I can see the following log entries:

E/CordovaWebViewImpl(1161): CordovaWebView: TIMEOUT ERROR!

12-04 18:27:49.254: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/core/library-preload.json

12-04 18:27:49.714: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/m/library-preload.json

12-04 18:27:58.574: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/parentapp/manifest.json

12-04 18:27:59.214: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/core/themes/sap_bluecrystal/library-parameters.json

12-04 18:27:59.264: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/m/themes/sap_bluecrystal/library-parameters.json

12-04 18:27:59.554: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/webapp/Component-preload.js

12-04 18:28:00.364: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/layout/library-preload.json

12-04 18:28:00.634: E/AndroidProtocolHandler(1161): Unable to open asset URL: file:///android_asset/www/resources/sap/ui/layout/themes/sap_bluecrystal/library-parameters.json

I have to mention that I converted a UI5 app to a Kapsel app automatically in web-ide.

When I start the Kapsel app it is working in web-ide. The app is quite simple it contains just a field with a combobox and a form for the text output. The app neither uses ODATA service nor a kapsel-plugin/cordova-plugin. Therefore I did not specify an ODATA service and I did not specify any plugin when deploying the app to device.

I checked the project folder on my local PC C:\Users\...\www\resources: It does not contain the files which are mentioned in the error messages (e. g. library-preload.json).

As far as I understand are the missing files system files. From where can I get the missing files and how can I include the missing files into the deploy process of the HAT in order to solve the errors described above?

Best regards,

Matthias

SIMMACO FERRIERO

Blog Post Author

December 5, 2015 at 3:45 pm

Hi Matthias,

are you able to send me in some way your application? You can export it from SAP Web IDE and send it to me.

Regards,

Simmaco

Former Member

December 10, 2015 at 10:34 pm

Hi Simmaco,

now I have a question regarding the ui5 version which is used by HAT to create an Android app. I had a look at the folder which contains the android app generated by HAT:

C:\Users\SAPHybrid\<name of my application>\hybrid\platforms\android\assets\www\resources

There the file sap-ui-core.js is located.

When I open that file I can see in the comment

* UI development toolkit for HTML5 (OpenUI5)

* Licensed under the Apache License, Version 2.0 - see LICENSE.txt.

I would like to distribute my app according to the regulations specified in the apache licence version 2.0. Therefore I have the following questions:

a) Does the android app consist only of components covered by apache licence version 2.0?

b) Does the app contain also sap components which are not covered by that licence (e. g. sap components for which I have to buy a licence in order to be allowed to distribute the app)?

Thanks for your help,

Matthias

Former Member

December 20, 2015 at 8:03 pm

Hi Simmaco,

I developed a kapsel app and I can run that app on an emulator.

However when I select in Web IDE the index.html in my app and then select right mouse button and select 'Run' - 'Run on' - 'Android Device' the following popup appears:

'Select a Signing Key for Android Release Builds'

In the popup I select the radio button for 'Test Key' and press the 'OK' button.

Then another popup appears saying 'WARNING: No device found! Try to use emulator.

However an Android Device (Samsung Galaxy S2 mobile phone) is connected to the PC via USB. I downloaded the Samsung USB driver and installed it on the PC.

From the windows explorer I can access the S2 mobile phone which is connected to the PC via USB. Therefore I assume that the USB connection between PC and S2 mobile phone is available.

However when I go to WEB IDE and try to run the app on an Android Device I get the warning: No device found (as described above).

Did you encounter a similar problem? Any help would be appreciated.

Thank you and best regards,

Matthias

SIMMACO FERRIERO

Blog Post Author

December 22, 2015 at 9:51 am

Hi Matthias,

maybe it would be better if you could ask these kind of questions by opening a new Discussion marked as a Question with your issue. It will get better visibility and it is also the proper way to proceed. However, regarding your problem I never experienced such kind of thing and I've also tried with a couple of Android devices. Have you tried with another one? Did you check if the Google USB Driver is properly installed and configured as described here OEM USB Drivers | Android Developers ?

Regards,

Simmaco

Former Member

February 29, 2016 at 5:48 pm

Hi,

Thank you very much for your valuable guide.

I'm almost done. But I stuck up at Level 3 "Build Hybrid Companion App" -> "Build the companion app" step.

Please check the below screenshot and help me out.

Former Member

May 17, 2016 at 3:53 pm

Hi,

I have a doubt, I have created an app which consists of charts(i.e vizframe charts), it runs on the web perfectly, but when I tried it running on android phone after converting it to .apk, it didn't recognize viz libraries. So, is the fault on my side or is it not supported?

thanks,

Sanjo Thomas

SIMMACO FERRIERO

Blog Post Author

May 18, 2016 at 6:55 am

Sanjo,

Viz is supported. Do you mind to share the project or give me more information about the error that you can capture in the background?

You can write me in private.

Regards,

Simmaco

Former Member

May 18, 2016 at 7:15 am

Yes sure,please follow me so that I could send direct message. Actually it isn't identifying the resources/sap/viz/library.js and resources/ui/thirdparty/d3.js. Help me out

Daniel Rosenbaum

August 10, 2016 at 3:01 pm

First of all, thank you Simmaco Ferriero for this very detailed how-to-guide! That is some excellent and useful work!

When I went through the steps, I have found some minor mistakes and some outdated stuff and I thought I might share these issues for other people who are completing the installation of HAT:

Part 2, Step "Download and install SAP Kapsel Plugin":
- There is a small directory change. The new one "\modules\KapselFramework\smp-plugins-dist" is equivalent to "\modules\KapselSDK" in the guide.
Part 2, Step "Install Node.js":
- Version 5.4.1 is required (already mentioned here: https://help.hana.ondemand.com/webide_hat/frameset.htm?d2865598e67f4ddabc79e5943352b0a1.html ).
- Go to: https://nodejs.org -> "Downloads" -> "Previous Releases" -> "5.4.1 Downloads".
Part 2, Step "Install Apache Cordova 5.2.0":
- Version 6.0.0 is required, so just use the command: npm install -g cordova@6.0.0
Part 2, Appendix:
- In all descriptions of the proxy settings there is a small typo (double colon in proxy address). The right way is: <protocol>://<proxyhost>:<proxyport>
Part 3, Step "Run HAT and test its connectivity with SAP Web IDE":
- In the Web IDE you have to activate the "Hybrid App Toolkit" at first in "Preferences -> Plugins"

As you can see, these are mostly minor remarks, but the newer versions of Node.js and Cordova were inevitable during my installation.

I hope this will be of use to someone 🙂

Best regards

Daniel

SIMMACO FERRIERO

Blog Post Author

August 11, 2016 at 7:21 am

Thanks! I'll try to update my blog taking your suggestions into account.

Regards,

Simmaco

Vladislav Volodin

November 9, 2017 at 12:53 pm

Do you know why node.js is still 5.4.1? Is there a chance to use 8.x.x?

Georgi Nushev

August 11, 2016 at 6:23 am

Hi Simmaco,

I know there were some plans about the HAT as a Cloud version?

Is there any update on that?

Regards,

Georgi

SIMMACO FERRIERO

Blog Post Author

August 11, 2016 at 7:19 am

Georgi,

unfortunately I have no news regarding this. Probably we still need to wait.

Regards,

Simmaco

Former Member

October 7, 2016 at 8:54 am

Hi Simmaco,

I was able to install HAT successfully following the blog However, when I deploy an app , I see the below error on the emulator:

The connection to the server was unsuccessful (file:///android_asset/www/main.html)

Cordova Version - 6.3.1

Kapsel - 3.13.0

SMPSDK - 3.0.13.0

Regards

Vidya

SIMMACO FERRIERO

Blog Post Author

October 7, 2016 at 9:03 am

Vidya,

make sure you are able to navigate on internet from your Android device. Secondly, I'm not sure why you are having an error on "main.html". The first page to be loaded should be "index.html". Could you please try by creating a new very basic app from SAP Web IDE starting from the SAPUI5 Application template?

Regards,

Simmaco

Kartik Kuttarmare

February 9, 2018 at 10:06 am

Hello Simmaco,

while installig HAT 1.29

we are getting an error plz suggest.

ERROR:

cordova build android project error!

ANDROID_HOME=C:\Program Files (x86)\Android\android-sdk
JAVA_HOME=C:\Program Files\Java\jdk1.8.0_40
The system cannot find the path specified.
Error: cmd: Command failed with exit code 1

All path set properly

Ludo Noens

January 11, 2019 at 3:09 am

This blog post is outdated. We have reached end-of-maintenance for HAT local add-on. You can no longer download this tool from the SAP Store. We no longer support this tool. You are strongly advised to make use of our Cloud Build Service provided through Mobile Services. More information can be found here: https://blogs.sap.com/2018/08/16/announcing-end-of-maintenance-for-hybrid-app-toolkit-local-add-on-local-builds-only

Ludo Noens
Product Owner – Hybrid Application Toolkit

Technical Articles

How to install Hybrid Application Toolkit (HAT) on Windows (part 1 of 3)

Introduction

Prerequisites

Getting started

Install Java Development Kit (JDK)

Install Android SDK

Install Apache Ant

APPENDIX

Configure proxy for Android SDK Manager

Assigned Tags