Customizing mobile timecards for Oracle EBS (part 2)

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:

1. Modifying ebs.properties: located in Application Resources->Descriptors->ADF META-INF/ebs
2. By means of creating a custom deployment profile
3. 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.

EBS Properties

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).

Allowed customizations

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
• Privacy Policy Link
• 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’ [1] 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:
oracle.ebs.login.branding.applogo.location=.adf/META-INF/ebs/custom/XXX_display-xxhdpi-icon.png

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!

Company Logo

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).

oracle.ebs.login.branding.corporatelogo.style=width:143px; height:83px

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
• Springboard
• 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

This JavaScript file contains key-value pairs for all kinds of text resources used on the login page. One of these is APP_TITLE_TIMECARDS, which is used to store the Timecard app title.

Add a custom app name key-value pair, such as ‘XXAP_TITLE_TIMECARDS’ in this JavaScript bundle. Make sure that this value matches the one specified in the ebs.properties file (QTime). You can optionally add translations for this new key in the other JavaScript files.

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.

Customizing EULA

“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:

1. Copy: Custom-EULA-Generic.html
   1. From: /.adf/META-INF/ebs
   2. To: /.adf/META-INF/ebs/custom
2. Modify the copied Custom-EULA-Generic.html
3. Modify property in ebs.properties: oracle.ebs.login.android.eulahtmllocation
4. Similar for: oracle.ebs.login.ios.eulahtmllocation

Customizing Copyright

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.

Changing Privacy Policy Link

A link to the Privacy Policy can be found on the ‘About Page’. It can be changed easily from the ebs.properties file.

Change property: oracle.ebs.login.branding.privacypolicyurl to point to your company Privacy Policy Page.

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:

oracle.ebs.login.rolecode=UMX|HXC_MBL_TIME_ENTRY
oracle.ebs.login.roleappname=HXC

A change could be to use a custom role, defined in a custom app in Oracle EBS.

oracle.ebs.login.rolecode=UMX|XX_TIMECARD_MBL_ROLE
oracle.ebs.login.roleappname=XX_QA

Conclusion

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.

Follow up

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.

References

[1] Oracle® E-Business Suite Mobile Foundation Developer's Guide, http://docs.oracle.com/cd/E18727_01/doc.121/e69284.pdf

[2] Timecards for EBS,
https://play.google.com/store/apps/details?id=com.oracle.ebs.hr.hxc.timecards&hl=en_GB

[3] Introduction to Oracle Mobile Application Framework, http://docs.oracle.com/middleware/mobile200/mobile/develop-oepe/oepe-maf-about.htm

[4] Using Mobile Application Archives for Enterprise Distribution, https://docs.oracle.com/cd/E26401_01/doc.122/e69284/T660136T660627.htm

About the author Richard Velden

Oracle Fusion Middleware Developer at Qualogy. Specializes in integration and cloud development using Oracle technologies such as: SOA Suite, Service Bus, Integration and Process Cloud.

More posts by Richard Velden