Using the Login Component to Develop Mobile Apps

Overview

Oracle E-Business Suite Mobile Foundation Login Component (the Login component), available from Oracle E-Business Suite Mobile Foundation Release 4.1, is a library to help you easily develop and test mobile apps developed for Oracle E-Business Suite using Oracle Mobile Application Framework (MAF).

Note: Starting from Oracle E-Business Suite Mobile Foundation Release 7.0, custom apps developed using the Login component can optionally be enabled with push notifications. Oracle E-Business Suite Mobile Foundation uses Oracle Mobile Hub, from Release 9.0 and onwards when an appropriate patch is applied, or Oracle Mobile Cloud Service to provide support for push notifications.

For more details about implementing this feature for the mobile app, see Implementing Push Notifications.

The component implements the following features that are common to all Oracle E-Business Suite mobile apps developed based on Oracle E-Business Suite Mobile Foundation so that you can focus on implementing application functionality.

To better understand how to create custom apps using the Login component or APIs, this chapter includes the following topics:

Understanding the Login Component Features

Oracle E-Business Suite mobile apps, like the self-service web applications, can be accessed only by authorized users of Oracle E-Business Suite. This requires a mobile app user to enter a user name and corresponding password, select an appropriate application responsibility as well as an organization if required before the app can successfully retrieve data from Oracle E-Business Suite. Unlike self-service web applications where the users are taken to a single Oracle E-Business Suite home page from where the users can access an application through its responsibility, mobile apps are designed and implemented for specific application functionalities. Hence, there is no Oracle E-Business Suite home page experience when implementing smartphone apps.

Before using the Login component to develop mobile apps against Oracle E-Business Suite, it is important to understand the following concepts:

Supported User Flows

The Login component provides the following user flows.

  1. Initial Configuration and Context Initialization

  2. Regular Login

  3. Application Reconfiguration

Initial Configuration and Context Initialization

The following diagram illustrates the process flow that a mobile app user goes through while attempting to use the app for the first time:

Mobile Apps Initial Launch Process Flow

the picture is described in the document text

During the initial launch of the app, the user is required to perform the following tasks:

  1. Accept End User License Agreement if the app requires one (optional).

  2. Enter the Server URL to connect to an Oracle E-Business Suite instance.

  3. Enter Oracle E-Business Suite user name and password in the Sign In screen.

  4. Select a responsibility if the app requires one (optional).

  5. Select an organization if the app requires one (optional).

For the tasks that are marked optional, the Login component allows you to remove the tasks in the flow using simple configuration. There are one-time activities in the diagram that are required to be done only when the app is launched for the first time.

Regular Login

Once the app is set up and used successfully for the first time, the user goes through the following flow for all subsequent uses of the app:

Mobile Apps Subsequent Launch Process Flow

the picture is described in the document text

Application Reconfiguration

There may be times when a user wants to use the app against a different Oracle E-Business Suite instance. This is the flow that the user goes through to change the Server URL to point to a different Oracle E-Business Suite instance.

Mobile Apps Launch Process Flow After Reconfiguration

the picture is described in the document text

The user is required to perform the following tasks:

  1. Log in to the app. Go to the Settings screen and then the Connection Details screen.

  2. Tap Change URL to replace the current server URL with a new server URL.

  3. Force the app to close and then launch the app again.

  4. Review the new server URL.

    In this step, you can decide to proceed with the new server URL or cancel the reconfiguration to use the previous server URL if desired.

  5. Enter Oracle E-Business Suite user name and password in the Sign In screen.

  6. Select a responsibility if the app requires one (optional).

  7. Select an organization if the app requires one (optional).

Please note that steps that are marked optional are listed here only if the user originally went through them in the Initial Configuration and Context Initialization.

Mobile App Security

Oracle E-Business Suite mobile apps are secured against Oracle E-Business Suite security model for both Authentication and Authorization. Following are the security features implemented by the Login component to secure your mobile apps against Oracle E-Business Suite.

Authentication

To access Oracle E-Business Suite mobile apps, mobile app users use the same user name and password information that they use to log in to Oracle E-Business Suite self-service applications. Administrators can still choose a specific authentication type for each app based on how the authentication is set up in Oracle E-Business Suite.

The authentication type for each mobile app is configured on the Oracle E-Business Suite server using the Mobile Applications Manager responsibility at the time the app is deployed for users. The authentication type value determines the configuration parameters required to set when configuring your mobile app.

Authorization

If an Oracle E-Business Suite mobile app requires responsibility context to access Oracle E-Business Suite data, then two levels of authorization setup are required:

Configuration File

In order for the Login component to connect to an Oracle E-Business Suite instance and provide secure access to the data for the mobile apps, it requires a set of configuration parameters. The configuration parameters for a given mobile app are set up by the administrators on the Oracle E-Business Suite Server using the Mobile Applications Manager responsibility. The configuration parameters are then downloaded from the Oracle E-Business Suite server by the Login component based on the server URL provided by the user. The most important configuration parameter for a given mobile app is the Authentication Type. Based on the authentication type, the corresponding configuration parameters determine how the authentication works for the mobile app.

Developing Your Mobile Apps Using the Login Component

This section provides the step-by-step instructions on using the Login component to develop custom apps. Specifically, it includes the following topics:

Starting from Oracle E-Business Suite Mobile Foundation Release 7.0 and onwards, you can optionally enable push notifications for your custom apps developed using the Login component. For information on implementing this feature for these custom apps, see Implementing Push Notifications.

Downloading and Using the Login Component

After applying the required patches for developing custom apps, as described in Applying Prerequisite Patches on the Oracle E-Business Suite Server, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2, and performing needed setup tasks on the server side, you can download and use the Login component for your custom app development.

The Oracle E-Business Suite Mobile Foundation Login component developed for Oracle E-Business Suite Mobile Foundation Release 9.1 is available for download from My Oracle Support through Patch 32284288. This patch applies to Oracle E-Business Suite Release 12.1.3 and Release 12.2.

Note: For Oracle E-Business Suite Mobile Foundation (Login component) Release 9.0, you can download it through Patch 30914694. It is also included in the "Oracle E-Business Suite Mobile Application Archive 9.0" software distribution from the Oracle Software Delivery Cloud. For download instructions, see Downloading Mobile Application Archives Files. For Oracle E-Business Suite Mobile Foundation (Login component) Release 8.0, download it through Patch 27958894; for Oracle E-Business Suite Mobile Foundation (Login component) Release 7.0, download it through Patch 26023015.

You can use the downloaded Login component to develop custom apps for Oracle E-Business Suite. This component enables the Oracle E-Business Suite Mobile Foundation client libraries, application template, and sample app.

The following table lists the files contained in the Login component for you to use for custom app development:

Folder Name Subfolder and File Name
maf/project
This folder includes the Login component libraries and other Oracle Mobile Application Framework (Oracle MAF) project files.
Files contained in this folder should be included into your Oracle MAF JDeveloper project.
lib
  • EBSLoginCC.jar

  • EBSLoginLib.jar

  adf/META-INF
  • wsm-assembly.xml

  • maf-config.xml

  • connections.xml

  adf/META-INF/ebs
  • ebs.properties

  • Custom-EULA-Generic.html

  • CorporateLogo.png

  src/META-INF
  • logging.properties

  • maf.properties

  src/Cordova-Plugin-InAppBrowser
This folder contains Cordova plug-in implementation for InAppBrowser.
  ApplicationController/src/META-INF
  • maf-skins.xml

  ApplicationController/public_html/resources
  • html/ebs-Login.html

  • images/CorporateLogo.png

  • css

    • ebs-Login.css

    • EBSMobile-1.1.css

    • EBSMobile-1.1.Android.css

    • EBSMobile-1.1.iOS.css

    • EBSMobile-1.0.css

    • EBSMobile-1.0.Android.css

    • EBSMobile-1.0.iOS.css

  • js

    • ebs-Login.js

    • ebs-LoginBundle.js

    • ebs-LoginBundle_de.js

    • ebs-LoginBundle_es.js

    • ebs-LoginBundle_es_US.js

    • ebs-LoginBundle_fr.js

    • ebs-LoginBundle_fr_CA.js

    • ebs-LoginBundle_it.js

    • ebs-LoginBundle_ja.js

    • ebs-LoginBundle_nl.js

    • ebs-LoginBundle_pt_BR.js

    • ebs-LoginBundle_zh.js


ViewController/public_html/resources
  • js

    • ebs-ControlActions.js

  • images

    • springboard_list.png

maf/template
This folder contains an Oracle JDeveloper project, built with Oracle Mobile Application Framework (MAF) 2.6.3 (or Oracle MAF 2.6.2 for Oracle E-Business Suite Mobile Foundation Release 9.0, Oracle MAF 2.5.0 for Oracle E-Business Suite Mobile Foundation Release 8.0, Oracle MAF 2.4.0 for Oracle E-Business Suite Mobile Foundation Release 7.0) and preconfigured with the Oracle E-Business Suite Login component.
This project can be used as a template to quickly start developing custom mobile apps against Oracle E-Business Suite.
  • EBSMobileAppTemplate.zip

maf/sample
This folder contains an Oracle JDeveloper project, built with Oracle Mobile Application Framework 2.6.3 (or Oracle MAF 2.6.2 for Oracle E-Business Suite Mobile Foundation Release 9.0, Oracle MAF 2.5.0 for Oracle E-Business Suite Mobile Foundation Release 8.0, Oracle MAF 2.4.0 for Oracle E-Business Suite Mobile Foundation Release 7.0) which is a sample mobile app that is implemented using the Login component that can connect to Oracle E-Business Suite.
Please note that the sample app acts as a reference implementation for:
  • Developing an Oracle E-Business Suite mobile app using the Login component

  • Implementing a List of Values (LOV)

  • Implementing a simple search box over List View

  • Implementing error, warning and confirmation messages


You can use the sample app in Oracle JDeveloper to review, deploy, and test against Oracle E-Business Suite.

Important: To use the sample app, ensure that you apply required sample app patches as described in Applying Prerequisite Patches on the Oracle E-Business Suite Server, Oracle E-Business Suite Mobile Apps Administrator's Guide, Release 12.1 and 12.2 for your Oracle E-Business Suite instance. Additionally, the REST services used by the sample app must be deployed. For more information, see:

  • EBSSample.zip

Getting Started with Mobile Application Project

Oracle Mobile Application Framework development knowledge is required for developing custom mobile apps for Oracle E-Business Suite. Refer to the Oracle Mobile Application Framework 2.6.3 Migration Notes (https://www.oracle.com/application-development/technologies/maf/maf263migration.html).

Note: For mobile apps built with Oracle E-Business Suite Mobile Foundation Release 9.0, refer to Oracle Mobile Application Framework 2.6.2 Migration Notes (https://www.oracle.com/application-development/technologies/maf/maf262migration.html). For mobile apps built with Oracle E-Business Suite Mobile Foundation Release 8.0, refer to the Oracle Mobile Application Framework 2.5.0 documentation (https://docs.oracle.com/middleware/maf250/mobile/index.html). For mobile apps built with Oracle E-Business Suite Mobile Foundation 7.0, see Oracle Mobile Application Framework 2.4.0 documentation (https://docs.oracle.com/middleware/maf240/mobile/index.html).

Additional Information: If you are upgrading your mobile apps to Oracle E-Business Suite Mobile Foundation Release 9.1 from Release 4.1 or later, perform the needed tasks as described in Migrating Your Mobile Apps.

You can start your mobile application project in either of the following ways:

Option 1: Using Mobile Application Template (Recommended)

This option uses the mobile application template (EBSMobileAppTemplate.zip) in which the Login component is already set up.

To use the template, unzip the EBSMobileAppTemplate.zip file and open the project file in Oracle JDeveloper. Since the template is already preconfigured with the Login component, in this situation, proceed to Step 3: Setting Up the Sign In Screen directly (skip the first two steps) and then perform the rest of setup tasks described in this chapter.

Option 2: Creating a New MAF Application

Without using the mobile application template, you need to create a new MAF application from scratch in Oracle JDeveloper and then set up the Login component yourself.

Once the MAF application is created, Oracle JDeveloper creates required folders and other artifacts under the workspace folder. You need to perform the following tasks to set up the Login component for your project first and then complete the rest of the tasks described in this chapter:

Step 1: Copying the Login Component Files (Conditional)

When creating a mobile app from scratch without using the mobile application template, you need to create a new MAF application in Oracle JDeveloper and then set up the Login component by copying the Login component files and then including them in your project.

Important: If the mobile application template is used while creating mobile apps, since the template is already preconfigured with the Login component, skip this step and directly proceed to the Step 3: Setting Up the Sign In Screen.

Perform the following steps to copy the Login component files to your newly created MAF application project:

  1. Copy MAF artifacts.

    After the MAF application project is created, the MAF artifacts are automatically generated. Copy these files from the Login component package that contains Oracle E-Business Suite specific content and them replace existing files in your Oracle JDeveloper project.

      Package Directory Filename Destination Directory
    1 maf/project/adf/META-INF wsm-assembly.xml <ApplicationRootFolder>/.adf/META-INF
    2 maf/project/adf/META-INF connections.xml <ApplicationRootFolder>/.adf/META-INF
    3 maf/project/adf/META-INF maf-config.xml <ApplicationRootFolder>/.adf/META-INF
    4 maf/project/src/META-INF logging.properties <ApplicationRootFolder>/src/META-INF
    5 maf/project/src/META-INF maf.properties <ApplicationRootFolder>/src/META-INF
    6 maf/project/ApplicationController/src/META-INF maf-skins.xml <ApplicationRootFolder>/ApplicationController/src/META-INF
  2. Copy the Login component libraries.

    The Login component contains the following two libraries:

    • EBSLoginCC.jar- a MAF feature archive that contains MAF artifacts, such as pages, task flows, and other MAF specific content required for the Login component flows.

    • EBSLoginLib.jar - a Java archive file that contains all Java classes implemented in the Login component.

    Copy the Login component libraries listed in the table to a given destination folder. If the destination folder is not present, you need to create one.

      Package Directory Filename Destination Directory
    1 maf/project/lib EBSLoginCC.jar <ApplicationRootFolder>/lib
    2 maf/project/lib EBSLoginLib.jar <ApplicationRootFolder>/lib
  3. Copy Oracle E-Business Suite artifacts.

    Following files are Oracle E-Business Suite specific implementations required by the Login component. Copy these files to your Oracle JDeveloper project. If the destination folders listed here are not present, you need to create them.

      Package Directory Filename Destination Directory
    1 maf/project/adf/META-INF/ebs ebs.properties <ApplicationRootFolder>/.adf/META-INF/ebs
    2 maf/project/adf/META-INF/ebs Custom-EULA-Generic.html <ApplicationRootFolder>/.adf/META-INF/ebs
    3 maf/project/adf/META-INF/ebs CorporateLogo.png <ApplicationRootFolder>/.adf/META-INF/ebs
    4 maf/project/ApplicationController/public_html/resources/html ebs-Login.html <ApplicationRootFolder>/ApplicationController/public_html/resources/html
    5 maf/project/ApplicationController/public_html/resources/images CorporateLogo.png <ApplicationRootFolder>/ApplicationController/public_html/resources/images
    6 maf/project/ApplicationController/public_html/resources/css ebs-Login.css <ApplicationRootFolder>/ApplicationController/public_html/resources/css
    7 maf/project/ApplicationController/public_html/resources/css EBSMobile-1.1.css
    EBSMobile-1.0.css
    <ApplicationRootFolder>/ApplicationController/public_html/resources/css
    8 maf/project/ApplicationController/public_html/resources/css EBSMobile-1.1.Android.css
    EBSMobile-1.0.Android.css
    <ApplicationRootFolder>/ApplicationController/public_html/resources/css
    9 maf/project/ApplicationController/public_html/resources/css EBSMobile-1.1.iOS.css
    EBSMobile-1.0.iOS.css
    <ApplicationRootFolder>/ApplicationController/public_html/resources/css
    10 maf/project/ApplicationController/public_html/resources/js ebs-Login.js <ApplicationRootFolder>/ApplicationController/public_html/resources/js
    11 maf/project/ApplicationController/public_html/resources/js ebs-LoginBundle.*
    (All files)
    <ApplicationRootFolder>/ApplicationController/public_html/resources/js
    12 maf/project/ViewController/public_html/resources/js ebs-ControlActions.js <ApplicationRootFolder>/ViewController/public_html/resources/js
    13 maf/project/ViewController/public_html/resources/images springboard_list.png <ApplicationRootFolder>/ViewController/public_html/resources/images
    14 This copy step is completed after the app image is prepared, as described in Step 6: Integrating with the Springboard. android_app_header_icon.png <ApplicationRootFolder>/ViewController/public_html/resources/images
  4. Copy Cordova plug-ins.

    Copy the maf/project/src/Cordova-Plugin-InAppBrowser folder to <ApplicationRootFolder>/src/.

Step 2: Setting Up the Login Component Libraries (Conditional)

Similar to copying the component files, this step is required only if you do not use the mobile application template to create your mobile apps. If the template is used, skip this step and proceed to Step 3: Setting Up the Sign In Screen.

After copying the Login component files to your project, perform the following tasks to include them in your MAF project:

Important: The Login component is configurable by using the ebs.properties file to utilize its features. Refer to Supported Properties for the Login Component.

  1. Create the file system connection.

    1. In Oracle JDeveloper, select Window and click Resources to open the Resources window.

    2. Click the folder icon with the + sign, then IDE Connections, and then click File System.

      Oracle JDeveloper Navigation Menu with File System Selected

      the picture is described in the document text

    3. In the Create File System Connection window, enter the following information:

      Create File System Connection Window

      the picture is described in the document text

      • Connection Name: Enter the connection name, such as "EBSCCLibraryPath".

      • Directory Path: Enter the directory path information that points to the lib folder under the application's root where you have copied the EBSLoginCC.jar file.

        The directory path should point only up to the lib folder.

    4. In the Resources window, select the IDE Connections panel. Expand File System and then EBSCCLibraryPath to locate the EBSLoginCC.jar file.

      Resources Window with the EBSLoginCC.jar File Selected

      the picture is described in the document text

    5. Save your work.

  2. Include the Login component archive as an application library.

    1. In Oracle JDeveloper, select your MAF application under the Applications window.

    2. Right click the EBSLoginCC.jar file in the Resources window.

    3. Add it to Application and select Application Library.

    4. Confirm that EBSLoginCC.jar is added as an application library by checking the Application Resources panel and then expanding the Libraries folder.

      Application Resources Window with EBSLoginCC.jar in the Libraries Folder

      the picture is described in the document text

    5. Save your work.

  3. Include the Login component library in the ApplicationController project's Classpath.

    1. In Oracle JDeveloper, right click the "ApplicationController" project.

    2. Select Project Properties from the menu. The Project Properties dialog box appears.

      Select Libraries and Classpath and then click Add JAR/Directory.

      The Add Archive or Directory dialog box appears.

    3. Locate the EBSLoginLib.jar folder from the application's lib folder and click Select to add the selected EBSLoginLib.jar folder.

    4. Confirm that the EBSLoginLib.jar folder is included and click OK.

      Libraries and Classpath Window with EBSLoginLib.jar Highlighted in the ApplicationController Project's Classpath

      the picture is described in the document text

    5. Save your work.

  4. Include the Login component library in the ViewController project's Classpath.

    1. In Oracle JDeveloper, right click the "ViewController" project.

    2. Select Project Properties from the menu. The Project Properties dialog box appears.

      Select Libraries and Classpath and then click Add JAR/Directory.

      The Add Archive or Directory dialog box appears.

    3. Locate the EBSLoginLib.jar folder from the application's lib folder and click Select to add the selected EBSLoginLib.jar folder.

    4. Confirm that the EBSLoginLib.jar folder is included and click OK.

      Libraries and Classpath Window with EBSLoginLib.jar in the ViewController Project's Classpath

      the picture is described in the document text

    5. Save your work.

  5. Include the Login component feature archive into your app's maf-application.xml. All these features are required in order for the Login component to work correctly.

    1. In Oracle JDeveloper, select your mobile application project.

    2. In the Applications Navigator, expand the Application Resources panel, then the Descriptors folder, and then the ADF META-INF folder.

      Double click to open the maf-application.xml file.

    3. In the overview editor of the maf-application.xml file, select Feature References from the left panel.

    4. Add the following features in the order of sequence listed here:

      1. oracle.apps.fnd.mobile.login.EULA

      2. oracle.apps.fnd.mobile.login.Config

      3. oracle.apps.fnd.mobile.login.ConfigSecured

      4. oracle.apps.fnd.mobile.login.ResponsibilityPicker

      5. oracle.apps.fnd.mobile.login.Springboard

      6. oracle.apps.fnd.mobile.login.About

      7. oracle.apps.fnd.mobile.login.Signout

      8. oracle.apps.fnd.mobile.login.ConnectionDetails

      9. oracle.apps.fnd.mobile.login.Diagnostics

      Important: For the application features you will be creating later for your app, include those features after the Login component's default features.

    5. Make sure "Show on Springboard" is set to "true" and "Show on Navigation Bar" is set to "false" only for oracle.apps.fnd.mobile.login.About.

      For all other features, ensure that "Show on Navigation Bar" and "Show on Springboard" are both set to "false".

    6. Save your work.

  6. Configure your application with Oracle E-Business Suite login page and server.

    1. In Oracle JDeveloper, select your mobile application project.

    2. In the Applications Navigator, expand the Application Resources panel, then the Descriptors folder, and then the ADF META-INF folder.

    3. Double click to open the maf-application.xml file.

    4. In the overview editor of the maf-application.xml file, select Security from the left panel.

    5. In the Login Page region, enter the following information:

      • Select the "Custom" button.

      • In the Content field, select "HTML Page" from the drop-down list and the ebs-Login.html file for the HTML Page.

        The ebs-Login.html file should be located under your application's ApplicationController/public_html/resources/html folder.

    6. In the Application and Access Control region, select "EBSLoginConn" from the drop-down list for the Application / Configuration Login Server field.

      Security Tab: Login Page Region, KBA Page Region, Application and Access Control Region

      the picture is described in the document text

    7. Save your work.

  7. Perform the following tasks to configure your app with Springboard:

    1. In Oracle JDeveloper, select your mobile application project.

    2. In the Application Navigator, expand the Application Resources panel, then the Descriptors folder, and then the ADF META-INF folder.

    3. Double click to open the maf-application.xml file.

    4. In the overview editor of the maf-application.xml file, select Application from the left panel.

    5. In the Navigation section, enter the following information:

      • Leave the following check boxes unchecked:

        • Show Navigation Bar on Application Launch

        • Show Navigation Bar Toggle Button

      • Springboard: Select the "Custom" button as the value.

      • Feature: Select oracle.apps.fnd.mobile.login.Springboard from the drop-down list as the value.

      • Leave the following check boxes unchecked:

        • Show Springboard on Application Launch

        • Show Springboard Toggle Button

      • Springboard Animation: Select the "Slide" button.

      • Slideout Width: Set it to "250" pixels.

      Application Tab: Navigation Region

      the picture is described in the document text

    6. Save your work.

  8. Perform the following tasks to ensure the Back navigation for Android apps works correctly:

    • Use ebs-ControlAction.js to set all the features.

      1. In Oracle JDeveloper, select your mobile application project.

      2. In the Applications Navigator, expand the ViewController folder, then the Application Sources folder, and then the META-INF folder.

      3. Double click maf-feature.xml.

      4. Select each feature and click the Content tab.

      5. Click the + icon for the Includes region and enter the following values:

        Content Tab: Includes Region

        the picture is described in the document text

        • Type: JavaScript

        • File: resources/js/ebs-ControlActions.js

      6. Repeat this procedure for all the features you include from the Login component as well as the new features you create for your app.

      7. Save your work.

  9. Add managed beans by performing the following tasks:

    1. In Oracle JDeveloper, select your mobile application project.

    2. In the Applications Navigator, expand the ViewController panel, and then the Web Content folder.

      Note: The Web Content folder will not be created until a feature is added in the maf-feature.xml file. If you do not see the Web Content folder under your View Controller project, make sure that you have at least one feature with valid Content added in the maf-feature.xml file.

      Double click to open the adfc-mobile-config.xml file.

    3. Select Overview and then click "Managed Beans" from the left panel.

    4. Add the "SpringBoardBean" managed bean with the following information:

      Name Class Scope
      SpringBoardBean oracle.apps.fnd.mobile.common.springboard.SpringBoardBean application

      Please note that the managed bean classes come from EBSLoginCC.jar.

      Managed Beans Tab: Managed Beans Region

      the picture is described in the document text

    5. Save your work.

Step 3: Setting Up the Sign In Screen

The ebs-LoginBundle.js file that you copied to your MAF project earlier contains translated Application Names for some of the common Oracle E-Business Suite mobile apps.

In order to show your app name in the Sign In screen, perform the following tasks:

  1. In Oracle JDeveloper, select your mobile application project.

  2. In the Applications Navigator, expand the ApplicationController folder, then the Web Content folder, then the resources folder, and then the js folder.

  3. Double click the ebs-LoginBundle.js file.

  4. Add an entry for your app name. For example, 'APP_TITLE_XXAPPNAME' : 'My App',.

    Ensure that there is a comma at the end of the entry if it is not the last entry.

  5. If your mobile app is translated to different languages, you may add the same entry in all other ebs-LoginBundle_<langcode>.js files as well.

  6. Double click the ebs-Login.js file.

    This JavaScript loads translatable app names on the Sign In screen from ebs-LoginBundle.js. You need to change this ebs-Login.js file to reference the translation key from ebs-LoginBundle.js that corresponds to your app, such as APP_TITLE_XXAPPNAME.

    For example, for the Approvals app, string APP_TITLE_APPROVALS is referenced in the following line of code:

    document.getElementById('message').innerHTML = getLocaleMessage('APP_TITLE_XXAPPNAME');

Step 4: Implementing Cordova InAppBrowser Plug-in

The Login component internally uses the Cordova InAppBrowser plug-in to open external URLs within an app. Specifically, implementing this plug-in allows an app to:

Register the plug-in by performing the following steps:

  1. Copy the folder from maf/project/src/Cordova-Plugin-InAppBrowser to <ApplicationFolder>/src.

    Note: If you use the Cordova barcode scanner plug-in for your app, move the barcode scanner plug-in as well to the src folder and re-register it. This helps you organize all the Cordova plug-ins into the same directory.

  2. In Oracle JDeveloper. In the Applications Navigator, expand the Application Resources panel, then the Descriptors folder, and then the ADF META-INF folder.

    Double-click the maf-application.xml file.

  3. In the overview editor that appears, click the Plugins navigation tab.

  4. Go to the Additional Plugins section.

  5. Click the + icon. Navigate to the src folder and then select folder "Cordova-Plugin-InAppBrowser".

    This automatically adds an entry for InAppBrowser.

Additionally, after the registration, perform the following tasks if any of your app pages shows URLs to external websites (open outside MAF's default WebView):

  1. Go to maf-feature.xml and include ebs-ControlActions.js to the feature that you want to open an external URL within an app.

  2. Invoke the Oracle E-Business Suite Mobile Foundation API openURLInAppBrowser in class oracle.apps.fnd.mobile.common.utils.AppsUtil from your managed bean or data control method as follows:

    • Use amx:commandLink to display external URLs to open outside MAF's WebView, such as:

      amx:commandLink text="#{row.fileUrl}" shortDesc="#{common.CC_ATCH_URLATTACHMENT}" actionListener="#{bindings.openURL.execute}"/>

    • In the managed bean or data control method invoke the following Java API with Feature Id and the target URL as input arguments to open the URL outside WebView:

      AppsUtil.openURLInAppBrowser(featureId, url);

Step 5: Setting Up Context Initialization

Responsibility picker and organization picker are part of the context initialization flow for those mobile apps that require the security context to fetch data from Oracle E-Business Suite. While some mobile apps may only require responsibility picker, some mobile apps may require a responsibility followed by an organization before the security context can be initialized.

The Login component provides the context initialization flow only up to the responsibility picker. You can insert any number of steps, after the responsibility picker, into the context initialization flow, such as organization picker followed by department picker and so on before the user is directed to the app's landing page.

You can turn on the responsibility picker for the mobile app using the property oracle.ebs.login.useresppicker=Y in the ebs.properties file. Once the responsibility picker is turned on, based on your app's requirement, you have the following choices:

Important: Oracle E-Business Suite mobile sample app implements organization picker that follows responsibility picker. Developers can use the sample app as a reference.

Context initialization flow is invoked only once when an app is launched for the first time. The selected context parameters, such as responsibility and organization, are saved locally and used to initialize context for every subsequent visit. If a user wants to change the settings, go to the app's Settings screen from Springboard.

Step 6: Integrating with the Springboard

This section describes the instructions on how to show the Springboard toggle icon in the landing pages of all the features accessed from Springboard.

Starting from Oracle E-Business Suite Mobile Foundation 5.0, both iOS and Android apps display the same Springboard toggle icon on the left side of the page header. Therefore, use the following steps to modify the landing pages to show the Springboard toggle icon consistently for both iOS and Android platforms:

  1. No need to add additional styling to <amx:panelPage>. The <amx:panelPage> should be like <amx:panelPage id="pp1">, where the id attribute could have any value.

  2. Add the following information under <amx:panelPage> from where Springboard should be accessed.

    <amx:facet name="primary">
                    <amx:commandLink actionListener="#{applicationScope.SpringBoardBean.goToSpringBoard}"
                            styleClass="ebs-sbList-Button" id="cb2"
                            shortDesc="#{EBSCommonBundle.CC_EBS_SPRINGBOARD}">
                            <amx:image id="i3" source="/resources/images/springboard_list.png"
                              shortDesc="#{EBSCommonBundle.CC_EBS_SPRINGBOARD}"/>
                            <amx:setPropertyListener id="spl3" to="#{pageFlowScope.disable_id}" from="pglListView"/>
                            </amx:commandLink>
    </amx:facet>

    Please note that <amx:setPropertyListener> to #{pageFlowScope.disable_id) is to disable the base page controls when Springboard is displayed. The “from” should be the id of the PGL that contains the controls to disable.

    Following is an example from the Settings screen.

    An Example of the Settings Screen

    the picture is described in the document text

Step 7: Setting Up Mobile App Access Roles

Oracle E-Business Suite mobile apps use role-based access control to allow users who are assigned the appropriate access roles to access Oracle E-Business Suite. To secure your custom apps, you need to set up required app-specific mobile app access roles first. Mobile applications administrators can then assign these roles to responsibilities that will have access to the custom apps.

For information on creating app-specific access roles in Oracle E-Business Suite, see Creating and Using Mobile App Access Roles.

Update the following properties in the ebs.properties file with the role:

For a list of properties supported by ebs.properties, see Supported Properties in the Login Component.

Step 8: Integrating with the Settings Screen

You can create a MAF feature for the Settings screen that a mobile user can access from Springboard. This may include any app-specific settings that can be captured from the user and used by the app.

App-Specific Preferences

In order for mobile apps to maintain app-specific preferences, the Login component provides PreferenceStore APIs in class oracle.apps.fnd.mobile.common.utils.PreferenceStore to store and retrieve preference values in the local database. Some of the use cases of the app-specific settings are:

PreferenceStore APIs

The following are common input parameters for the oracle.apps.fnd.mobile.common.utils.PreferenceStore APIs.

The following table lists the PreferenceStore APIs:

API Description
PreferenceStore.getPreference (String userName, String moduleName, String preferenceName, String preferenceValue, String language); This API inserts the preference value if not already present. If it is already present, it updates the value.
PreferenceStore.getPreference(String userName, String moduleName, String preferenceName, String language); This API returns the preference value as a string.
PreferenceStore.setPreferences(String userName, String moduleName, String preferenceName, String preferenceValues[], String language); This API inserts an array of preference values if not already present. If the given preference name is already present, it erases existing values and stores the new array of values.
PreferenceStore.getPreferences(String userName, String moduleName, String preferenceName, String language); This API returns an array of preference values as a string.
PreferenceStore.deleteUserPreference(String userName, String module, String preferenceName); This API deletes the preference record from the preference store.
PreferenceStore.setDefaultFeature(String userName, String featureId); This API sets the default feature for the user. This value overrides the default feature configured in the ebs.properties file. When the user signs in to the app in subsequent times, the user is navigated to this feature.
PreferenceStore.getDefaultFeature(String username); This AP returns the default feature for the user. This is used internally by the Login component to take the user to the default feature after user signs in to the app.

PreferenceStore APIs Usage

The following are some usage examples of the PreferenceStore APIs:

Default Settings Screen from the Login Component

Apart from any app-specific settings that you can implement, the Login component provides the following features that can also be integrated with app's Settings screen:

Responsibility Picker (Feature Id - oracle.apps.fnd.mobile.login.ResponsibilityPicker)

When displaying a link for the user to change the current responsibility by relaunching the context initialization flow, it is important to show the current selected responsibility name in the Settings screen.

Perform the following tasks to integrate the Settings screen with the context initialization flow:

  1. Show display name of the current selected responsibility in the Settings screen. The following options are available to get the display name of the current responsibility. The current responsibility name is stored in #{applicationScope.ResponsibilityAppScopeBean.respDisplayName}.

    1. Use a backing bean attribute for the outputText field, which will fetch the responsibility display name from the EL.

    2. If the EL is not set, then read the responsibility from the local SQLite database using the following API:

      PreferenceStore.getPreference(null, DAOConstants.APP_USER_PREFERENCES_CCLOGIN_MODULE, ResponsibilityConstants.RESPONSIBILITY_DISPLAY_NAME, null);
  2. When the user taps the Responsibility link on the Settings screen, perform the following steps:

    1. Reset the feature oracle.apps.fnd.mobile.login.ResponsibilityPicker.

    2. Set #{applicationScope.pageFrom} to the Settings feature's Id.

    3. Go to feature oracle.apps.fnd.mobile.login.ResponsibilityPicker.

  3. If you implement a step after the responsibility picker in the context initialization flow, when the user taps Back in that step (for example, the Organization Picker screen or any other screen which is present after the Responsibility Picker screen) in the Settings flow, perform the same steps as listed in the previous step 2.

  4. Use the following code to navigate to the Responsibility Picker screen:

    AdfmfContainerUtilities.resetFeature("oracle.apps.fnd.mobile.login.ResponsibilityPicker");
    AppsUtil.setELString("#{applicationScope.pageFrom}", "Settings");
    AdfmfContainerUtilities.gotoFeature("oracle.apps.fnd.mobile.login.ResponsibilityPicker ");
    

Connection Details (Feature Id - oracle.apps.fnd.mobile.login.ConnectionDetails)

Perform the following steps to integrate the Settings screen with the Connection Details screen provided from the Login component:

  1. Reset the Connection Details feature.

  2. Set the application scope variable #{applicationScope.pageFrom} to the feature Id from which you are navigating away. For example, if you are navigating from the Settings screen to the Connection Details screen, set this variable to the feature Id of the Settings feature.

  3. Invoke AdfmfContainerUtilities.gotoFeature to go to the intended feature.

  4. Use the following code to navigate to the Diagnostics screen:

    AdfmfContainerUtilities.resetFeature("oracle.apps.fnd.mobile.login.ConnectionDetails");
    AppsUtil.setELString("#{applicationScope.pageFrom}", "Settings");
    AdfmfContainerUtilities.gotoFeature("oracle.apps.fnd.mobile.login.ConnectionDetails ");
    

Diagnostics (Feature Id - oracle.apps.fnd.mobile.login.Diagnostics)

Perform the following steps to integrate the Settings screen with the Diagnostics screen provided from the Login component:

  1. Reset the Diagnostics feature.

  2. Set the application scope variable #{applicationScope.pageFrom} to the feature Id from which you are navigating away. For example, if you are navigating from the Settings screen to the Diagnostics screen, set this variable to the feature Id of your Settings feature.

  3. Invoke AdfmfContainerUtilities.gotoFeature to go to the intended feature.

  4. Use the following code to navigate to the Diagnostics screen:

    AdfmfContainerUtilities.resetFeature("oracle.apps.fnd.mobile.login.Diagnostics");
    AppsUtil.setELString("#{applicationScope.pageFrom}", "Settings");
    AdfmfContainerUtilities.gotoFeature("oracle.apps.fnd.mobile.login.Diagnostics ");
    

Local Database Storage

In certain scenarios, you might have to store complex data structures which are not covered by the usage examples for the PreferenceStore APIs discussed earlier. You can create your own tables by leveraging the property oracle.ebs.login.sql and pointing to a SQL file that contains the required DDL statements. The Login component during startup will run this SQL script to create required tables for your app requirements.

Step 9: Setting Up Default Server URL (Optional)

Starting from Oracle E-Business Suite Mobile Foundation Release 8.0 and onwards, you can preconfigure the Oracle E-Business Suite server URL for your custom apps built with the Login component. Once this task is complete, the custom app users no longer need to enter this URL manually after launching the app.

Depending on whether you use Enterprise Mobility Management (EMM) solutions, you can configure the default server URL in the following ways:

Step 10: Implementing Java Classes

Application Lifecycle Listener

The Login component provides default implementation of Application Lifecycle Listener. If you would like to implement your own Application Lifecycle Listener, perform the following tasks to extend the default Lifecycle Listener implementation to make sure the Login component works correctly.

  1. Extend your Application Lifecycle Listener class from the Login component's oracle.apps.fnd.mobile.common.login.CCLoginLifeCycleListenerImpl.

  2. The first statement in the start() method of your Application LifeCycle Listener should be super.start();.

  3. This statement is extremely important to initialize the SQLite database for your app. If you do not include it, your app will not work as expected.

Step 11: Using Application Logging

If the diagnostics feature is integrated with the app's Settings screen, it can be used to turn on the app logging. The Diagnostics screen allows users to enable or disable the logging feature. The logs written by the app can then be uploaded to the Oracle E-Business Suite server for administrators or developers to review. Log file corresponding to a mobile app is uploaded to the server with the following parameters:

Administrators can retrieve the uploaded log file from the System Administration responsibility using the module name and the user name who uploaded the log file.

Developers can use the AppLogger APIs (oracle.apps.fnd.mobile.common.utils.AppLogger) shipped with the Login component to write log statements from app code to client log file when logging is enabled.

Only two log levels are supported:

Please note that developers are required to use only the AppLogger APIs to write client logs. Using MAF's logging interface directly is not allowed.

The following table describes the AppLogger APIs:

API Description
logInfo(Class, methodName, message); Write informational messages
logError(Class, methodName, message); Write error messages
logWarning(Class, methodName, message); Write warning messages
logException(Class, methodName, Exception); Write exception messages

Step 12: Implementing Corporate Branding

In order for the mobile app to match with your corporate branding, modify the following items that are controlled by the Login component:

For step-by-step instructions on modifying the app for corporate branding, see Implementing Corporate Branding.

Step 13: Using the Developer Mode

When deploying and testing the mobile apps that use the Login component, you are required to accept the End User License Agreement (EULA) and then enter the Server URL every time. While testing against a development environment, you should be able to easily bypass these steps and go directly to the Sign In screen.

Use the following properties in ebs.properties to enable the developer mode.

Remember to turn off the developer mode when shipping the app for testing. This way the app can connect to any Oracle E-Business Suite environment during the testing.

Migrating Your Custom Mobile Apps

This section describes information on upgrading your mobile app to Oracle E-Business Suite Mobile Foundation Release 9.1 from Release 4.1 or later. It includes the following tasks:

  1. Opening a MAF Application Project

  2. Copying Files without Customization

  3. Copying Files with Customization

  4. (Optional) Enabling Push Notifications (Upgrading to Oracle E-Business Suite Mobile Foundation Release 7.0 or Later Only)

  5. Deploying Your Apps

Step 1: Opening a MAF Application Project

Before you begin, ensure that you read and truly understand the knowledge of migrating a MAF application, refer to the Oracle Mobile Application Framework 2.6.3 Migration Notes (https://www.oracle.com/application-development/technologies/maf/maf263migration.html).

If you have created a custom app with Oracle E-Business Suite Mobile Foundation Release 9.0, you have used Oracle Mobile Application Framework 2.6.2. In order to migrate your Oracle MAF application from Oracle E-Business Suite Mobile Foundation Release 9.0 to Release 9.1, you need to open your MAF application in Oracle JDeveloper with Oracle Mobile Application Framework 2.6.3. This migrates your application from Oracle Mobile Application Framework 2.6.2 to Oracle Mobile Application Framework 2.6.3.

Note: To migrate your Oracle MAF application from Oracle E-Business Suite Mobile Foundation Release 8.0 to Release 9.0, open your MAF application in Oracle JDeveloper with Oracle Mobile Application Framework 2.6.2 instead. This migrates your application from Oracle Mobile Application Framework 2.5.0 to Oracle Mobile Application Framework 2.6.2. To migrate your Oracle MAF application from Oracle E-Business Suite Mobile Foundation Release 7.0 to Release 8.0, open your MAF application in Oracle JDeveloper with Oracle Mobile Application Framework 2.5.0 instead. This migrates your application from Oracle Mobile Application Framework 2.4.0 to Oracle Mobile Application Framework 2.5.0.

Step 2: Copying Files Without Customization

Once you have migrated the application to Oracle MAF 2.6.3, copy the following files from the Login component package to your newly upgraded MAF application.

  1. Copy folder from maf/project/src/Cordova-Plugin-InAppBrowser to the <ApplicationFolder>/src directory.

    Register the plug-in from the maf-application.xml file. See: Step 4: Implementing Cordova InAppBrowser Plug-in.

  2. Copy the following MAF artifacts.

    • maf-config.xml

    • wsm-assembly.xml

    • maf.properties

    • maf-skins.xml

  3. Copy the following the Login component libraries.

    • EBSLoginCC.jar

    • EBSLoginLib.jar

  4. Copy the following Oracle E-Business Suite artifacts.

    • EBSMobile-1.1.css

    • EBSMobile-1.1.Android.css

    • EBSMobile-1.1.iOS.css

    • ebs-ControlActions.js

For detailed instructions, see Step 1: Copying the Login Component Files (Conditional).

Step 3: Copying Files with Customization

Before you start copying the customized files, Oracle recommends that you back up existing files as the references of previous customization for your app.

Copy the following files that you could have customized as part of your implementation for your app:

After copying these files, you need to set up the Login screen, as described in Step 3: Setting Up the Login Screen.

Ensure to redo the customization that you have performed earlier. You can reference the backup files you just created for your previous customization.

Step 4: (Optional) Enabling Push Notifications (Upgrading to Oracle E-Business Suite Mobile Foundation Release 7.0 or Later Only)

After the upgrade and before the deployment, you can optionally enable push notifications, available from Oracle E-Business Suite Mobile Foundation Release 7.0 and onwards, for your upgraded custom apps developed using the Login component.

For information on implementing this feature for your custom apps, see Implementing Push Notifications.

Step 5: Deploying Your Apps

After upgrading your app, you need to redeploy and test the app.

See: Deploying and Testing Mobile Apps.

Deploying and Testing Mobile Apps

After completing the required steps for developing a custom app with the Login component, you can deploy the app for the iOS, Android, or both platforms.

For information on deploying your apps, see Deploying Your Mobile Apps.

You can also use the Login component's developer mode option to quickly deploy and test the app against the development environment.