SAP Mobile Platform 3.0

Getting Started with Kapsel

Overview

One type of mobile app that can be written using the SAP Mobile Platform 3.0 (SMP 3.0) is an HTML5 hybrid app or Kapsel app.  Apache Cordova is an open source project that provides a container which includes a browser that renders the UI of the application and a set of API's callable from JavaScript to access native device functionality such as the device's camera and contacts list.  The benefit of this is that the same UI code (HTML/CSS) and business logic code (JavaScript) can be deployed on multiple platforms such as iOS and Android without code modifications.  The list of Apache Cordova API's including sample code is available at API Reference.  Apache Cordova itself can be extended to provide additional native device functionality.  For additional details on writing a Cordova plugin see Plugin Development Guide.

Kapsel is a set of plugins that enhance Apache Cordova with functionality such as a stream-lined logon to an SMP 3.0 server, the ability to update deployed applications, encrypted storage and push notifications.  For more information on SMP 3.0 in general see the following blog post SAP Mobile Platform 3.0 launches at TechEd in Las Vegas or the blog posts by John Wargo, the Kapsel product manager.

Setup

Kapsel apps can be developed on Windows or Mac machines.  Kapsel apps can currently target Android or iOS mobile devices/emulators.  Development for an iOS device must occur on a Mac machine.  Android development can occur on a Windows or Mac machine.  Also see Supported Versions for SAP Mobile Platform SDK

The SAP Mobile Platform and the SAP Mobile Platform SDK can be downloaded from the SAP Service Market Place.  It is currently in Ramp Up.  See Demystifying SAP's Ramp-Up process for additional details about the ramp up process.

Four files need to be downloaded to install the SAP Mobile Platform 3.0 SP02 version.  The 3.0.0 server, the 3.0.0 SDK and then the SP02 support package for the server and the SP02 support package for the SDK.  If an image is blurry, click on it to see it at its full resolution.

Under A-Z Index, click on Installations and Upgrades > M > SAP Mobile Platform SDK > SAP Mobile Platform SDK 3.0 > Installation > SAP Mobile Platform Runtime 3.0 SDK Windows x64 64-bit.
Then click on Support Packages > SAP Mobile Platform SDK 3.0 > Windows on x64bit and download 3.0 SP02 support package.

Click on M > SAP Mobile Platform > SAP Mobile Platform 3.0 > Installation > SAP Mobile Platform Runtime 3.0 Windows x64 64-bit.
Then click on Support Packages and Patches > SAP Mobile Platform 3.0 Runtime > Windows on x64bit and download 3.0 SP02 support package.

Additional Required Software

The Apache Cordova command line will generate a project that can then be built using Android SDK or Xcode.

The Android  SDK also requires Java to run. To successfully use Apache Cordova for Android, a JAVA_HOME variable must be specified and it should be added to the windows path.

JAVA_HOME=C:\Program Files\Java\jdk1.7.0_45
PATH=%PATH%;%JAVA_HOME%\bin;

The Android SDK tools\bin folder also needs to be added to the windows and mac(.bash_profile) path.

PATH=%PATH%;C:\Android\sdk\tools

or

export PATH=$PATH:~/Downloads/adt-bundle-mac-x86_64-20130522/sdk/tools

If you are using Windows, Git for windows is a prerequisite and must be in the path.  Git can be installed from Git for Windows or git-scm.

On a Mac, Git is installed as part of Xcode.  The following commands can be used in OS X to view the version installed and to verify that it is on the path.

git --version
pkgutil --file-info /usr/bin/git
echo $PATH

If needed it can be installed from Git for Mac

Finally if using windows; ant should be installed and added to the path.

PATH=%PATH%;C:\apache-ant-1.9.1\bin

Accessing the SAP OData Gateway Demo

Kapsel apps communicate with backend enterprise systems primarily by using OData.  For additional information on OData see Appendix A:  OData.  SAP provides a publicly available OData endpoint at SAP Netweaver Gateway Demo System.  Some of the samples in this guide will utilize this.  Follow the instructions on the previously provided link to receive a user name and password necessary for accessing the OData source used throughout this guide.

Ensure that the OData endpoint can be accessed by opening it in a browser.

https://sapes1.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT

Enter the provided user name and password.

CarrierCollection is the collection that will be used.

CarrierCollection returns a list of airlines.

Note that the option ?sap-ds-debug=true can be used with SAP Netweaver Gateway OData sources.  This causes HTML to be returned to the browser enabling the content to be displayed in an easier to read format and the links become clickable.

Notice that https is used.  The following step adds the certificate of the SAP Netweaver Gateway server to the SMP 3.0 server.  This is needed as the SMP 3.0 keystore (C:\SAP\MobilePlatform3\Server\configuration\smp_keystore.jks) does not contain the trusted root certificate that was used to sign the certificate used by the SAP Netweaver Gateway server.

Right-click and choose View page info > Connection > Certificate Information.

Click on the Details tab, Copy To File... to export the certificate to a local cer file which can then be imported into the SMP 3.0 server's keystore.

C:\SAP\MobilePlatform3\Server\configuration>keytool -import -v -alias sapgatewaycert -keystore smp_keystore.jks -storepass changeit -file c:\temp\sapdevcenter.cer

Note, the password shown above, changeit, was a value that was requested during the SMP 3.0 server install.  Replace changeit with the value you specified during the install.

Note that the SMP 3.0 server needs to be restarted after making this change.

The above step demonstrates how to enable the SMP 3.0 server to trust the OData server's certificate by installing the certificate (sapdevcenter.cer) into the SMP 3.0 server's keystore.  Alternatively, the certificate belonging to the entity that signed the OData server's certificate (Starfield) could be installed.
Here are a few more useful keytool commands

keytool -list -v -keystore smp_keystore.jks 
keytool -list -v -keystore smp_keystore.jks -alias sapgatewaycert
keytool -delete -alias sapgatewaycert -keystore smp_keystore.jks

Configuring a Kapsel App in the Management Cockpit

The SMP 3.0 server provides authentication, logging and the ability to rewrite the URLs of an OData endpoint.  The SMP authentication providers enable the use of an existing authentication system to authenticate users accessing mobile applications.  Rewriting URL's can hide from the end user the host name of the OData endpoint.

The following steps will demonstrate how to configure a new hybrid or Kapsel app in the SMP 3.0 management cockpit.

Create a new application in the management cockpit.  The management cockpit can be accessed at https://localhost:8083/Admin/

The default user is smpAdmin and password is whatever was specified during the install.

Click on Applications > New.  The id is

com.mycompany.logon

The OData endpoint URL is

https://sapes1.sapdevcenter.com/sap/opu/odata/IWFND/RMTSAMPLEFLIGHT

The Use System Proxy should be checked if the computer uses a proxy server.

The values for the system proxy are set by modifying the SMP 3.0 server's props.ini file.

Note, changes to the props.ini file require either stopping and starting the SMP server via stop.bat and go.bat if it is not running as a service.  If the SMP 3.0 server is being run as a service, the service should be stopped, its settings regenerated and then restarted.  The service can be stopped and started with the services.msc commmand.  The steps to regenerate the service settings are shown below.  They may require being run in a command prompt that is opened by shift-right-click on cmd.exe shortcut and choosing run as administrator.

C:\SAP\MobilePlatform3\Server\bin\svcutil -uninstall
C:\SAP\MobilePlatform3\Server\bin\svcutil -generate
C:\SAP\MobilePlatform3\Server\bin\svcutil -install

Under the Authentication tab, choose the default configuration.

The OData endpoint will handle the authentication rather than the SMP 3.0 server.  The No Authentication Challenge provider allows any user id and password to succeed during the registration process.

Press Save.

Ping the endpoint to confirm that it is correctly configured.

The application is now configured in the SMP 3.0 server and ready to be implemented.

Installing Apache Cordova with Node.js

Note, execute the following commands using the Windows command prompt or the OS X terminal.

If necessary, download and install Node.js from nodejs.org/download

Node.js and its package manager npm can be used to install Apache Cordova.  The version installed can be seen by the following node command

node -v

To see what packages are already globally installed use

npm ls -g

Use npm to install the Apache Cordova command-line interface.
Cordova 3.0.6 (or the latest 3.0.x version) should be used if using SMP 3.0.

Cordova 3.1.0-0.2.0 (or the latest 3.1.x version) should be used if using SMP 3.0 SP01.
Cordova 3.3.1-0.1.2 (or the latest 3.3.x version) should be used if using SMP 3.0 SP02.
Additional information is available at The Command-line Interface.

npm install -g cordova@3.3.1-0.1.2
npm ls -g cordova
or
cordova -v

Note, the -g indicates that Apache Cordova should be installed globally.  It will be placed at the location indicated by

npm root -g

Note if you are on a Mac, use

sudo npm install -g cordova@3.3.1-0.1.2

A specific version of Apache Cordova can be installed by specifying a version number or if the version number is not supplied then the latest version is installed.

npm install -g cordova@3.3.1-0.1.2

The available versions can be seen with the info command.

$ npm info cordova

Note, if you use a proxy server you will need to configure npm and git.  The following are for illustration purposes and demonstrate how to list the current settings, remove them and to set them.  If these are not set an error similar to the one shown below may appear when creating a project.  If this happens, delete C:\Users\user\.cordova\, set the proxy settings and rerun the create command.

[Error: downloaded www assets in /Users/user_name/.cordova/lib/www/cordova/3.3.0/www does not contain index.html, or www subdir with index.html]

npm config get proxy
npm config get https-proxy
npm config delete proxy
npm config delete https-proxy
npm config set proxy http://proxy:8080
npm config set https-proxy http://proxy:8080

git var -l
git config --global --get http.proxy
git config --global --get https.proxy
git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global http.proxy http://proxy:8080
git config --global https.proxy http://proxy:8080

Uninstalling Apache Cordova

Cordova can be uninstalled by

npm uninstall -g cordova
npm cache clean

After performing the uninstall, if the following folder exists, you may wish to also delete it.

C:\Users\user\.cordova

or on a Mac

~/users/user/.cordova

Creating an Apache Cordova Project

The command-line interface or CLI is used to create Cordova projects.  For additional details see Command-line Interface.

Create a folder to hold the Kapsel projects such as C:\Kapsel_Projects or ~/Documents/Kapsel_Projects
A new project can now be created using

cordova -d create C:\Kapsel_Projects\LogonDemo com.mycompany.logon LogonDemo

or on a Mac

cordova -d create ~/Documents/Kapsel_Projects/LogonDemo com.mycompany.logondemo LogonDemo

The first parameter following create is the directory to create the project, the next parameter is a reverse-domain-style identifier and the final parameter is the project name.
Note, this may take a few minutes to complete as an initial download of the template project that will be used has to be downloaded to

C:\Users\user\.cordova

or

~/users/user/.cordova

Note, the -d flag indicates debug output and is optional but can be useful the first time this is run in case something goes wrong.

Note, on a Mac, if the above command fails due to a permission problem, it may be necessary to provide execute rights to the folder where Cordova was installed.

cd /usr/local
sudo chmod +r+x bin

To add a platform run the following command

cd C:\Kapsel_Projects\LogonDemo or cd ~/Documents/Kapsel_Projects/LogonDemo
cordova -d platform add android

or

cordova -d platform add ios

or both at once if you are on a Mac

cordova -d platform add android ios

At this point,

LogonDemo\www

contains the HTML, JavaScript and CSS used by the project.

The files contained in here are the ones that should be modified.  A duplicate set of the files are included in each of the below directories.

LogonDemo\platforms\android\assets\www
LogonDemo\platfoms\ios\www

A plugin can be added with the following command.  The below plugin enables console.log to display log messages.

cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git

For a list of additional plugins click on one of the API's such as Camera at http://cordova.apache.org/docs/en/3.3.0/

Changes would now be made to index.html file followed by calling the prepare command to copy the files in the project/www folder to the platform specific www folders.

cordova -d prepare android ios

At this point the project can be opened in a development environment such as Xcode or the Eclipse IDE that includes the Android Development Tools plugin.  Alternatively, the cordova command line can also be used to build and deploy the project.

Note to open the project in Eclipse and then run it choose File > Import > Android > Existing Android Code Into Workspace.  Then right-click on the project and choose Run As > Android Application.

To open the project in Xcode, double click on the file

~/Documents/Kapsel_Projects/LogonDemo/platforms/ios/LogonDemo.xcodeproj

Kapsel Plugins

The following sections provide step by step instructions demonstrating each Kapsel plugin and a set of appendices on topics related to Kapsel app development.
Logon
AppUpdate
Push
EncryptedStorage
Logger
Settings
AuthProxy
Appendix A:  OData
Appendix B:  Debugging
Appendix C:  UI Frameworks
Appendix D:  Security
Appendix E:  Upgrading
Appendix F:  Tips
Appendix G:  New Features
Appendix H:  Non Kapsel Plugins
Appendix I:  Afaria and Kapsel