SAP ITSmobile for Android

Enterprise Browser 5.0

Overview

This guide provides instructions for modifying an EB app for Android to work with ITSmobile, the SAP middleware system built around its Internet Transaction Server (ITS). ITSmobile provides browser-based access to SAP's ERP, SRM and other enterprise apps made with the company's proprietary dynpro language. Enterprise Browser apps can be built or adapted to work with ITSmobile, and thereby to access SAP back-end enterprise apps. Doing so requires familiarity with editing the Config.xml and the HTML file(s) of EB apps.

EB 2.x for SAP

Enterprise Browser 2.0 (and later) includes an installation package (EnterpriseBrowser_SAP_signed_v2.0.1.0.apk) with a Config.xml file designed for organizations that are running SAP ITS mobile app(s) on Zebra Android devices. The standard Config.xml file also is included in the package, and can be activated using steps in the config-switching section below.

When migrating SAP apps from Windows Mobile/CE to Android, the most common problems relate to page-fitting and the absence of hardware function keys. To address these issues, organizations often maintain separate applications for different device-screen sizes and build HTML-based buttons to replace the missing hardware keys.

Enterprise Browser 2.x helps address these and other migration issues.

SAP Package Features

Sound support

SAP ITSmobile applications can be configured to play a sound to indicate the success or failure of a transaction, and the EB SAP package can be configured also to play these sounds. If different sounds are desired, DOM injection can be used to play sounds stored on the device.

SAP Keyboards

EB 2.0 (and later) includes SAP-specific keyboard layouts that leverage EB's custom ButtonBar features. This helps to compensate for hardware keys missing from Android devices. The SAP keyboard by default displays a numeric layout whenever the focus of an app is on an input field. The default layout is easily changed by editing the showKeyboard/hideKeyboard JavaScript function in the sapkeyboard.js API.

A function key layout allows SAP users to press function keys from the Software Input Panel (SIP) on demand, eliminating the need to modify the SAP application to include HTML buttons to emulate function keys. Each key on an EB keyboard can easily be configured to issue a keystroke or to run a script. For more information, see the ButtonBar Parameter guide.

Logic in the /android_sap/Sapkeyboard.js file reads the SAP keyboard config paramaters from the Config.xml file and registers for onfocus and keydown events to control keyboard pop-up behavior. It's important to ensure that the functions below are called after showing or hiding a keyboard.

//call to redraw the WebView when keyboard pops up:
metaReceiver.resizeWebviewOnButtonbarShown(); 

//call to redraw WebView when keyboard is hidden:
 metaReceiver.restoreWebviewOnButtonbarHidden();

Configuration Parameters

SAP Keyboard Parameters

KeyboardType

Enterprise Browser 2.5 introduced KeyboardType parameter, which can be used to select a keyboard, button bar, custom Enterprise Keyboard layout or default IME for the app.

Possible Values:

  • Buttonbar enables the EB buttonbar layouts to input data. The desired layout file must be specified in the <buttonxmlfile> tag of the app's Config.xml file.

    
<buttonxmlfile value="file://%INSTALLDIR%/android_sap/ EKBCustomLayouts.encrypted" />

  • EnterpriseKeyBoard (EKB) enables the custom layouts made for Zebra's Enterprise Keyboard to input data. For this setting to work properly, the *.encrypted file containing layouts must be present in the /enterprise/device/settings/ekb/config/ device folder on the device (see EKB Layouts, below).

  • Default activates the default IME in the device for data input.

Examples:


<KeyboardType value="ButtonBar"/>
  // OR
<KeyboardType value="EnterpriseKeyBoard"/>
  // OR
<KeyboardType value="default"/>

EKB Layouts

Keyboard Behavior

Enterprise Browser 2.0 (and later) supports configuration parameters that provide more control over the behavior of SAP apps. Keyboard visibility and custom key layouts are controlled through parameters in the Config.xml file. For more information about using the file, see the Config.xml reference.

To show the SAP keyboard on every page:

<KeyboardVisibility value="alwaysOn"/>

Notes:

  • When KeyboardType is set to "EnterpriseKeyboard," the selected EKB layout shows on every displayed EB page. The layout is hidden when the screen is touched.
  • When KeyboardType is set to "ButtonBar," the buttonbar layout is displayed until quitting Enterprise Browser.

To show keyboard on demand when an input field is in focus:


<KeyboardConfiguration>
    <KeyboardVisibility value="onDemand"/>
      <ondemand>
        <onFocus value="1"/>
      </ondemand>  
</KeyboardConfiguration>


Display the keyboard whenever the F10 key is pressed:


<KeyboardConfiguration>
    <KeyboardVisibility value="onDemand"/>
      <ondemand>
        <onHardwarekeypress value="1"/>
        <HardwarekeyValue value="140"/>
      </ondemand>   
</KeyboardConfiguration>


Display the keyboard by pressing the F10 key OR when focus comes to an input field:


<KeyboardConfiguration>
<KeyboardVisibility value="onDemand"/>
      <ondemand>
          <onHardwarekeypress value="1"/>
           <HardwarekeyValue value="140"/>
                    <onFocus value="1"/>
                 </ondemand>    
</KeyboardConfiguration>


Make the page re-sizable on keyboard pop-up to avoid visibility issues:


<SIP>
  <ResizeOnButtonbar value="1"/>        
</SIP>


Set the page as re-sizable while reserving a minimum safe height for the keyboard:


<SIP>
  <ResizeOnButtonbar value="1"/>
  <ButtonBarMaxHeight value="default"/> 
</SIP>

Notes:

  • If the default SAP keyboard layout is preferred, Zebra recommends using the "default" value for the ButtonBarMaxHeight parameter (as shown immediately above). If a custom layout is to be used, the value should be specified (in pixels) to match the layout height.

  • For MC93 devices running Android 8.O Oreo: disable the SAP custom keyboard (if desired) by updating the sapconfigreader.js file on the device as follows: 

    
// Replace line 66 in the "sapconfigreader.js" file with the JavaScript code below:
//
if(-1 != deviceModel.indexOf("mc92") || -1 != deviceModel.indexOf("mc33") || -1 != deviceModel.indexOf("mc67") || -1 != deviceModel.indexOf("tc20k") || -1 != deviceMo

  • The sapconfigreader.js file is in the following device directory:
    \[InternalStorage]\Android\data\com.zebra.mdna.enterprisebrowser\android_sap

Page Fitting

Like all pixel-based UI elements, SAP ITSmobile UI elements look smaller on high-resolution displays than on low-res ones. A page designed to fill the screen of a 640x480 display will occupy only a portion of a modern high-res display. To compensate, apps running on Enterprise Browser 2.0 (and later) can use the ViewPort parameter, which reads device-specific display settings into the app at runtime.

Example:


<ViewPort>
  <UseWideViewPort value="1"/>
  <ViewPortWidth value="device-width"/>
  <ViewPortInitialScale value="1.0"/>
</ViewPort>


Supported meta tags:

  • UseWideViewPort - Value of "1" applies subsequent meta tags (default=0).
  • ViewPortWidth - Sets the width of the page.
  • ViewPortInitialScale - Sets the zoom level of the page when the app starts.

Possible values:

  • UseWideViewPort
    • 1 (enabled), meta tags (below) are applied
    • 0 (disabled), meta tags are NOT applied (default)
  • ViewPortWidth more info
  • ViewPortInitialScale more info
    • Accepts HTML5-spec viewport settings
    • Number corresponding to fixed initial magnification value (i.e. "1.5" = 1.5x zoom)
    • maximum-scale - caps the magnification value ("=1.0"=no zoom-in)
    • minimum-scale - sets a base magnification value ("=1.0"=no zoom-out)
    • user-scalable - Controls whether user is allowed to zoom (=yes, =no)

Note: Settings above impact all pages.

Force-fit to Screen Width

It's possible that some ITSmobile pages are wider than the viewport (visible area) area of the device, resulting in the need to scroll the screen to see all page elements and a less than ideal user experience. This problem is addressed with the <SapForceFitToScreen> parameter, which arranges horizontally aligned HTML elements vertically. When enabled, ITSmobile pages are forced to render elements within the visible horizontal region, or screen width.

NOTE: This parameter applies only to SAP ITSmobile apps, and might effect CSS styling. Parameter is disabled by default.

Confine page to screen width:


<SapForceFitToScreen value="1"/>
For additional page fitting options, see the DOM injection guide.

Customize Page UI Elements

EB 2.x (and later) provides configuration parameters for controlling the size of UI elements on SAP pages.

These settings impact all pages.

Increase button height:


<SapCustomization> 
    <SapButtonHeight value="30px"/>
</SapCustomization>


Adjust font size:


<SapCustomization>    
  <SapButtonFontSize value="10px"/>      
</SapCustomization>


Adjust a read-only text field:


<SapCustomization>     
  <MobileEditDisabledWidth value="auto"/> 
</SapCustomization>

NOTE: The "auto" setting (default) automatically adjusts a read-only text field for the screen width of the device. This parameter also can accept a fixed-width value (i.e. 20px).

To customize style elements:

Specify desired style changes using a custom CSS file as described in the Custom CSS File section (below). The code below shows how the file name and path should appear using the <customcssfile> tag in the Config.xml file. 


<Applications>
  <Application
  ...  
    <SapCustomization> 
        <customcssfile value="file://%INSTALLDIR%/android_sap/sapstyle.txt"/>
    </SapCustomization>

Custom CSS File

Apps made with Enterprise Browser 2.5 (and later) for Android can employ a custom CSS file to modify certain styles within an SAP app at runtime. By default, a file called sapstyle.txt is stored in the following device folder:

  • %INSTALLDIR%/android_sap/

To modify a style using the custom CSS file:

  1. In the CSS file, change the elements for the style class(es) as desired.

  2. Add the enabled:true tag in the class(es) as the first statement:

    
.MobileButton {
enabled:true;      /*--New style identifier MUST be first statement --*/
width:100%;        /*-- All following styles will apply to this MobileButton class--*/ 
background-color:#A3C1E4;
color:blue;              
font-weight: 400;
}

  3. Save the changes and push the new file to the device, replacing the old file (if any).

The new style is applied the next time the page loads.

Sample SAP CSS File

The section below shows the default CSS file for SAP apps found on the device in %INSTALLDIR%/android_sap/style.txt after EB installation. To activate and any attribute, add the tag enabled:true; within the curly braces {}, modify parameters if desired, save and push the new file to the device. Changes are reflected the next time the effected page(s) are loaded.

To specify and/or change the name and/or location of the sapstyle.txt file, see the <customcssfile> tag section of the Config.xml reference.

  
  /*----------------------------------*/
  /* GENERAL PAGE                     */
  /*----------------------------------*/
  @import url("../ALV_GRID.CSS");

  .MobileUserArea, input {
    font-family:arial;
    font-size:100%;
  }

  .MobileUserArea, textarea {
    font-family:arial;
    font-size:100%;
  }

  /* --- MOBILE BODY -----------------*/
  .MobileBody {
    margin: 0px;
    padding: 0px;
    border-width: 0px;
    background-color:#F5F9FC;
  }

  /* --- MOBILE SCREEN ---------------*/
  .MobileScreen {
    width:100%;
    padding:0px;
    margin:0px;
    border:0px;
  }

  /*----------------------------------*/
  /* Main Areas of Mobile Screen      */
  /*----------------------------------*/

  /* --- CUA AREA --------------------*/
  .MobileCuaArea {
    width:100%;
    background-color:#D9E5F2;
    padding:0px;
    margin:0px;
    border-bottom-style:solid;
    border-bottom-width:2px;
    border-bottom-color:#B3C3CF;
  }

  /* --- USER AREA -------------------*/
  .MobileUserArea {
    table-layout:fixed;
    width:100%;
    overflow-x:auto;
    overflow-y:auto;
  }

  /* ---------------------------------*/
  /* CUA AREA ELEMENTS                */
  /*----------------------------------*/

  /* --- MESSAGE ---------------------*/
  .MobileMessageScreen {
    width:100%;
    background-color:#F5F9FC;
    padding:0px;
    margin:0px;
    border-style:solid;
    border-color:#C40026;
    border-top-width:0px;
    border-left-width:0px;
    border-right-width:0px;
    border-bottom-width:2px;
  }

  .MobileMessageLine {
  }

  /* --- MESSAGE ---------------------*/
  .MobileMessageLogo {
    vertical-align:middle;
    padding-left:3px;
    padding-right:3px;
  }

  /* --- TITLE -----------------------*/
  .MobileWindowTitle {
    font-weight:bold;
    font-size:1.0em;
    padding-left:7px;
    overflow:hidden;
    white-space:nowrap;
  }

  /* --- LOGO im Header --------------*/
  .MobileHeaderLogo {
    background-color:#D9E5F2;
    vertical-align:middle;
    height:16px;
    border:0px;
    padding-left:3px;
  }

  /* --- Include Frame ---------------*/
  .MobileIncludeFrame {
  }

  /* --- Basic Row -------------------*/
  .MobileRow {
    white-space:nowrap;
    vertical-align:middle;
  }

  /* ---------------------------------*/
  /* DYNPRO ELEMENTE                  */
  /*----------------------------------*/

  /* --- SUBSCREENS ------------------*/
  .MobileSubScreen {
    table-layout:fixed;
    width:100%;
    padding:0px;
    margin:0px;
    border:0px;
  }

  /* --- STEPLOOPS -------------------*/
  .MobileStepLoop {
    table-layout:fixed;
    width:100%;
    padding:0px;
    margin:0px;
    border:0px;
  }

  /* --- FRAME -----------------------*/
  .MobileFrame {
    width:100%;
    table-layout:fixed;
    background-color:#D9E5F2;
    padding:0px;
    margin:0px;
  }

  .MobileFrameHeader {
    width:100%;
    background-color:#A3C1E4;
    font-weight:bold;
    padding:0px;
    margin:0px;
    border:0px;
  }

  .MobileFrameHidden {
    width:100%;
  }

  /* --- ACTIVE BUTTON ---------------*/
  .MobileButton {
    width:100%;
    font-weight: 400;
  }

  /* --- DISABLED BUTTON -------------*/
  .MobileButtonDisabled {
    width:100%;
  }

  /* --- EDIT FIELD ------------------*/
  .MobileEdit {
    width:100%;
  }

  .MobileEditMultiline {
  }

  .MobileEditMultilineDisabled {
  }

  .MobileEditMultilineHighlighted {
    color:blue;
  }

  .MobileEditMultilineHighlightedDisabled {
    color:blue;
  }

  .MobileEditMultilineRequired {
    border-color:blue;
  }

  .MobileEditMultilineRequiredHighlighted {
    border-color:blue;
    color:blue;
  }

  .MobileEditDisabled {
    width:100%;
    border-style:solid;
    border-color:#808080;
    border-width:1px;
    color:black;
    background-color:#F5F9FC;
  }

  /* required */
  .MobileEditRequired {
    width:100%;
    border-color:blue;
  }

  .MobileEditRequiredDisabled {
    width:100%;
    border-style:solid;
    border-color:#808080;
    border-width:1px;
    background-color:#F5F9FC;
  }

  /* required + highlighted */
  .MobileEditRequiredHighlighted {
    width:100%;
    border-color:blue;
    color:blue;
  }

  .MobileEditRequiredHighlightedDisabled {
    width:100%;
    border-style:solid;
    border-color:#808080;
    border-width:1px;
    color:blue;
    background-color:#F5F9FC;
  }

  /* highlighlighted */
  .MobileEditHighlighted {
    width:100%;
    color:blue;
  }

  .MobileEditHighlightedDisabled {
    width:100%;
    border-style:solid;
    border-color:#808080;
    border-width:1px;
    color:blue;
    background-color:#F5F9FC;
  }

  /* --- F4 BUTTON -------------------*/
  .MobileF4Button {
    width:1em;
  }

  .MobileF4ButtonDisabled {
    width:1em;
  }

  /* --- SEARCHELP BUTTONS -----------*/
  .MobileSearchhelpButton_Search {
  }

  .MobileSearchhelpButton_SearchDisabled {
  }

  .MobileSearchhelpButton_Cancel {
  }

  .MobileSearchhelpButton_Options {
  }

  .MobileSearchhelpButton_Selection {
  }

  .MobileSearchhelpButton_Sort {
  }

  .MobileSearchhelpButton {
  }

  /* --- SEARCHELP EDIT FIELD --------*/
  .MobileSearchhelpEdit {
  }

  .MobileSearchHelpBody {
  }

  .MobileSearchHelpScreen {
  }

  .MobileSearchHelpUserArea {
  }

  .MobileSearchHelpSortingRow {
    background-color: #f2e1af;
  }

  .MobileSearchHelpRow {
  }

  .MobileSearchHelpRow2 {
    background-color: #D9E5F2;
  }

  .MobileSearchHelpFindResults {
  }

  .MobileSearchHelpMessageLine {
    color: red; font-weight: bold;
  }

  /* --- F4 HELP FIELD ---------------*/
  .MobileF4 {
  }

  .MobileF4Disabled {
  }

  /* required */
  .MobileF4Required {
    border-color: blue;
  }

  .MobileF4RequiredDisabled {
    border-color: blue;
  }

  /* required + highlighted */
  .MobileF4RequiredHighlighted {
    border-color:blue;
    color:blue;
  }

  .MobileF4RequiredHighlightedDisabled {
    border-color:blue;
    color:blue;
  }

  /* highlighlighted */
  .MobileF4Highlighted {
    color:blue;
  }

  .MobileF4HighlightedDisabled {
    color:blue;
  }

  /* --- PASSWORD --------------------*/
  .MobilePassword {
    width:100%;
  }

  .MobilePasswordDisabled {
    width:100%;
  }

  /* highlighted */
  .MobilePasswordHighlighted {
    width:100%;
    color:blue;
  }

  .MobilePasswordHighlightedDisabled {
    width:100%;
    color:blue;
  }

  /* --- LABEL FIELD -----------------*/
  .MobileLabel {
    width:100%;
    white-space:nowrap;
  }

  .MobileLabelHighlighted {
    width:100%;
    white-space:nowrap;
    color:blue;
  }

  /* --- RADIOBOX --------------------*/
  .MobileRadioButton {
    vertical-align:middle;
  }

  .MobileRadioLabel {
    white-space:nowrap;
  }

  /* --- CHECKBOX --------------------*/
  .MobileCheck {
  }

  .MobileCheckLabel {
    white-space:nowrap;
  }

  /* --- LISTBOX ---------------------*/
  .MobileListboxRequiredHighlighted {
    width:100%;
    border-color:blue;
    color:blue;
  }

  .MobileListboxRequiredHighlightedDisabled {
    width:100%;
    border-color:blue;
    color:blue;
  }

  .MobileListboxRequired {
    width:100%;
    border-color:blue;
  }

  .MobileListboxRequiredDisabled {
    width:100%;
    border-color:blue;
  }

  .MobileListboxHighlighted {
    width:100%;
    color:blue;
  }

  .MobileListboxHighlightedDisabled {
    width:100%;
    color:blue;
  }

  .MobileListbox {
    width:100%;
  }

  .MobileListboxDisabled {
    width:100%;
  }

  /* ---------------------------------*/
  /* SYSTEM MESSAGE / MAIL            */
  /*----------------------------------*/
  .MobileSysList {
    width:90%;
    table-layout:fixed;
    background-color:#D9E5F2;
    padding:0px;
    margin:0px;
    border:2px;
    border-color:#B3C3CF;
    border-style:solid;
  }

  .MobileSysListTitle {
    width:100%;
    background-color:#A3C1E4;
    font-weight:bold;
  }

Android Keyboard and DataWedge

The SAP package disables keyboard input by default. Enterprise Browser supports disabling the Enterprise Keyboard layout selected as the default in the Android settings panel. Disable it by setting the Config.xml file parameter as shown below: 


<IME>
  <DisableAllIME value ="1"/>
</IME>

Prevent all keyboard pop-ups:


<IME>
  <DisableAllIME value ="1"/>
</IME>
<SIP>
  <ResizeOnButtonbar value="1"/>        
</SIP>

<KeyboardConfiguration>
<KeyboardVisibility value="onDemand"/>
  <ondemand>
      <onHardwarekeypress value="1"/>
      <HardwarekeyValue value="140"/>
  </ondemand>   
</KeyboardConfiguration>

The first section of the Config.xml code above prevents the keyboard from automatically popping up when the focus moves to an input field, and sets the page as "resizable" so it can adapt if a keyboard does appear. The second section causes the keyboard to appear when the F10 key is pressed (on certain devices).

More information:

Ending SAP Session

It's important to terminate the SAP session when quitting an Enterprise Browser app that accesses ITSmobile. EB 2.x implements a Config.xml tag for this purpose. The SAP package by default is set to terminate an SAP session whenever Enterprise Browser is closed.

Default setting on SAP package:


<DeleteCookiesOnLaunch value="1"/>


Default setting on non-SAP package:


<DeleteCookiesOnLaunch value="0"/>


Locking Screen Orientation

EB 2.0 (and later) can lock an EB app to a specific screen orientation (portrait or landscape). The SAP package by default sets the parameter to "Auto," which locks the app in the "natural" orientation of device (landscape on CC5000, ET55, VC80 and WT6000; portrait on all others). Screen "auto-rotation" is disabled when this parameter is used. More info.

Set screen orientation to "natural" for device:


<ScreenOrientation>
  <LockOrientation value= "Auto"/>
</ScreenOrientation>

KeyDown Actions

EB 2.0 (and later) allows hardware keys of certain Zebra devices to be remapped to perform predefined actions or execute JavaScript code blocks residing on the device or on a server. Hardware keys are remapped in the KeyActions section of the KeyCodeMapping .xml file. See the Keycode Mapping Guide for more information.

Press F8 key to quit the app:


<KeyActions> 
    <KEYACTION  keyvalue="138" action="quit" />
</KeyActions>


Execute JavaScript on KeyDown event


<KeyActions> 
   <KEYACTION  keyvalue="139" action="runscript- zoomscript" />
</KeyActions>


DOM Namespace

Enterprise Browser can inject one or more of its JavaScript APIs into a running ITSmobile app, providing access to virtually any feature available to any other EB app.

See the EB Config Reference for details.

Hide SystemBar

Enterprise Browser allows the System bar (also known as the Navigation bar, which contains HOME, BACK and RECENT buttons) to be hidden, maximizing screen space for apps and helping to prevent the app user from accidentally exiting. By default, the System bar is is hidden in the SAP bundle and displayed in the standard package. The parameter is configured in the app's Config.xml file. See the EB Config Reference for details.

Speech Recognition

EB 2.0 (and later) supports the injection of speech commands into legacy SAP applications using text-to-speech (TTS) technology, allowing apps to speak to app users. Apps also can accept speech inputs via automatic speech recognition (ASR) and execute certain commands on a page, all without modifying the underlying server application. By default, TTS and ASR are disabled in the SAP package. See the Voice Guide for details.

SAP vs. Standard EB Package

The SAP and standard Enterprise Browser .apk files are identical; the differences between the two packages are contained only in their Config.xml files. For organizations with mixed deployments, Zebra recommends deploying the SAP package to all devices and pushing the standard Config.xml file to the EB installation directory of devices that require it. This is because the SAP installation delivers both SAP and standard versions of the Config.xml to the device.

Install directory:

/Android/data/com.zebra.mdna.enterprisebrowser/

SAP config file location:

/Android/data/com.zebra.mdna.enterprisebrowser/android_sap/Config.xml

Standard config file location:

/Android/data/com.zebra.mdna.enterprisebrowser/android_regular/Config.xml

To convert to the standard package from SAP:

  • Copy the Config.xml from android_regular to the EB install directory.

To convert to SAP from the standard package:

  • Copy the Config.xml from android_sap to the install directory.

Note: The /Android/data/com.zebra.mdna.enterprisebrowser/ folder can be replaced with the /%INSTALLDIR%/ substitution variable.

See Also