Friday, June 1, 2007

Extensions in OA framework

1. Introduction
2. What is Oracle Applications Framework?
3. Setting up your Environment
4. How to confirm whether actually go for extension or not?
5. BC4J Extensions
6. Deploying your extensions on the application server



1. Introduction

This purpose of this document is to help its readers understand the extensions in Oracle Applications Framework (OAF) and provide a general guideline as to how to create and deploy extensions in OAF.

This document is created based on experiences while implementing iProcurement module in R11.5.10 for one of US Banking Client.


2. What is Oracle Applications Framework?

Oracle Applications Framework is a development and deployment platform for Oracle Self-Service Web Applications. It is a
100% Java & XML, middle-tier application framework and services for the rapid development & deployment of HTML based applications. This framework is based on MVC archietecture (Model-View-Controller).















Correspondingly, MVC in OA Framework can be categorized as:
View – Common UIX-based HTML components used throughout Applications.
Controller – OA Controller responds to user actions, directs application flow.
Model – Business logic encapsulated in Business Components for Java view objects and entity objects.
OA Framework provides with two main features:

1.Personalizations
2.Extensibility

1. Personalization

Personalization means declaratively tailoring the user interface (UI) look-and-feel, layout or visibility of page content to suite a business need or a user preference.
Note that with personalization we are not adding a custom functional flow to the system. It plainly refers to modifying the User Interface with the capabilities provided by the framework, for a better user experience.

Examples of personalization include:

Changing the order of the column in a UI table
Making certain attributes as read-only
Hiding/Showing certain attributes to the user



2. Extensibility

Extensibility refers to the ability to programmatically extend an application's functionality. In other words, extending the n functionality of an application gives developer the ability of:

· Adding new content or business logic
· Extending/overriding existing business logic

The tool which we use for extending various applications in Oracle Applications 11i is JDeveloper.Oracle Self-Service Web Applications can be customized using extensibility feature as per business requirement, in following two ways:

· Customization by extensions: The Oracle Self-Service Web Applications can be customized as per business requirement by adding the custom code to the extended class of the base class. Oracle support this approach because in case of upgrading or applying any patch, if the base class file is replaced by a new class file, then the custom code will still be present in the extended class.


· Customization by modification: The Oracle Self-Service Web Applications can also be customized as per business requirement by adding the custom code to base class itself. However, Oracle does not support this , because in case of upgrading or applying any patch, if the base class file is replaced, then the custom code is removed and so, is the related functionality. That is why Oracle advises for customization by extensions.
With extension, custom functional flows can be created or existing business logic can be overridden to suit customer needs. Examples of extensions include:

· Extending View Objects in order to include an extra transient attribute.
· Extending Application Modules in order to add a new logic as per business requirement.


3. Setting up your Environment

In order to start with extensions we first have to setup appropriate environment for it, i.e. setup Jdeveloper environment. For setting JDeveloper environment, we follow following steps:

Download the latest version of JDeveloper (OAJdev.zip) which is patched for OA Framework from metalink.(We used 9.0.3 version of JDeveloper) and install it as per the instructions on metalink.

To start Jdeveloper go to JDev\jdevbin\jdev\bin and click
jdevw.exe (For convenience, we can create a shortcut of this icon on desktop.)

Put the dbc file extracted from server from <$FND_TOP>\secure\ and put it in appropriate folder i.e.
\dbc_files\secure
Here, refers to path till “jdev” directory in “jdevhome” directory of JDeveloper

Expand the Connections node in the JDeveloper System Navigator, and then expand the Database node. Right-click on the Database node, and select New Connection... to open the Connection Wizard. Follow the JDeveloper instructions to define a new database connection for the Oracle Applications database identified by the DBC file you selected above.

Please confirm that the dbc file does not contain any slashes in the line:
APPS_JDBC_URL=……
Originally the dbc file contains back slashes in this line it is extracted from Unix database server.



The various information needed to complete the connection wizard can be filled by opening the dbc file and then filling Host name, Port, Sid etc. If you get any errors while making the database connection, again cross check the database entries from dbc file and see that there are no back slashes in line
APPS_JDBC_URL=……
of the dbc file.

In order to set our module related environment in Jdeveloper,make a folder named “myclasses” under path \myclasses
Zip the application top from your UNIX application server specific to your module. Eg., since, we were working on IProcurement, so it was
$JAVA_TOP\oracle\apps\icx

Extract this under \myclasses. Please ensure that we have exactly same directory structure under myclasses folders as the zip file of application top has.

Under the directory structure C:\JDev\jdevhome\jdev there are two folders:
myclasses
myprojects
Ideally myclasses folder contain all the files of the application top related to that module, while in myprojects folder we should put only those packages and files are needed to be run, extended or customized. Also note, once a file in myprojects folder is compiled through jdev, a copy of its class file is automatically placed in myclasses.
But, there are a lot of dependencies between VOs and Eos, so, what we did in our implementation was that we unzipped the application top both in myclasses as well as myprojects folder.

In order to find which page to run, to start Oracle Applications from a specific responsibility, through local Jdev Apache server, login on Oracle Applications home page and click the responsibility specific to your module.
Like in our case it was I- procurement. Click on about the page link on this page in order to find relevant information.


NOTE:The about the page link is by default not available on every page. To make it available, two profile options need to set, to have the link ‘about the page’ and ‘Personalize this Page’ on each OA Page. In order to enable it, set these two profile options:

Personalize Self-service Defn (FND_CUSTOM_OA_DEFINTION) - set to “YES”
FND: Personalization Region Link Enabled - set to “YES”



In the above screenshot you can see the directory structure and exact page (red oval space) that opens up while clicking the I-procurement responsibility. In our case it was
oracle\apps\icx\icatalog\shopping\webui\ShoppingHomePG.xml
Now, make the same directory structure under myprojects folder and copy, paste ShoppingHomePG.xml i.e.
\myprojects\oracle\apps\icx\icatalog\shopping\webui\ShoppingHomePG.xml

Select File > New... to open the New... dialog (shown in the following screenshot). This dialog is also called the New Object Gallery.
Workspace Configured for Oracle Applications highlighted">
Choose General > Workspace Configured for Oracle Applications from the New... dialog, or highlight Workspaces in the Navigator and choose New OA Workspace... from the context menu. We'll be prompted to create an OA workspace. Verify that the default workspace directory name points to our own \myprojects directory, as shown in the following diagram. Modify the workspace file name as well (any name is okay for a workspace, such as Iproc.jws). Check the Add a New OA Project check box.


After you click OK, you will see the Oracle Applications Project Wizard.
In Step 1 of the wizard, verify that the default project directory name points to your own JDEV_USER_HOME\myprojects directory, as shown in the following diagram. Modify the project file name as well (any name is okay for a project, such as OAPjoject2.jpr). Set the default package name to
oracle.apps. Like in our case it was oracle.apps.icx
In Step 2 of the wizard we have to set the database connection and runtime connection. In Step3, Browse the correct dbc file here. Fill the runtime username and password .Fill the application short name specific to your module, like in our case it was “ICX” for iprocurement. (If you are unaware of application short name you can find it out from fnd_application_vl).To fill Responsibility key of the related responsibility (for iprocurement it is SELF_SERVICE_PURCHASING_5), you can login in oracle applications and then
System AdministratoràSecurity: ResponsibilityàDefine
Here query for the Responsibility name to get Responsibility key.




12. In order to add homepage of the responsibility(module), on which we are working to the current project, click the red circled button as shown in screenshot below:

We will browse the page which we found in step 4 in myprojects folder i.e.


\myprojects\oracle\apps\icx\icatalog\shopping\webui\ShoppingHomePG.xml
13. Right click ShoppingHomePG.xml and select Run ShoppingHomePG.xml
14. We will be able to see the homepage of the specific responsibility.
This completes all steps needed to develop suitable environment for extensions in particular page under specific responsibility in Oracle Applications 11i.

4. How to confirm whether actually go for extension or not?
In order to decide whether to actually go about extending a webpage or not, we take an example, which we implemented in I-Procurement. The requirement was that in a standard requisition details page, it looks like the screenshot below



Item number was not available. We had a requirement where we have to introduce an extra column in the table: LinesTableRN named as Item number, which will reveal item number of the item. We added an extra column through personalization, to reveal to item number , but to check whether item number is available in standard view objects of the page ,we have to check its availability in the about this page of the page.
Click “about this page” link, to find out information about various View Objects, application modules and controller objects. We also get information about directory structure and the page from this link. So, we get following information:

Page : /oracle/apps/icx/por/reqmgmt/webui/ReqDetailsPG
Application Module : ReqMgmtAM
Available View Objects : (All view objects that are available in ReqMgmtAM can be used)
Controller object : ReqDetailsCO

In order to analyze whether we need to actually extension or we can solve just by going through personalization, we analyzed all the view objects definitions by clicking each view object through about this page link and search whether item number is available in any view object or not .We found that non of the available view objects had item number, so, we are now confirmed of the approach, extension
We introduced an extra column in the table: LinesTableRN named as Item number, which will reveal item number of the item. We added an extra column through personalization and now we will have to extend any View Object available on the page(we choose ReqDetailsVO) to add an extra an extra transient column called item number and get it populated by some business logic.

5. BC4J Extensions
The best way to start the extensions is to mount the whole package in Jdeveloper. To do it we should browse through the server folder of the package. Like in our case we browsed

/oracle/apps/icx/por/reqmgmt/server

This folder contains a file called server.xml

Sometimes, it happens that some server.xml files are missing in the package which stops us from mounting the package in jdeveloper. In such case raise an SR with Oracle to provide patch for all server.xml files of the module or package your working. We raised it for Iprocurement module, as some server.xml files were missing. As soon as you apply this patch all the server.xml are available.

Now, in order to complete our extensions follow these steps:
1. Create Your New BC4J Package.
In your OAProject2.jpr project, create a new, empty BC4J package named .oracle.apps.icx.por.reqmgmt.server. i.e.
ftu.oracle.apps.icx.por.reqmgmt.server
2. Create Your New View Object (VO) and transient attribute
Create a new VO, named ReqDetailsVO, that extends ftu.oracle.apps.icx.por.reqmgmt.server. ReqDetailsVO i.e.
FtuReqDetailsVO
Create the VO in the ftu.oracle.apps.icx.por.reqmgmt.server
Package. Add transient attribute Item Number to your extended VO.
Substitute new VO FtuReqDetailsVO for the existing VO ReqDetailsVO.For details of how to substitute one VO for another ,look at the steps listed in the
OAF Implementation Guide.
Similarly extend the controller class ReqDetailsCO to FtuReqDetailsCO and a new method in process request () like "ftuItemNumberDisplay". Invoke this method through application module.
Extend the application module ReqMgmtAM TO FtuReqMgmtAM, so that we extend the application module and write our custom logic inside the method "ftuItemNumberDisplay" in FtuReqMgmtAM, in order to retrieve value of Item Number
Run ShoppingHomePG and navigate to the present page in order to see the result of our personalization and extension. We see the following result






6. Deploying your extensions on the application server
In order to deploy your extensions follow these steps:
1. Compile your Java files in JDeveloper and zip up your Java classes to the
<$JAVA_TOP>// oracle/apps/
Hence in our case we, put the all the class files from C:\JDev\jdevhome\jdev\myprojects\ftu\oracle\apps\icx\por\reqmgmt\server
To <$JAVA_TOP> /ftu/oracle/apps/icx/por/reqmgmt/server in the application unix server.
Run the jpx import utility to import substitutions specified in the .jpx definition file to the MDS repository of application server. Hence, in our case we have OAProject2.jpx file which is used for extracting substitutions on application server. For details of how to jpx import utility, look at the steps listed in the OAF Implementation Guide.
Note: Each JDeveloper project has one .jpx file. If you have more than one JDeveloper project where you have created substitutions, you can import the substitutions specified in the respective .jpx file from each project, one after another. If you deploy substitutions for the same component more than once, the latest substitution will take precedence, replacing the existing substitution for that component.
3. Bounce the web server
4. Review your deployed extensions
At this point the deployment of your extension is complete, and you should be able to login to your application to verify that your changes have successfully taken effect.