Customizing mobile timecards for Oracle EBS (part 2)Published on: Author: Richard Velden Category: Oracle
In this tutorial we will show how to customize Oracle’s Mobile Timecard app for Oracle E-Business Suite (EBS). In this second part we will focus on performing all kinds of supported customizations in JDeveloper.
Oracle’s Mobile Timecard app for Oracle E-Business has been developed using Oracle Mobile Application Framework (MAF). Oracle offers customers the capability to customize this application for their needs.
Customizing the Mobile Timecards app
Please check part 1 of this tutorial before proceeding.
Basically, for customizing the mobile apps, Oracle has provided a few hooks:
- Modifying ebs.properties: located in Application Resources->Descriptors->ADF META-INF/ebs
- By means of creating a custom deployment profile
- Some restricted modifications to other source and resource files
First we will show where the hooks are. Then we will discuss the components that are allowed to be customized by Oracle.
The first customization hook is the ebs.properties file which can be found in: Application Resources->Descriptors->ADF META-INF/ebs.
This file contains properties and values which can change the look and feel of the application. We will discuss various modifications to this file later.
Creating a new deployment profile
The second customization hook is the deployment profile. Each mobile app comes with seeded deployment profiles for both Android and iOS.
Deployment profiles contain, among other properties, the file locations of icons and splash-screens. To create a custom deployment profile: Application->Deploy->New Deployment Profile.
Then select ‘MAF for Android’ and name the deployment profile accordingly.
Next the deployment profile property page will pop up. Navigate to ‘Android Options’ and set the minimum SDK API level to 16. Keep the deployment profile on ‘Debug’.
Next we change some ‘Application Details’ to change the Application Bundle Id. If you remember, in the previous blog we’ve modified ‘Application ID’ in the maf-application.xml. This ID had to be exactly the same as the one defined in Oracle EBS Mobile Applications Manager.
The deployment profile in JDeveloper also contains an Application (Bundle) Id. This identifier however relates to how the app is stored on the mobile device. It does not necessarily have to be the same as the Application Id in the maf-application.xml.
Oracle recommends to also change this Application Bundle Id to some unique id. For us it seemed logical to keep this the same as the Application Id defined in maf-application.xml. A practical use for changing this Application Bundle ID is when you need multiple versions of this app to run on the same device (for testing).
Now we’ve discussed the two main hooks for customization, we’ll dive into the Oracle allowed customizations.
In this current version (5.0) Oracle only allows customizations which have to do with Corporate Branding. As of yet, no real functional customizations are allowed.
So what can we change?
- Application Logo
- Splash Screen
- Company Logo
- Application Name
- Legal Terms / EULA
- Copyright Information
- Mobile Role
The first few customizations involve adding your own graphical resources (logos/icons).
Custom Icons and Splash Screens
Before we can customize, we first need to create Custom Icons and Splash Screens, available in various different image sizes.
Oracle has some size recommendation for each icon, Splash Screen or logo depending on the platform, and device resolution. For the latest specifications please check ‘Oracle® E-Business Suite Mobile Foundation Developer's Guide’  for details.
Oracle recommends to put custom Splash Screens and app logos in the same folder as the default ones <Application Root Folder>\resources\android or the <Application Root Folder>resources/iOS folder. Oracle also recommends to use the same names, as the default images but prefix our custom logos with XXX_ (e.g.: XXX_Icon-120.png).
For this tutorial we have prepared a Custom Icon, Splash Screen and Company Logo.
The Splash Screen and App Logo have been placed in the <Application Root Folder>\resources\android folder. Please mind that these two resources (App Logo and Splash Screen) should be available in multiple sizes.
The app and the Company Logo are placed into: <Application Root Folder>\.adf\META-INF\ebs\custom
We’ll also copy some logos to different locations later in this article.
Changing App Logo and Splash Screen
The application logo and Splash Screen can be modified using your own custom deployment profile (as created earlier). Select the ‘Application Images’ node in the deployment profile.
In the Application Deployment Profile one can change the Application Icon and Splash Screen for each of the ‘platform display types’.
We have changed the Splash Screen and logo as shown in the screenshot below. The XXX_ files contain a custom Qualogy Icon and Splash Screen.
Changing the App Logo in the About Page
The previous application deployment descriptor modification only changed the initial Splash Screen and the App Logo. The Application Logo is also displayed on the About Page and in the Page Header.
To change the logo on the About Page we need a copy of the logo file with size 152x152 to be placed in /.adf/META-INF/ebs/custom
Then we need to modify ebs.properties and update property: oracle.ebs.login.branding.applogo.location to point to this location. For example:
Changing the App Logo in the Page Header
To modify the Application Logo on the Page Header we need to make a copy of the logo of size 80x80. Make sure the name of the file is: android_app_header_icon.png
Store the file in: <Application Root>\ViewController\public_html\images
You will replace the default App Header from Oracle, with your custom one!
The Company Logo is shown on both the Sign-in Screen, and Server URL screen. Oracle allows us to customize this logo by overwriting the seeded logo by our custom version.
The custom company logo file name should be CorporateLogo.png and it should be placed in both: “/ApplicationController/public_html/resources/images” and “/.adf/META-INF/ebs/custom”
Aspect ratios/size of the corporate logo
In order to show the Company Logo properly in the app we need to modify some style properties. Oracle recommends to take 50% of the height/width of the actual image.
First, for the Server URL screen, we open ebs.properties and modify the following property to change the CSS style of the company logo (our logo size was: 285x165).
Secondly for the Sign-in Page we need to set this style in another file as well.
Open ApplicationController/Web Content/resources/html/ebs-Login.html and modify the height and width of the CorporateLogo image tag:
<img src="../images/CorporateLogo.png" alt="oracle logo" height="83" width="143"/>
Changing the App Name
The App Name, by default Timecards, is shown on the following pages:
- Sign-in Screen
- Server URL screen
- About Page
Changing the App Name can be done just by modifying a property in ebs.properties. For the Sign-in Screen however, different steps need to be taken.
Open the ebs.properties file and update property: oracle.ebs.login.appname
Changing the name for the Sign-in Screen requires some additional effort. Open the login bundle: ApplicationController\Web Content\resources\js\ebs-LoginBundle.js
Next: we open the ebs-Login.js and search for ‘APP_TITLE_TIMECARDS’. This value needs to be replaced with your custom version of the application title.
“When an app is launched for the first time, the End User License Agreement (EULA) or Legal Terms screen appears.” We can customize the EULA in the following way:
- Copy: Custom-EULA-Generic.html
- From: /.adf/META-INF/ebs
- To: /.adf/META-INF/ebs/custom
- Modify the copied Custom-EULA-Generic.html
- Modify property in ebs.properties: oracle.ebs.login.android.eulahtmllocation
- Similar for: oracle.ebs.login.ios.eulahtmllocation
To do so: create a txt file in /.adf/META-INF/ebs/custom/ and call it XXX_ebs-oracleCopyright.txt
In ebs.properties, modify property oracle.ebs.login.branding.copyrightfilelocation to point to this custom txt file.
Change mobile app roles
In our Timecards app the default role for mobile is: UMX|HXC_MBL_TIME_ENTRY
If you require a different role to be set up for your mobile version, use ebs.properties again to change the required role for mobile. You need the following two properties for that:
A change could be to use a custom role, defined in a custom app in Oracle EBS.
Customers may freely use the mobile apps for EBS from Oracle. Minor customizations are supported, but these are all related to basic branding.
Pragmatically making some more intrusive changes will not be supported, but they will work just fine. One could think of the following unsupported, but reasonably safe changes:
- Minor CSS changes
- Changing other icons/logos/images
Bear in mind that such changes need to be re-applied once Oracle releases a newer version of the mobile app. Of course one can choose to keep the older (customized) version, but be aware that Oracle might not support the older version indefinitely. One of the considerations is that the REST services used by Oracle’s mobile apps, are no API’s, such as the ones defined in the Integrated SOA Gateway (ISG). Newer versions of Oracle E-Business Suite therefore might not be API compatible with an older mobile app version.
As we have shown, customizing the seeded mobile apps is only marginally possible/supported. In cases where the existing applications are not sufficient, Oracle also recommends to create your own mobile application.
In our next article we will discuss how to create an entirely new mobile application for Oracle EBS using MAF.
 Oracle® E-Business Suite Mobile Foundation Developer's Guide, http://docs.oracle.com/cd/E18727_01/doc.121/e69284.pdf
 Timecards for EBS,
 Introduction to Oracle Mobile Application Framework, http://docs.oracle.com/middleware/mobile200/mobile/develop-oepe/oepe-maf-about.htm
 Using Mobile Application Archives for Enterprise Distribution, https://docs.oracle.com/cd/E26401_01/doc.122/e69284/T660136T660627.htm