SAP Kapsel Plugins For Cordova

SAP Kapsel – Apache Cordova Plugins
Technical Overview
Midhun VP
August 26th, 2015

Overview of Apache Cordova
and SAP Kapsel

© 2015 SAP AG. All rights reserved. 3
Container-Based Applications on Mobile Devices - Apache
Cordova
Mobile Device
When a browser-based application is executed on a mobile device, the JavaScript coding normally
has no access to hardware features of the mobile device such as the accelerometer, GPS location or
the camera etc.
In order for a web-based application to gain access to these hardware features, it is necessary to run
the application within a container that acts both as a browser and provides an API to access the
hardware.
Apache Cordova (formerly known as PhoneGap) provides this container.

Cordova High Level Architecture
Mobile Device
Native Application
Web View
JavaScript, CSS, HTML, etc.
Plugin
JavaScript API
Native API
Plugin
JavaScript API
Native API
Plugin
JavaScript API
Native API
Plugin
JavaScript API
Native API

Cordova’s standard PlugIns
Events
 pause, resume, online, offline, backbutton, menubutton, …
Notification
 alert, confirm, prompt, beep, vibrate
Capture
(Capture media files using device's media capture applications)
Storage (DB device storage interface)
Geolocation
File
Media (audio recording an playback)
Contacts

Cordova’s User Interface

Apache Cordova Benefits
 Large Community of Contributors
 Developer community that needs little ramp-up
 Supports most devices
 Web developers do not need to understand native code for customizing container
 Better performance at app startup and page loading
 Config.xml approach to configure web app and turn on/off plugins
 Network whitelisting approach to handle most web security threats
(see html5sec.org)

Kapsel - SAP Specific Plug-Ins for Cordova
SMP3 / HCPms Server
HTTP(S)
In order for a Cordova-based web application to be able to interact with SMP3/HCPms, SAP has
provided a set of plugins that are collectively known as “Kapsel”. These plugins are part of the larger
Mobile SDK.
In this presentation, we will be focusing on the use of the Kapsel Logon and OData plugins.
Mobile Device

Kapsel SDK
Part of the SAP Mobile Client SDK.
 Contains Plugins
 Contains Fiori Client
 Command Line Interface (CLI)

Kapsel
 Kapsel is a set of SAP specific plugins for
Apache Cordova
 Provides enterprise capabilities to a
Cordova application
 Fits cleanly within existing Cordova
development environments and processes
 Supports Android (4.0+), iOS (6.0+) and
Windows 8.1 / Windows Phone 8.1
 A single web application can be provisioned
into the container
Cordova
AppUpdate
AuthProxy
EncryptedStorage
Logger
Logon
Push
OData
3rd party plugin
3rd party plugin
KapselPlugins
E2E
Barcode Scanner
Online App
App Prefs

Kapsel Plugins
1. AppUpdate
2. AuthProxy
3. EncryptedStorage
4. Logon
5. Logger
6. Push
7. Offline OData
8. E2E
9. Barcode Scanner
10. Online App
11. App Preferences
12. And More…

Apache Cordova Command
Line Client

Apache Cordova
Before You Start
To get started with Cordova you need a number of things in place and
configured.
 Node.JS– contains package manager used to install/update Cordova.
– http://nodejs.org/
 GIT – used to access source repositories where Cordova plugin’s and resources reside.
– Windows – install GIT from here: http://msysgit.github.io/
– OS X – install Xcode command line tools
 Ant – used to build downloaded plugins
– Must install on Windows; Comes with Xcode command line tools; Install here:
http://ant.apache.org/manual/install.html

Apache Cordova
Command Line Interface (CLI) – Overview and Project Create Command
Cordova CLI is used to create projects, add plugins to projects, add
supported device platforms to projects, and much much more.
 Cordova CLI documentation - http://cordova.apache.org/docs/en/4.0.0/index.html
 To Create a Project: cordova create <Project Folder> <Package Name> <Display Text>
– Package Name and Display Text are optional and can be edited in the project’s config.xml file.
– Example: cordova create HelloWorld com.example.helloworld "HelloWorld"
– www folder contains web contents
o javascript, css, html

Apache Cordova
Command Line Interface (CLI) – Add Supported Device Platform Command
Kapsel supports iOS, Android and Windows 8.1 platform. Adding platforms to
your projects is simple with the Cordova CLI.
 Add Platform Command: cordova platform add <android/ios>
– Must be in Project’s root directory
– Need OS X to work with iOS platform; Windows OS to work with Windows 8.1
– Device specific resources copied (and downloaded if needed) into platforms/<device> directory.
– Note: Android SDK tools folder must be defined on the PATH environment variable

Apache Cordova
Command Line Interface (CLI) – Prepare Platform
Once your platform independent resources are developed and placed in the
project’s www folder you can prepare the platforms so they are ready for
deployment.
 Add Prepare Platform Command:
cordova prepare <android/ios>
– Moves content found in main www folder to platform’s www folder.

Apache Cordova
Run Application on iOS Simulator
For iOS, you can just open the project in Xcode by double clicking on the
.xcodeproj file.
 Then from Xcode just run it in the Simulator.

Apache Cordova
Run Application on Android Emulator
Run on Emulator: cordova emulate android
Run on Device: cordova run android

Agenda
Overview of Cordova and Kapsel
Working with the Cordova Command Line Interface (CLI)
How to use the Kapsel Logon Plugin
How to use the Kapsel OData Plugin for Offline Apps
How to use the Kapsel Logger Plugin
How to use the Kapsel AppUpdate Plugin
How to use the Kapsel Push Plugin
How to use the Kapsel EncryptedStorage Plugin
Basics of using SAP UI5 with Kapsel

 Kapsel’s Cornerstone plugin – most plugins rely
upon the services provided by the Logon plugin
 Implementation of the SMP/HCPms Mobile
Application Framework (MAF) Logon Module as a
Cordova plugin
 Manages the process of onboarding application with
the SMP/HCPms server, authenticating user and so
on
 Where available, will interface with the MCIM client
(Client Hub)
 Where available, will pull certificates from Afaria
 Skinable – can provide your own look and feel.
Kapsel Logon Plugin

Logon Plugin
Add Plugin to Project
Cordova CLI has a command for adding plugins to your project.
 Cordova plugin add <plugin> --searchPath <file location to search>
– Location of plugin can be on file system path or URL.
– Command must be executed in the root directory of a Cordova project.
 To add the logon plugin:
 cordova plugin add com.sap.mp.cordova.plugins.logon --searchPath <Location of
Kapsel Plugins>
 Plugins are copied into the projects plugin directory:

Logon Plugin
Logging in to an Application
Call function init to start the logon process.
<static> init(successCallback, errorCallback, applicationId,
context, logonView)
 successCallback – function called when logon successful.
 errorCallback – function called when logon fails.
 applicationId – String; applicationId as defined on the SMP/HCPms server.
 context – optional; object that overrides Logon plugin default values.
 logonView – optional; use to point custom logon view.
 Typically would add logon code to index.html of your Cordova application.
 Other functions available with the logon plugin – see documentation for details on those.
– lock, unlock, set, get, etc.

Logon Plugin
Logging in to an Application - CODE
function init() {
//Application ID on SMP/HCPms
var appId = "com.sap.flight.kapsel";
// Optional initial connection context
// Sets defaults on MAF Login Component
var context = {
"serverHost": "10.7.96.217", //SMP 3.0 Server hostname or IP
"serverPort": "8080", //SMP 3.0 Server port
"https": "false", //Use HTTPS?
};
// Init the Logon component
sap.Logon.init(logonSuccessCallback, errorCallback, appId,
context, sap.logon.IabUi);
}
...
// Device is Ready! Call the init function!
document.addEventListener("deviceready", init, false);

Logon Plugin
Logging in to an Application – CODE; Callback Functions
function logonSuccessCallback(result) {
// If result is not null, we have successful login
if (result) {
// Set the application Context
// This has all the good stuff in it
applicationContext = result;
// Read the Airlines from Gateway and display
readAirlines(applicationContext);
}
}
...
function errorCallback(e) {
alert("An error occurred");
alert(JSON.stringify(e));
}

Logon Plugin
Logging in to an Application – Using the Application Context
function readAirlines(applicationContext) {
//Check if user has been on-boarded
if (!applicationContext) {
alert("Register or unlock before proceeding");
}
// Get the endpoint, user, password and setup the X-SMP-APPCID header
var uri = applicationContext.applicationEndpointURL;
var user = applicationContext.registrationContext.user;
var password = applicationContext.registrationContext.password;
var headers = {"X-SMP-APPCID" :
applicationContext.applicationConnectionId};
// Create OData model from URL
var oModel = new sap.ui.model.odata.ODataModel(uri,
true,
user,
password,
headers);
...
}

Agenda

A SAPUI5, Cordova-Based Application Running in Online
Mode
SMP3/HCPms Server OData Server
SAP Gateway or HANA
HTTP(S) HTTP(S)
Since the mobile device has network
connectivity, the container-based app can
perform direct OData operations against the
backend server using SMP3/HCPms as a
proxy server.
The client app receives a real-
time response from the backend
server
Mobile Device

A SAPUI5, Cordova-Based Application Running in Offline
Mode 1/5
SAP Gateway or HANA
1. In order to use an app in offline mode, you must first have
network connectivity to the SMP3/HCPms server.
Mobile Device
HTTP(S) HTTP(S)

Mode 2/5
SAP Gateway or HANA
Offline
Store
2. The Kapsel OData plugin extracts information from the backend
server and stores it in an offline store held locally on the device.
Mobile Device
HTTP(S) HTTP(S)

Mode 3/5
SAP Gateway or HANA
Offline
Store
2. The Kapsel OData plugin extracts information from the backend
server and stores it in an offline store held locally on the device.
3. The app can now operate without the need for any network
connectivity by performing operations on the data held locally in
the offline store.
Mobile Device

Mode 4/5
SAP Gateway or HANA
Offline
Store
4. When network connectivity is re-established, the offline store
must be synchronized with the backend server. This is a 2-step
process:
a) Local modifications made to the offline store must be flushed to the
backend. Think of this as “pushing out the changes I have made”.
Mobile Device
HTTP(S) HTTP(S)

Mode 5/5
SAP Gateway or HANA
Offline
Store
4. When network connectivity is re-established, the offline store
must be synchronized with the backend server. This is a 2-step
process:
a) Local modifications made to the offline store must be flushed to the
backend. Think of this as “pushing out the changes I have made”.
b) The offline store must also be refreshed with any changes made by other
users of the same application.
Think of this as a “pulling in the changes other users have made”.
Mobile Device
HTTP(S) HTTP(S)

OData Plugin
 cordova -d plugin add <location of plugin>
– Location of plugin can be on file system path or URL.
– Command must be executed in the root directory of a Cordova project.
 To add the logon plugin:
cordova plugin add com.sap.mp.cordova.plugins.odata --searchPath <Location of
Kapsel Plugins>
 Plugins are copied into the projects plugin directory:

OData Plugin
Accessing OData Offline – createOfflineStore(…)
Call method createOfflineStore(…) to create an OfflineStore object.
<static> createOfflineStore(properties) -> sap.OfflineStore
Properties – an object with property values for creating the Offline Store. Example:
var properties = { "name": "travel”, "host": connectionInfo.serverHost, "port":
connectionInfo.serverPort, "https":
connectionInfo.https, "serviceRoot" : connectionInfo.serviceUrl,
"definingRequests" : { "req1" : "/Products?$expand=Supplier” },
"customHeaders" : connectionInfo.headers }
var store = sap.OData.createOfflineStore(properties);

OData Plugin
Accessing OData Offline – OfflineStore Method open(…)
Call the open(…) method to open the offline store. Must be online at the
stage!
Creates local database on the device.
open(success_callback, error_callback)
success_callback – function called if store was opened successfully.
error_callback – function called if error was encountered when opening store.
Example:
store.open(store_open_success, store_open_failure);

OData Plugin
Accessing OData Offline – applyHttpClient()
Call applyHttpClient() applies custom OData.defaultHttpClient with custom Http Client
that will access local database for requests that are mapped to the Offline Store.
<static> applyHttpClient()
Example:
sap.OData.applyHttpClient();
Call when you want to go offline!
Can remove with the removeHttpClient() call:
sap.Odata.removeHttpClient();

OData Plugin
Accessing OData Offline – flush(…)
Flush is called on a OfflineStore object to send all the requests that occurred
when offline to the server. Call when you come back online.
flush(success_callback, error_callback)
Example:
sap.OData.stores[0].flush(flush_success, flush_failure);

OData Plugin
Accessing OData Offline – refresh(…)
Refresh is called on an OfflineStore object to pull in the latest changes from
the backend and update the OfflineStore.
refresh(success_callback, error_callback)
Example:
sap.OData.stores[0].refresh(flush_success, flush_failure);

Agenda

Kapsel Logger
• Write logs back to server
Console Log
• Standard Cordova plugin – allows you to
write to the console logs of the platform.
Kapsel Logger Plugin and Cordova ConsoleLog plugin

Kapsel Logger and Cordova ConsoleLog Plugin
 It must be executed in the root directory of a Cordova project.
 To add the Kapsel logger plugin:
cordova plugin add com.sap.mp.cordova.plugins.logger --searchPath <Location of
Kapsel Plugins>
 To add the Cordova ConsoleLog plugin:
cordova plugin add org.apache.cordova.console

ConsoleLog Plugin
Logging in to an Application - CODE
Call function init to start the logon process.
<static> log(message)
 Message – String; message your want to be logged on device.
 Example: console.log("Logon was successful!");

Logger Plugin
Logging messages - CODE
Several methods to log messages at different status levels.
<static> debug(message, tag, successCallback, errorCallback)
Or warn(...) or info(...) or error(...).
 Message – String; message you wanted logged.
 tag – optional String; tag to help sort the logged messages
 successCallBack – optional function; called on success
 errorCallBack – optional function; called on error
sap.Logger.info(message, tag);

Logger Plugin
Uploading Logs to the Server
Uploads the log to the SMP/HCPms server.
<static> upload(successCallback, errorCallback)
 successCallBack – function; called on success
 errorCallBack – function; called on error
sap.Logger.upload(function() {
console.log("Logs uploaded to server successfully");},
function(e) {
console.log("Upload Failed. Status: "
+ e.statusCode + ", Message: "
+ e.statusMessage);});

Log Plugin
Activate Logging for Client
Logging must be activated for the client on HCPms.
 Admin UI > Registrations and Users:

Logger Plugin
Setting the log level - CODE
Optional method to change log level on the server.
<static> setLogLevel(level, successCallback, errorCallback)
 Level - set to sap.Logger.INFO/ERROR/DEBUG/WARN
 successCallBack – function; called on success
 errorCallBack – function; called on error
 Example – set log level to INFO:
sap.Logger.setLogLevel(sap.Logger.INFO,
function() {console.log("Log level set");},
function() { console.log("Failed to set log level");});

Agenda

• Kapsel’s Lifecycle Management plugin
• Manages remote updating web content
within the Kapsel container
• www folder contents uploaded to
SMP3/HCPms.
• No special coding required.
• App checks if new update is available –
pulls new content from server
Kapsel AppUpdate Plugin

AppUpdate Plugin
 To add the AppUpdate plugin:
cordova plugin add com.sap.mp.cordova.plugins.appupdate --searchPath <Location of
Kapsel Plugins>
 Plugins are copied into the projects plugin directory, along with dependent plugins.

AppUpdate Plugin
Add Plugin to Project – config.xml
Add application version info to projects config.xml
 Open the config.xml file found in the project’s www folder.
 Before the closing “widget” tag, add the following where 1 is the version being deployed:
<preference name="hybridapprevision" value="1" />

• Kapsel CLI will be able to package up the contents of an application and then
deploy the packaged contents to the SMP3/HCPms server.
• Application defined in SMP3/HCPms will be able to support all platform types
for AppUpdate.
• Commands:
• kapsel package
• kapsel deploy
Kapsel CLI – For AppUpdate

Kapsel CLI
package command
The package command will package the contents of the platform www
folder’s for deployment.
kapsel package [platform(s)]
 Use optional platform flag to specify the platform(s) included in the package.
 Package web application resources into a Zip file (HTML, CSS, JavaScript files plus other
required resources)
 Files will be packaged to include the platform name (in lower case) plus the platform’s www
folder and the platform’s config.xml file.

Kapsel CLI
deploy command
Will deploy the packaged contents to the SMP3/HCPms server.
kapsel deploy <APP ID> <SMP_SERVER> <User> <Password>
 Will make an http(s) request to the server to deploy the archive which was created with the
package command
Example:
kapsel deploy com.sap.flight.kapsel localhost smpAdmin s3pAdmin

AppUpdate Plugin + Kapsel CLI
Making Changes and Push to Clients
To push a new update you just need to make changes to your application,
package and deploy to SMP3/HCPms.
 In HCPms Admin UI you will now see that Revision to is available:
 When the user opens the application they will be
notified the the new version:

Agenda

• Manages the process of registering for push
requests plus
• Exposes events which help a developer code
an application to respond to push notifications
• User must be registered with SMP3/HCPms
before registering for push
• SMP3/HCPms and Device must be on
network that can reach APNS/GCM
• Must define push settings in SMP3/HCPms
for application
Kapsel Push Plugin

Push Plugin
cordova plugin add com.sap.mp.cordova.plugins.push --searchPath <Location of
Kapsel Plugins>

Define Application Push Settings in SMP 3.0
Obtain necessary notification configuration from device platform and enter
into HCPms Applications Push settings:

Push Plugin
Registering API
To receive a notification user must register with APNS/GCM and register their
push notification token with SMP3/HCPms.
<static> registerForNotificationTypes(types, successCallback, errorCallback,
notificationlistenerfunc, senderId)
 types – Optional; Types of notifications the application wants to receive. The different types
of notifications are expressed in notificationType.
 successCallback – Optional function; called on successful registration
 errorCallback – Optional function; called on registration failure.
 notificationlistenerfunc – Optional function; called when the application is open and a
notification arrives.
 senderId – optional String; only used for GCM – the GCM Sender ID

Push Plugin
Registering - CODE
var nTypes = sap.Push.notificationType.SOUNDS |
sap.Push.notificationType.ALERT |
sap.Push.notificationType.BADGE;
//Register User for Push
sap.Push.registerForNotificationTypes(nTypes,
registerForPushSuccess,
registerForPushFailure,
proccessNotification,
“Optional GCM Sender ID");
function proccessNotification(notification) {
//Display Incoming Message
alert("Notification received: " + notification.dispmsg);
}

Push Plugin
Sending a Push Notification
SMP provides a RESTful service to send push notifications.
 The Request should be formatted with the following:
HTTP Method: POST
URL: http://<smp_server_hostname>:8080/Notification/<registration_id>
Request Header for GCM (other header types defined – check help):
X-SMP-GCM-DATA:
{"dispmsg":"Hello Kapsel","appid":"com.sap.flight.kapsel","appname":"Flight Kapsel App for
RKT","reasonurl":"http://www.sap.com","reasoncode":1234}
 Test from a REST Client:

Agenda

• Adds encrypted local storage to a
Cordova application (key-value pair)
• Store/Cache application data.
• Follows W3C Web Storage API with
some exceptions
• Works Asynchronously (like most things
on a mobile device).
Kapsel Encrypted Storage Plugin

Encrypted Storage Plugin
cordova plugin add com.sap.mp.cordova.plugins.encryptedstorage --searchPath
<Location of Kapsel Plugins>

Constructor
First step to using the Encrypted Storage is to create an Encrypted Storage
Object.
Constructor EncryptedStorage(storageName, storagePassword)
 storageName – String; name of the encrypted storage.
 storagePassword – Optional function; called on successful registration
 Example:
var storage = new sap.EncryptedStorage("FlightStore", "abcd1234");

Storing Data
The methods on the Encrypted Storage Object are Asynchronous and require callback
functions. To store data call the setItem() method:
setItem(key, value, successCallback, errorCallback)
 key – String; key of the value being stored, used for lookup
 value – String; value being stored
 successCallback – function; will be called on success
 errorCallback – function; will be called on failure
 Example:
storage.setItem(key, value, storageSuccessCallback,
storageErrorCallback);
function storageSuccessCallback() { console.log("Success");}
function storageErrorCallback(errorInfo) {
alert("Could not read data - " + errorInfo.message);
}

Getting Data
The methods on the Encrypted Storage Object are Asynchronous and require callback
functions. To get data call the getItem() method:
getItem(key, successCallback, errorCallback)
 key – String; key of the value being stored, used for lookup
 successCallback – function; will be called on success with value for key
 errorCallback – function; will be called on failure
 Example:
storage.getItem(airlineDataKey,
function(value) {airlineData = JSON.parse(value);},
storageErrorCallback);
function storageErrorCallback(errorInfo) {
alert("Could not store data - " + errorInfo.message);
}

Getting Data
The Encrypted Storage Object offers a number of methods to work with the stored data.
Clear all data from the storage:
clear(successCallback, errorCallback)
Remove a Key value for storage:
removeItem(key, successCallback, errorCallback)
Get Number of values stored
length(successCallback, errorCallback)

Agenda

• Kapsel supports any 3rd Party HTML5
libraries. Sencha, JQuery Mobile, etc.
• Easy to use SAP Mobile UI5 with
Kapsel.
• UI5 contains UI elements and OData
Client API.
• Based on Model View Controller (MVC)
architecture.
• For best performance package SAP
Mobile UI5 with your application.
SAP Mobile UI5 and Kapsel

Making OData Calls
Obtaining Connection Details
The Logon Plugin successCallBack function receives all the connection
details to make an Odata call.
function successCallBack(applicationContext) {
...
// Get the endpoint, user, password and application Connection ID
var uri = applicationContext.applicationEndpointURL;
var user = applicationContext.registrationContext.user;
var password = applicationContext.registrationContext.password;
var appConnID = applicationContext.applicationConnectionId;
...
}

Making OData Calls
Creating OData Model
Create an ODataModel object with the connection data. Pass the application
connection ID as a header value.
var headers = {"X-SMP-APPCID" : appConnID};
// Create OData model from URL
var oModel = new sap.ui.model.odata.ODataModel(uri,
true,
user,
password,
headers);

Making OData Calls
Binding To UI List Element
Create the List Template and List object. The ODataModel gets bound to the
List object with specified collection to access.
// Create a list template
var oTemplate =
new sap.m.StandardListItem({title: "{carrid}",
description: "{CARRNAME}"});
// Create a List and add the model
var oList = new sap.m.List();
oList.setModel(oModel);
// Bind the CarrierCollection items and template
oList.bindItems("/CarrierCollection", oTemplate, null, null);
// Place it on the page
oList.placeAt("content");

Model View Controller (MVC)
View
Controller
Model

You should now be able to
 Have a good understanding of what Cordova is
 Understand how to create Cordova projects and add Kapsel
Plugins
 Understand how to use the Kapsel Logon Plugin
 Understand how to use the Kapsel AppUpdate Plugin
 Understand how to push Updates to Clients
 Understand how to use the Kapsel Logger Plugin
 Understand how to use the Kapsel Push Plugin
 Understand how to use the Kapsel EncryptedStorage Plugin
 Undestand the basics of using SAP UI5 with Kapsel
Summary

SAP Kapsel Plugins For Cordova

In this document

More Related Content

Viewers also liked

Similar to SAP Kapsel Plugins For Cordova

More from Chris Whealy

Recently uploaded

SAP Kapsel Plugins For Cordova