SAP Fiori Client (SP13+)

SAP Fiori is a set of applications that cover some of the most frequently used SAP software functions. These apps were written using SAPUI5 and hence can be accessed in a browser on a variety of devices. Details on the over 1000 apps are available at Fiori Apps Library. There is a demo of a few SAP Fiori apps available at SAP Fiori, Demo Cloud Edition.

When an SAP Fiori app is run in the SAP Fiori Client, it provides a set of enhancements to the app including the ability to customize or brand the app title, app icon, splash screen, first use tip screen, access native device functionality such as a barcode scanner, security enhancements such as the ability to set a whitelist of URLs the application can communicate with, handling of authentication challenges within a WebView via the AuthProxy plugin, improved attachment handling on Android and iOS and additional benefits when integrated with the SMP 3.0 server.

See also the following posts.
SAP Fiori & SMP
Introducing SAP Fiori Client 1.2
SAP Fiori – Mobile
Fiori Guidelines
SAP Fiori Launchpad
SAP Fiori Reference Apps
Mobile Single Sign-On for SAP Fiori with SAP Authenticator
Configuring SAP Fiori Client for Single Sign-On with iOS SAP Authenticator
A prebuilt version of the SAP Fiori Client is available from the iTunes, Android, and Windows stores at iOS SAP Fiori Client mobile app, Android SAP Fiori Client mobile app, and Windows 10 SAP Fiori Client.
Note, the Fiori Client for Android is also available from SAP at MOB SAP FIORI CLIENT AND 1.X.X.

A custom version of the SAP Fiori Client for Android, iOS and as of SP13, Windows 10 can be created using the Kapsel SDK. Building the SAP Fiori Client yourself allows for the app to be customized. New plugins can be added or ones that are not being used can be removed.

For additional details see the script that creates the SAP Fiori Client at

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\create_fiori_client.js,

the JavaScript file at

C:\SAP\MobileSDK3\KapselSDK\plugins\fioriclient\www\fioriclient.js,

and the documentation at SAP Fiori Client.

The following steps will demonstrate how to create the SAP Fiori Client using SMP 3.0 SP14 SDK.

Building the SAP Fiori Client
Running the SAP Fiori Client
Customizations
Changing the App Name, Icon, and Splash Screen
Changing the Background Image
Modifying the Version
Modifying the Status Bar
Hiding Last Screen from AppSwitcher and Enabling or Disabling Screen Capture
Configurations
Opening the Fiori Client from an External Link
No Bridge
Using an X.509 Certificate
Using a Mobile Device Management Solution to Configure Initial Settings
Performance Settings
Troubleshooting
Proxying the Fiori Client through an SMP 3.0 Server

Building the SAP Fiori Client

  • Edit the file
    C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\config.json or /Users/i82xxxx/SAP/MobileSDK3/KapselSDK/apps/fiori_client/config.json

    Only include the platforms you wish to build and remove the others. Note, to building for iOS requires a Mac.

    {
        "packageName": "com.sap.fiori",
        "targetFolder": "FioriClient",
        "appName": "FioriClient",
        //"platforms": ["ios", "android", "windows"]
        "platforms": ["android"]
    }
    
  • In a command window run the following commands.
    cd C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client
    or on a Mac
    cd ~/SAP/MobileSDK3/KapselSDK/apps/fiori_client
    
    npm install
    node create_fiori_client.js
    cd FioriClient
    
  • Note it is also possible to debug the create_fiori_client.js script file. For additional details see V8 Inspector Integration for Node.js. Note this is an optional step.
    node --inspect --debug-brk create_fiori_client.js
  • Note that the create_fiori_client.js script has conveniently created a Cordova project containing Kapsel and Cordova plugins.
    C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient>cordova plugins
    cordova-plugin-camera 2.3.0 "Camera"
    cordova-plugin-compat 1.1.0 "Compat"
    cordova-plugin-contacts 2.2.0 "Contacts"
    cordova-plugin-crosswalk-webview 2.0.0 "Crosswalk WebView Engine"
    cordova-plugin-customurlscheme 4.0.0 "Custom URL scheme"
    cordova-plugin-device 1.1.4 "Device"
    cordova-plugin-dialogs 1.3.1 "Notification"
    cordova-plugin-file 4.3.1 "File"
    cordova-plugin-geolocation 2.3.0 "Geolocation"
    cordova-plugin-network-information 1.3.0 "Network Information"
    cordova-plugin-privacyscreen 0.3.1 "PrivacyScreenPlugin"
    cordova-plugin-screen-orientation 1.4.2 "Screen Orientation"
    cordova-plugin-splashscreen 4.0.0 "Splashscreen"
    cordova-plugin-statusbar 2.2.0 "StatusBar"
    cordova-plugin-whitelist 1.3.0 "Whitelist"
    de.appplant.cordova.plugin.printer 0.7.0 "Printer"
    kapsel-plugin-apppreferences 3.14.4 "AppPreference"
    kapsel-plugin-appupdate 3.14.4 "AppUpdate"
    kapsel-plugin-attachmentviewer 3.14.4 "AttachmentViewer"
    kapsel-plugin-authproxy 3.14.4 "AuthProxy"
    kapsel-plugin-barcodescanner 3.14.4 "BarcodeScanner"
    kapsel-plugin-cachemanager 3.14.4 "CacheManager"
    kapsel-plugin-calendar 4.4.4 "Calendar"
    kapsel-plugin-cdsprovider 3.14.4 "CDSProvider"
    kapsel-plugin-corelibs 3.14.4 "CoreLibs"
    kapsel-plugin-encryptedstorage 3.14.4 "EncryptedStorage"
    kapsel-plugin-federationprovider 3.14.4 "FederationProvider"
    kapsel-plugin-fioriclient 3.14.4 "FioriClient"
    kapsel-plugin-i18n 3.14.4 "i18n"
    kapsel-plugin-inappbrowser 3.14.4 "InAppBrowser"
    kapsel-plugin-inappbrowser-xwalk 3.14.4 "InAppBrowser"
    kapsel-plugin-logger 3.14.4 "Logger"
    kapsel-plugin-logon 3.14.4 "Logon"
    kapsel-plugin-online 3.14.4 "Online"
    kapsel-plugin-push 3.14.4 "Push"
    kapsel-plugin-settings 3.14.4 "Settings"
    kapsel-plugin-toolbar 3.14.4 "Toolbar"
    kapsel-plugin-ui5 3.14.4 "ui5"
    kapsel-plugin-usage 3.14.4 "Usage"
    kapsel-plugin-voicerecording 3.14.4 "Voice Recording"
    
  • Edit the following file:
    C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\www\appConfig.js

    Provide values such as those shown below.
    Note the fioriURL should be changed to reflect the webserver that hosts your SAP Fiori applications uses or to the trial SAP Fiori Launchpad.
    Note the website http://jsonlint.com/ can be used to validate JSON such as the contents of the appConfig variable below.

    fiori_client_appConfig = {
        "appID": "com.sap.fiori",
        //"fioriURL" : "https://www.sapfioritrial.com/sap/hana/uis/clients/ushell-app/shells/fiori/FioriLaunchpad.html?helpset=trial&sap-client=001",
        "fioriURLIsSMP": false,
        "certificate": "",
        "autoSelectSingleCert": false,
        //"backgroundImage": "../../../nightsky.jpg",
        "disablePasscode": false,
        "passcodePolicy": {
            "expirationDays":"0",
            "hasDigits":"false",
            "hasLowerCaseLetters":"false",
            "hasSpecialLetters":"false",
            "hasUpperCaseLetters":"false",
            "defaultAllowed":"true",
            "lockTimeout":"300",
            "minLength":"8",
            "minUniqueChars":"0",
            "retryLimit":"0"
            //"allowFingerprint":"true"
        }
    };
    

    The fioriURLIsSMP setting indicates if the SMP 3.0 server should be used as a proxy to access the SAP Fiori app enabling additional logging, authentication mechanisms, push notifications etc. An example of this being set to true is shown later in this document.
    The passcode policy can be set in the SMP 3.0 management cockpit when fioriURLIsSMP is true or in the appConfig.js as shown above when fioriURLIsSMP is false. Since the passcode policy setting defaultAllowed is set to true, this allows the user the option to disable the Passcode screen.

  • Build and deploy the project via the following command.
    cordova run android
    or
    cordova run ios
    or
    cordova run windows -- --archs=x64

Running the SAP Fiori Client

Some of the functionality of the app is illustrated below.

If the fioriURL variable is not specified in the appConfig.js or if the app is the one downloaded from the public app stores, the first screen shown requests the user to choose between Log In or Demo Mode. Demo mode uses the trial URL automatically and disables the passcode screen.

If using SAP Mobile Secure, an email can be provided instead of a URL that the Fiori Client will then use the email domain to get the details on how to connect to the Fiori app. Entering an email is typically less error prone than entering a long URL.
The following is an examle configuration in SAP Mobile Secure and the email address that would be entered.

dan@trial-i82XXXXtrial.sapmobileplace.com

New in SP14 is the ability to use the Barcode scanner to enter a URL.

The following QR code encodes the following trial URL.

https://www.sapfioritrial.com/sap/hana/uis/clients/ushell-app/shells/fiori/FioriLaunchpad.html?helpset=trial&sap-client=001


This screen can be skipped via the disablePasscode setting in the appConfig.js file.
The passcode policy is configured in the appConfig.js or in the SMP management cockpit when fioriURLIsSMP is set to true.

The Enter Passcode screen is shown when the app is subsequently opened or resumed from the background when a passcode has been set and the locktimeout has expired.

The first use tip screen is shown the first time the app is opened. To customize this, see the method showFirstUseTips and also logonCompletedCallback in the following file.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\plugins\kapsel-plugin-fioriclient\www\fioriclient.js

To remove it, add the below line to deviceready event in the www\js\index.js file.

sap.AppPreferences.setPreferenceValue('skipShowFirstUseTips', true);


If the URL being accessed is not available or uses HTTPS and the certificate authority that signed the web server’s certificate is not trusted by the device, an error page will be shown.

For additional details see Installing a Certificate or the HTTPS in the Security Appendix. A quick test to see if the site can be opened is to open the URL on the device’s browser.

By double tapping, a native menu is shown. The menu items are added in the initClient method in the following file.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\plugins\kapsel-plugin-fioriclient\www\fioriclient.js

The ability to view the device log and send it in an email is shown below.

The settings are implemented in fioriclient.js (and validation.html for Android).

Customizations

Changing the App Name, Icon and Splash Screen

The app name, icon and splash screen can be customized before create_fiori_client.js is run by modifying the appName in the following file.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\config.json

The icon.PNG files are under the following folder.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\template\res

The splash screen resources under the following folder.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\template\res\screen

As of SP11, the App Name in the Logon screen can be specified via the appName setting in the following file.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\www\appConfig.js

If it is not specified it defaults to SAP Fiori Client.

Changing the Background Image

The flowers background image of the SAP Fiori Client can easily be replaced via the backgroundImage setting in appConfig.js file as of SP13.

Modifying the Version

On Android and iOS, the version is specified in the following file.

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\config.xml
<widget id="com.sap.fiori" version="3.0.14.1"

In Xcode the build field should match the value in the config.xml file after running cordova prepare ios.

Note there is also a version displayed on the iOS settings screen. This version can be changed by editing the Resources > Settings.bundle > Root.plist file.

The version is specified in the following file on Windows:

C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\plugins\kapsel-plugin-fioriclient\www\messages_en.properties

Modifying the Status Bar

Note that on iOS, there are a few settings that can control how the status bar is displayed. The Fiori Client uses the StatusBar Plugin with the following settings set in config.xml.

<preference name="StatusBarOverlaysWebView" value="false" />
<preference name="StatusBarStyle" value="default" />
<preference name="StatusBarBackgroundColor" value="#FFFFFF" />


Note that statusbar can be removed by adding the following code to the file Resources/FioriClient-Info.plist.

<key>UIStatusBarHidden</key>
<true/>
<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

Hiding Last Screen from AppSwitcher and Enabling or Disabling Screen Capture

As of SP11, the Fiori Client includes the Privacy Screen plugin which on Android prevents the screen from being captured and on iOS and Android, prevents the last displayed screen from appearing in the app switcher. To remove this functionality run the following command to remove this plugin.

cordova plugin remove cordova-plugin-privacyscreen

As of SP 15, the Fiori Client on Android will likely have a menu option to enable or disable this feature.

Configurations

Opening the Fiori Client from an External Link

It is possible to provide a link to the Fiori Client or to a specific Fiori App within the Fiori Client on a webpage or an email. Here are a couple of examples. When the link is selected in a browser, the SAP Fiori Client will open.

<a href="com.sap.fiori.xcallbackurl://x-callback-url/openFioriUrl">Deep Link to Fiori Client</a>
<a href="com.sap.fiori.xcallbackurl://x-callback-url/openFioriUrl?url=https://www.sapfioritrial.com/sap/hana/uis/clients/ushell-app/shells/fiori/FioriLaunchpad.html?helpset=trial&sap-client=001#ContactPerson-MyContact">My Contacts</a>


Note, the com.sap.fiori comes from the packageName specified in the file C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\config.json.
The second link contains the URL to be opened in the Fiori Client. In this case it contains #ContactPerson-MyContacts which will open the CRM app My Contacts.

See also Creating a Mobile Deep Link to an Application in SAP Fiori Client.

No Bridge

No Bridge prevents access to the native plugins added to the SAP Fiori Client unless the WebView URL has the same host as the fioriURL specified in the settings.
As the SAP Fiori Client from the app store can be used with a user provided Fiori URL the protection provided by the navigation whitelist in the Whitelist plugin are disabled as these must be configured at build time. Specifically, the SAP Fiori Client from the app store has the following setting in its config.xml file.

<allow-navigation href="*" />

Prior to the No Bridge security enhancement, with the combination of the Kapsel online plugin and the wildcard in the allow-navigation setting, it was possible for any page to be loaded by the WebView and that page would have access to the API’s provided by the plugins included in the SAP Fiori Client.
If you know in advance the URLs that a custom SAP Fiori Client will access, it may make sense to specify them using the whitelist plugin. It is not possible to change the settings in the config.xml for the app store versions of the SAP Fiori Client.

The following steps will demonstrate this feature.

  • Create the following HTML page at a location that is available over HTTP such as the following location.
    C:\SAP\MobilePlatform3\Server\webapps\sapui5\index1.html

    The contents for index1.html can be copied from below content.

    <html>
        <head>
            <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width, height=device-height, target-densitydpi=device-dpi" />
            <title>No Bridge Demo index1</title>
            <script>
                document.addEventListener("deviceready", init, false);
    
                function init() {
                    log(location.href);
                    log("Device version: " + device.version);
                }
    
                function log(line) {
                    var results = document.getElementById("log_lines");
                    results.innerHTML+= "<br>" + line;
                }
                
            </script>
        </head>
        <body>
            <h1>No Bridge Demo index1</h1>
            <button onclick="location.href='http://YKFN00620418A.amer.global.corp.sap:8080/sapui5/index1.html'">index1.html by Machine Name</button>&nbsp;&nbsp;
            <button onclick="location.href='http://10.7.168.124:8080/sapui5/index1.html'">index1.html by IP address</button><br><br>
            <button onclick="sap.Online.showBusyIndicator()">Show Busy Indicator</button>&nbsp;&nbsp;<button onclick="sap.Online.hideBusyIndicator()">Hide Busy Indicator</button>
        	<div id="log_lines"></div>
        </body>
    </html>
    

    Modify the above links to use your machine’s fully qualified domain name and the IP address.

  • Configure the fioriURL of the SAP Fiori Client to use index1.html referencing the fully qualified domain name such as the following URL.
    http://YKFN00620418A.amer.global.corp.sap:8080/sapui5/index1.html
  • Run the SAP Fiori Client.
  • Notice that the navigation to index1.html by Machine Name works, and the navigation to index1.html by IP address loads but it is not possible to successfully call methods of the added plugins such as sap.Online.showBusyIndicator() because the machine name is different. The following message appears in the Android logcat when attempting to show the Busy Indicator which invokes an API of the online plugin.

    The following appears in the Xcode All Output view when attempting to access this API.

    ERROR: Plugin 'Online' not found, or is not a CDVPlugin. Check your plugin mapping in config.xml.
    2015-11-04 12:05:33.398 FioriClient[576:104290] -[CDVCommandQueue executePending] [Line 159] FAILED pluginJSON = ["INVALID","Online","showBusyIndicator",[]]

    In SP14, logging was added at the DEBUG level on Android using the log tag of FEATUREVECTOR.

    In SP13 only, the showBusyIndicator does not work unless the following entry is added to the config.xml.

    <preference name="useBusyIndicator" value="false" />
  • Note: the following plugins are excluded from the No Bridge feature.
    • Logger
    • Toolbar
    • Whitelist
    • Device

     

  • It is possible to specify additional URL’s that should not be affected by the no bridge feature. This can be specified via a parameter in the appconfig.js file named noBridgewhitelist as shown below.
        "fioriURL":"http://YKFN00620418A.amer.global.corp.sap:8080/sapui5/index1.html",
        "noBridgewhitelist":"10.7.168.124:8080",
    

    Alternatively it can be specified as a URL parameter in the Fiori Client UI when the user provides the Fiori URL. For example on the Enter Fiori URL page, the following URL could be provided.

    http://YKFN00620418A.amer.global.corp.sap:8080/sapui5/index1.html?noBridgewhitelist=*

    The following are a few examples of possible values.

    noBridgewhitelist=*
    noBridgewhitelist=wdf.sap.corp
    noBridgewhitelist=*.wdf.sap.corp
    noBridgewhitelist=*.yahoo.com,*.google.com

    One common case where this may be needed is if your application contains links to attachments that are hosted on another server.

  • This feature can be disabled on Android by renaming the following two files and recreating the Fiori Client.
    C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\template\scripts\android\after_platform_add\PluginAspect.aj to PluginAspect.aj.bak
    C:\SAP\MobileSDK3\KapselSDK\SP15\apps\fiori_client\template\scripts\android\after_platform_add\prepareRestriction.js to prepareRestriction.js.bak

  • This feature can be disabled on iOS by adding the following setting.
  • Note, if No Bridge is disabled, consider replacing * from allow-navigation in the config.xml with a more restricted pattern.
  • For additional security topics see the following documents.
    Technical setup of an SAP Fiori Landscape – Part 3: Mobilizing Fiori
    Configuration and Deployment Information and
    Configuring Security in SAP Mobile Platform.

Using an X.509 Certificate

When an X.509 certificate is installed on an iOS device, it is only accessible to select applications such as Mobile Safari or Mail. See Making Certificates and Keys Available To Your App.

It is possible to use SAP Afaria to provision the SAP Fiori Client with an X.509 client certificate. To do this include the certificate=com.sap.afaria on the URL as shown below.

https://mo-39d7636c8.mo.sap.corp:44301/sap/bc/ui5_ui5/sap/zbarc_ui5_app?appid=test&fioriurlissmp=false&certificate=com.sap.afaria

If you wish to use a third party mobile device management solution to provide the X.509 client certificate, a custom SAP Fiori Client could be built that included a custom certificate provider. The fioriURL would then include the parameter &certificate=com.mycompany.certprovider.CustomCertificateProvider.

One other option on iOS would be to create a second application that is able to acquire a X.509 certificate and then to share that with a custom SAP Fiori Client through keychain sharing. See also Configuring Keychain Sharing.

Using a Mobile Device Management Solution to Configure Initial Settings

A mobile device management solution such as SAP Afaria can be used to configure initial settings similar to those that can be set in appConfig.js file on iOS.
Note if using SAP Mobile Secure or SAP Afaria place this info in the managed App Configuration section.
If the MDM supports JSON format, create a JSON object as follows:

config={ 
    "appID":"com.sap.fiori.client.release",
    "fioriURL":"https://<your-host>/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html?sap-client=100&sap-language=EN",
    "fioriURLIsSMP":false,
    "certificate" : "com.sap.afaria",
    "passcodePolicy":{}
}

Note the appID must match the bundle ID.
If the MDM does not support JSON, convert the above JSON to base64-encoded.

Convert this:

{ 
    "appID":"com.sap.fiori.client.release",
    "fioriURL":"https://<your-host>/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html?sap-client=100&sap-language=EN",
    "fioriURLIsSMP":false,
    "certificate" : "com.sap.afaria",
    "passcodePolicy":{}
}

To something like what is below:

 
eyANCiJhcHBJRCI6ImZpb3JpIiwNCiJmaW9yaVVSTCI6Imh0dHBzOi8vb
GRjaXUzZS53ZGYuc2FwLmNvcnA6NDQzMjYvc2FwL2JjL3VpNV91aTUvd
WkyL3VzaGVsbC9zaGVsbHMvYWJhcC9GaW9yaUxhdW5jaHBhZC5odG1
sP3NhcC1jbGllbnQ9MTAwJnNhcC1sYW5ndWFnZT1FTiIsDQoiZmlvcmlV
UkxJc1NNUCI6ZmFsc2UsDQoicGFzc2NvZGVQb2xpY3kiOnt9DQp9DQo=

Add a second parameter named version so it looks like this:

version=1
config=eyANCiJhcHBJRCI6ImZpb3JpIiwNCiJmaW9yaVVSTCI6Imh0dHBzOi8vb
GRjaXUzZS53ZGYuc2FwLmNvcnA6NDQzMjYvc2FwL2JjL3VpNV91aTUvd
WkyL3VzaGVsbC9zaGVsbHMvYWJhcC9GaW9yaUxhdW5jaHBhZC5odG1
sP3NhcC1jbGllbnQ9MTAwJnNhcC1sYW5ndWFnZT1FTiIsDQoiZmlvcmlV
UkxJc1NNUCI6ZmFsc2UsDQoicGFzc2NvZGVQb2xpY3kiOnt9DQp9DQo=

See also the following SAP notes demonstrating this process with SAP Afaria.

How to provision SAP Fiori client via Managed App Configuration using a JSON config. -Afaria/Mobile Secure.
Flow When Digital Signing is Enabled.

Performance Settings

There are a few things that can be done to improve the startup time of the Fiori Client.

  • The deviceready event fires after all the plugins have loaded. Remove any unused plugins.
  • The browserify option places all the JavaScript files into one file. This may improve loading time.
    cordova run ios --browserify
  • The skipIndex setting can be specified in the config.xml file. This setting indicates that the Fiori Client will not load the index.html in the project directory and will only load the fioriURL. This can signifcantly decrease the startup time of the Fiori Client.
    <preference name="skipIndex" value="true" />

    For further details and limitations see skipIndex

  • The useLocalStorage setting can be specified in the appConfig.js file and when set to true does not use the datavault which can take a while to unlock.
     "useLocalStorage": true,

    For further details and limitations see Storing configuration data outside of the datavault

  • Release builds will generally run faster than debug builds.

Troubleshooting

If a problem is preventing the Fiori Client from successfully registering, the settings screen may not appear, preventing the user from changing the log level. One way to do this is to first use demo mode to show the trial SAP Fiori app, then set the log level to debug from settings screen by double tapping. Reset the app from setting screen and input the Fiori URL that is not working with the Fiori Client. The debug log level will persist across the application reset, so it will stay in debug log level.

If you cannot debug the app in Xcode, you can still view the device console output through Xcode’s Device menu. It will show the console output from all applications running on the device without debugging the application from Xcode.

The Fiori Client does not support URL shortener services or bitly URLs due to No Bridge. This feature may also cause troubles opening a URL that uses a different host or port than the one specified in the fioriURL.

Turning off the cachemanager which sends some extra requests to server from native library to help detect when the cache may need to be updated can be disabled via a URL parameter or in the appConfig.js.

&enableCacheManager=false
"enableCacheManager": false

The section Troubleshooting SAPUI5 Apps contains some troubleshooting tips such as how to perform an end2end trace.

Proxying the Fiori Client through an SMP 3.0 Server

The following steps demonstrate how to proxy a SAP Fiori application through a SMP 3.0 server. For further details see Configuration and Deployment Information.

  • Create a Kapsel application with the following ID.
    com.sap.fiori
    
    

    Set the endpoint to be a partial URL of your company’s Fiori launchpad URL.
    An example of a full URL to the app and then the partial URL follows.

    https://abc.sap.corp:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html?sap-client=100
    and
    https://abc.sap.corp:443/
    

    Add an SSO mechanism such as Basic for a URL that requires credentials.
    Rewrite mode should be Rewrite URL in Backend System.

    Select an HTTPS Authentication provider and provide a URL that requires authentication. The URL

    https://abc.sap.corp:443/sap/bc/ping?sap-client=100

    will be used during the registration step to verify that the provided user name and password on the registration screen. Since an SSO mechanism is used, the app will not need to display the app’s login screen. See also Single Sign-On Integration Across Client Applications.

    If the Save button is disabled, switch to the ADVANCED tab, and delete the Token Expiration Interval value.

    Save the application, and then attempt to ping the endpoint.
    A partial SAP Fiori URL such as

    https://abc.sap.corp:443/

    should return a 404 not found error. You would see the same error if the URL was entered into a browser or possibly success if the 404 error is embedded in a 200 response.

  • Notice that the endpoint (https://abc.sap.corp:443) uses HTTPS. The certificate that the endpoint server uses was signed by SAPNetCA_G2. In Chrome this can be seen by clicking on the lock icon beside the URL and choosing Details, View certificate. This certificate and its the cert that signed it (SAP Global Root CA) need to be installed in the SMP 3.0 server’s keystore as shown below.


    The following are a couple of commonly seen error messages.

    Backend system cannot be reached:::Root cause:::Exception during connection execute: peer not authenticated

    This error may be seen if the SMP server does not trust the certificate used by the endpoint.

    Backend system cannot be reached:::Root cause:::Exception during connection execute: abc.sap.corp:443

    This indicates that the SMP server cannot reach the URL. Check if the URL is reachable in a browser. If it is, it may be that your network requires a proxy server to access external URLs. Check the Use System Proxy setting and ensure the proxy settings under Settings > System > HTTP proxy host are correct in the SMP server management cockpit.

  • In the following file set the variable fioriURLIsSMP to true to indicate that the connection to the app will be proxied through the SMP 3.0 server.
    C:\SAP\MobileSDK3\KapselSDK\apps\fiori_client\FioriClient\www\appConfig.js

    Set the fioriURL to a URL as shown below.

    https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html

    The methods parseAppConfig and handleFioriUrlWithFakeParameter will extract the host and port to connect to. Note there are additional settings that can be specified in the appConfig.js file. If the values are not specified in the appConfig.js file (for example in the version of the Fiori Client available on the Apple App Store and Android Play Store, the appConfig.js file is not editable), then they can be specified in the user provided fioriURL. If the fioriURL is not specified in the appConfig.js file then the Enter Fiori URL screen will appear and the parameters normally specified in the appConfig can be specified in the FioriURL. Here are a few examples.

    //Direct to the Fiori Server via user supplied URL
    https://www.sapfioritrial.com/sap/hana/uis/clients/ushell-app/shells/fiori/FioriLaunchpad.html
    
    //Direct to the Fiori Server via appConfig.js
    "appID": "com.sap.fiori",
    "fioriURL": "https://www.sapfioritrial.com/sap/hana/uis/clients/ushell-app/shells/fiori/FioriLaunchpad.html",
    "fioriURLIsSMP": false,
    

     

    //Proxying through an SMP server via user supplied URL
    https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html?appid=com.sap.fiori&fioriURLIsSMP=true
    
    //Proxying through an SMP server via appConfig.js
    "appID": "com.sap.fiori",
    "fioriURL": "https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html",
    "fioriURLIsSMP": true,
    
    

     

    //Mutual Authentication using Afaria/SAP Mobile Secure to provide the client certificate via user supplied URL
    https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html?appid=com.sap.fiori&fioriURLIsSMP=true&certificate=afaria
    //Note that in SP08 of the SDK there is a new certificate provider named certificate=com.sap.afaria that is to only be used when not registering with the SMP server.
    
    //Mutual Authentication using Afaria/SAP Mobile Secure to provide the client certificate via appConfig.js
    "appID": "com.sap.fiori",
    "fioriURL": "https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html",
    "fioriURLIsSMP": true,
    "certificate": afaria,
    

     

    //SAML Authentication via user supplied URL
    https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html?appid=com.sap.fiori&fioriURLIsSMP=true&authtype=saml2.web.post
    
    //SAML Authentication via appConfig.js
    "appID": "com.sap.fiori",
    "fioriURL": "https://YKFN00620418A.amer.global.corp.sap:443/sap/bc/ui5_ui5/ui2/ushell/shells/abap/FioriLaunchpad.html",
    "fioriURLIsSMP": true,
    "auth": [
        {
            "type": "saml2.web.post",
            "config": {
                "saml2.web.post.authchallengeheader.name": "com.sap.cloud.security.login",
                "saml2.web.post.finish.endpoint.uri": "/SAMLAuthLauncher",
                "saml2.web.post.finish.endpoint.redirectparam": "finishEndpointParam"
            }
        }
    ]
    

    See also Enabling SAML Authentication and
    Configuring SAP Fiori Client Using URL Query Parameters

    One tool that can be used to verify the JSON is jsonlint.com.

    In order to use HTTPS the mobile device or simulator will need to trust the certificate used by the SMP server. For additional details see the HTTPS in the Security Appendix. Alternatively, use HTTP with port 8080 which is the default HTTP port for the SMP server.
    Note, if the Fiori Client does not trust the certificate used by the SMP server, an error such as the following will appear on the device’s log.

    "LogonController.getRegistrationErrorText: {\"errorCode\":\"80003\",\"errorMessage\":\"java.security.cert.CertPathValidatorException: Trust anchor for certification path not found.\",\"errorDomain\":\"MAFLogonCoreErrorDomain\"}"
    

    The device log can be viewed on Android via Logcat or on iOS via Xcode or via the Fiori Client View Log menu item.

  • Deploy and run the app.Since fioriURLIsSMP is set to true and the fioriURL is specified, the first screen that appears is the user name and password screen.The passcode policy is retrieved from the SMP 3.0 server during a successful registration process and then the set app passcode screen is shown.The first use tips page is shown and then the app is loaded.
  • When the appConfig.js file has fioriURLIsSMP set to true, the settings screen has two additional read only settings: Proxy Through SMP and AppID.


    Note, if you wish to change the Fiori URL to point to a different SMP server and have not specified a value for fioriURL, click the Clear All Application Settings button under Reset Settings. This will cause the Enter SAP Fiori URL screen to appear.
  • When the SAP Fiori Client is used with the SMP 3.0 server or HCPms server, statistics can be viewed like those shown below.


    Items such as the log level, the log entry expiry, and the client policy can be remotely managed.
  • In addition, notifications can be sent to the device, and additional security authentication mechanisms are available.

Back to Getting Started With Kapsel

To report this post you need to login first.

28 Comments

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

  1. Patrick Bierbaums

    Hi,

    I’m currently trying to create a custom Fiori Client for Android using SP13 and I’m having Trouble with the crosswalk plugins.
    Environment:
    – Windows 10 Pro
    – SMP SDK 3.0 SP13
    – Cordova 6.1.1

    When I create the project using create_fiori_client.js an error occurs when installing cordova-plugin-crosswalk-webview: “Plugin doesn’t support this project’s cordova-android Version. cordova-android: 5.1.1, failed Version requirement: >=6.”

    When I check the created Folder, I see that cordova-plugin-crosswalk-webview was installed with Version 2.2.0, even though the create_fiori_client.js defines Version 1.7.2. I have also tried to install Version 2.0.0 (as in your example above), but the error occurs with this one as well.

    When trying to build the apk, it Fails because of missing plugin Installation.

    Now to fix the error I’ve tried to navigate to the project, uninstall platform Android, uninstall plugin cordova-plugin-crosswalk-webview, install plugin cordova-plugin-crosswalk-webview@1.7.2, install Android and then build the apk. This works without Errors, but when I install the apk on a device or Emulator, the app crashes on start.

    The only way I have managed to create a functional Client, was by editing the create_fiori_client.js file and removing the crosswalk and xwalk plugins. However this is not satisfying, because of the missing benefits of crosswalk.

    Do you have any idea what I’m doing wrong and how the error could be fixed?

    Best regards,
    Patrick

    (0) 
  2. Daniel Van Leeuwen Post author

    What is the full version number of the Kapsel SDK that you are using?  The version number is shown in the plugin.xml file of most of the Kapsel plugins.

    I have not myself encountered that problem but can try it again using the same version you are using.  I would recommend trying the latest available PL if you are not on it already.

    SP 14 should also be coming out before too long.

    Finally crosswalk is particularily useful if you are deploying to devices that are older than Andorid 5.0.  The WebView component as of Android 5.0 is updated automatically via the app store.

    Regards,
    Dan van Leeuwen

    (0) 
    1. Patrick Bierbaums

      Thanks for your reply. The Version number of Kapsel SDK is 3.13.6. I’ve been using PL 6 of SMP SDK 3.0 SP 13.

      We have devices with all kinds of Android versions, so the use of crosswalk would be preferred.

      Best regards,
      Patrick Bierbaums

      (0) 
      1. Daniel Van Leeuwen Post author

        I believe I was able to reproduce the problem.

        I think this is what is happening.

        The create_fiori_client.js script adds the plugins to the project.

        It adds kapsel-plugin-inappbrowser-xwalk which if you look in its C:\SAP\MobileSDK3\KapselSDK\3_13_6\plugins\inappbrowser-xwalk\plugin.xml file has a dependency to

        <dependency id=”cordova-plugin-crosswalk-webview”/>

        I am guessing that since this dependency does not list a specific version, the latest available version is added to the project which is 2.2.0.

        I would recommend changing the dependency to be
        <dependency id=”cordova-plugin-crosswalk-webview@2.0.0″/>
        and then recreate the Fiori Client.

        This worked for me.  Hope it helps.  I have also opened a bug to have the development team follow up further on this.

        Regards,

        Dan van Leeuwen

         

        (0) 
        1. Patrick Bierbaums

          Thanks a lot for your help. I did the change and created a new project successfully. The APKs could also be built without problems, but when i deployed it to an Android Emulator (ARM (armeabi-v7a)) it can be installed, but crashes on start with message “FioriClient has stopped”.

          I will try to deploy it to an actual device tomorrow, but I expect the same outcome, as it is the same problem I described in my initial comment as well.

          I tried using command “cordova build android” as well as the build.bat, but it made no difference. The appConfig.js, has not been changed.

          Update: Installed the app on an actual device today  and it works! Thanks a lot!

          (0) 
  3. Raj Vikrant

    Hello Daniel,

    Thanks for writing a detailed blog.

    In our case we want to achieve mutual authentication between Custom Fiori Client on mobile Device (android & iOS) and Reverse Proxy server. This means Server will challenge client for X.509 cert and client has to read it from device and present it.
    As per your blog, to achieve X.509 certificate based authentication, we need to build a custom fiori client having custom certificate provider.

    But Standard Fiori client user guide says that it supports mutual authentication. Also release notes for SDK SP09 says AuthProxy Plugin automatically selects client certificate.Also there is one of the SAP Note 2132513,  which explains on similar lines.

    I am assuming custom fiori client should be replica of standard and hence it should also support mutual authentication by default. 

    Can you please clarify if we need to code anything to achieve mutual authentication between Custom Fiori client on Mobile Device(android + iOS) OR it works out of the box?

    Regards,
    Vikrant

    (1) 
    1. Daniel Van Leeuwen Post author

      Are you using a customFiori Client?  If so, modify the appConfig.js file and change the disablePasscode value to true.

      I assume you could also set this via a URL parameter when you specify the Fiori Client URL if you are using the App Store Fiori Client.

      Regards,

      Dan van Leeuwen

      (0) 
  4. Seenu Katha

    Hi Dan,

    I am trying to create a Custom Fiori Client for offline usage using which I can login and send data to GW &ECC. For this project, offline functionality is a must.

    I see that odata can be made offline using SMP/HCP with defining requests.
    I also see that Fiori can be made offline using MobileSecure.
    https://blogs.sap.com/2016/06/02/get-your-fiori-crm-app-offline-part-1/comment-page-1/#comment-357024

    But I would like combine both.

    So I first followed the steps to download Fiori content from front end server.
    Then to this project, I am adding android platform and plugins required.
    Then I am adding odata plugin to make odata offline.
    Then I will create android.apk file and install on Android phone.
    Then in SMP/HCP, I am adding define requests for odata offline.

    But It is not working for me. It gives me the registration error on SMP.
    I also want to understand, when we make odata calls from Fiori controller.js, where does it saves the data using offline store?

    When we use offline template from webide, it creates an offline store in fiori code. But it does not require SMP/HCP. So do we still need to write code manually to create an offline store in fiori js files?

    Pls guide me.

    Thanks
    seenu

    (0) 
    1. Daniel Van Leeuwen Post author

      The Fiori Client is meant to be used in an online manner.

      If you wish to write a custom app and use it for offline scenarios that is certainly possible using the Kapsel Offline plugin.

      Note the Offline plugin requires an SMP or HCPms server.

      If you are using a standard SAP Fiori app, I would first check if it supports offline usage.  Not all standard Fiori apps are supported in an offline scenario.  There are certain OData calls that are not supported.
      See http://help.sap.com/saphelp_smp3013sdk/helpdata/en/88/9d29b3fac0456b812d86b5794c6e54/content.htm

      The offline database is created in the server and sent down to the device when you initially open the offline store.

      I am in the process of creating a section in this guide that shows using the offline OData plugin.  Hopefully that will be published before the new year.

      To answer your question, when using the offline OData plugin, OData calls are fetched from the database on the device rather than from the backend server.  When the device is online, a flush and refresh can be made to synchronize the data.

      Regards,

      Dan van Leeuwen

      (0) 
      1. Seenu Katha

        Happy New Year Dan.

        Pls let me know once you add a section about using the offline feature in Custom Fiori Client. That would help immensely to finish my project.

        Thanks
        seenu

        (0) 
        1. Daniel Van Leeuwen Post author

          Just to be clear, the Fiori Client is an application created with the Kapsel SDK.  The Fiori Client is meant to be used in an online manner.  By that I mean it does not contain the web pages that make up the Fiori app that it displays.  It stores some of the files in a cache to speed up load time but does not make all of the files available when offline.  It acts similar to a normal web browser and only caches the files as directed to by the web server.

          If you wish to create an offline app, it is possible to do with the offline plugin but that would be a new app created with the Kapsel SDK.

          Note, there are limitations to the offline plugin that are described here.
          https://uacp2.hana.ondemand.com/doc/d9c75eebcfa840c8a4aa4b0e6a8136de/3.0.14/en-US/889d29b3fac0456b812d86b5794c6e54.html
          The plugin is further described here.
          https://uacp2.hana.ondemand.com/doc/d9c75eebcfa840c8a4aa4b0e6a8136de/3.0.14/en-US/ed65d7f0acbd4ae2bb4bb59e0aa389ad.html

          I hope to add a section to this guide on the offline plugin in the near future.  Here is a link to an older version.  https://blogs.sap.com/2015/07/19/getting-started-with-kapsel-part-10-offline-odata-sp09/

          Regards,

          Dan van Leeuwen

          (0) 
  5. Shivesh Ranjan

    Hi Dan,

     

    I am facing a strange issue while using Custom Fiori Client,

    Technical Environment: KapselSP13PL06, Cordova Version: 6.1.1, SMP : True, SMP Server Version: 3.0, Passcode is Enabled and set by user.

     

    Issue: We have attachment upload functionality in Fiori Application, when we upload the attachment using Android device -> It navigates to Passcode screen. -> After entering the passcode, upload is happening & its a repetitive process whenever I upload new attachment.

     

    Regards,

    Shivesh Ranjan.

    (0) 
    1. Daniel Van Leeuwen Post author

      That is odd.  The one thing I would try taking a look at is the passcode policy and specifically the lock timeout value.  In the management cockpit for the SMP or HCPms server, edit your application and under the Client Policies, enable the passcode policy and then have a look at the lock timeout value.  This should control how long the app can be in the background before the lock screen appears. I think the default is 5 minutes or 300 seconds.

       

      After setting the above go to the settings screen in the Fiori Client and choose Clear All Application Settings.  This should then start a new registration with the server after which the new client policy settings would be in effect for.  They would also come down as part of a settings exchange but it may take a few app restarts before they take effect.

      Hope that helps,

      Dan van Leeuwen

      (1) 
  6. Pavan Hampi

    Hello Dan,

    I have created Fioriclient Application as per steps mentioned above & it’s working.

    Could you please tell me that , the above steps mentioned in documents to create FioriClient app doesn’t required SMP server to deploy the application ?

    Regards,

    Pavan

    (0) 
    1. Daniel Van Leeuwen Post author

      I am not sure I follow you question exactly.  An SMP or HCPms server is optional for the Fiori Client.

      If you wish to deploy a customized Fiori Client you can do so using the Apple App store or the Google Play store.  You could also distribute your app to an internal store perhaps hosted by your company.  I believe functionality to do so is available with the SAP Mobile Secure product.

      You can also simply use the version of the Fiori Client that is already available on the Apple app store or Google play store.

      Regards,

      Dan van Leeuwen

      (0) 
  7. Kanchan Singh

    HI Daniel,

    I am using SMP 3.0 run time SP11 on different system. I am trying to develop app using SAP Fiori Client Plugin.

    I am following the above steps.

    I am trying to create app on cockpit, At Authentication tab–>Authentication Provider

    Select as HTTP/HTTPS Authentication and write my launchpad URL and click on SAVE button. An error is coming “error connecting to URL”, I have already export all certificate on cockpit.

     

    Thanks

    Kanchan

    (0) 
  8. Sandeep K S

    Hi Daniel,

    I tried Custom SAP Fiori Client through SAP Mobile Platform by following the steps mentioned in the above document.

    I’m getting an error “Whitelist Check Failed” while registering.

    Kindly, provide your help on the issue.

    Thanks in Advance.

    Regards,

    Sandeep K S

    (0) 
      1. Sandeep K S

        Hi Daniel,

        Thanks for the reply.

        I tried like the way you mentioned in appConfig.js file. Still, facing the same issue.

         

        Regards,

        Sandeep K S

        (0) 
  9. Rambhupal Koka

    I am trying to install SP14 PL01 but I am getting below error  while executing the  “node create_fiori_client.js” . Can you please advise which version I have to check.

    /users/*****/SAP/moibileSDK3/KapselSDK/apps/fiori_client/node_modules/semver/semvr.js  293

    throw new error Type Error(“Invalid Version: ” + version);

     

    (0) 
  10. Jan Nyfeler

    Hi Daniel

    Thank you very mch for the detailled and informative blog post.

    Supposed you are not using smp or mobile services, no client certificates and the custom fiori client is directly configured for an on premise gateway system.

    What role has the kapsel logon plugin, if any?

     

    From my understanding the custom fiori client then starts the configured url and ends up on the launchpad logon page where the user enters username and password.

    I do not see any participation of the logon plugin in this scenario, correct?

     

    Best regards

    Jan

    (0) 
    1. Daniel Van Leeuwen Post author

      One scenario that comes to mind is if the gateway challenges with basic authentication then the AuthProxy plugin in combination with the Logon plugin can respond with the user credentials.

      See also https://blogs.sap.com/2017/01/17/getting-started-with-kapsel-part-8-authproxysp13/.

      When the logon plugin is used in a direct case, the logon plugin is initialized in a different manner.  There is an example of this at the below link and search for sap.Logon.initPasscodeManager

      https://blogs.sap.com/2016/12/28/getting-started-with-kapsel-part-5-encrypted-storagesp13/

       

      The Logon plugin is required by many of the other Kapsel plugins.  It contains a datavault where secure information may be stored.

      The logon plugin also provides a passcode screen to provide an additional passcode or fingerprint that a user would need to supply before they can access the app.  For the direct case, you can specify what the passcode policy should be in the appConfig.js file.

       

      Regards,

      Dan van Leeuwen

      (0) 
  11. KALYANI CHAGARLAMUDI

    Hi Daniel,

    Thanks for the wonderful blog.I have created a custom fiori client app as per the steps posted.

    Now i see that app is not getting auto refreshed and count on the approval tiles are not getting auto updated after any transaction.I see this this only on the app in iOS device but this is not the behavior in browser.

    I need to manually clear cache for this to get  reflected on the app.

    Can you please let me know how should i handle this.

     

    Thanks in advance.

    (0) 
    1. Daniel Van Leeuwen Post author

      I have not myself come across this problem before.  You may wish to open a ticket with support on this.

      The one option that might have an effect on this is the enableCacheManager setting.  I believe it is mentioned in this blog posting.

      One other option to debug this further would be to use the Safari Web Inspector or Fiddler to examine the networking requests.  You could compare the requests between the case that is working  in the browser and the case that is not working in the Fiori Client.  It may be something about headers on the response do not indicate that the response should not be cached.

      Regards,

      Dan van Leeuwen

      (0) 

Leave a Reply