Using OA Extensions to extend existing Apps 11i OA Framework pages (step by step)

[ID 283158.1]

--------------------------------------------------------------------------------

Modified 03-APR-2009 Type BULLETIN Status MODERATED

***
This article is being delivered in Draft form and may contain
errors. Please use the MetaLink "Feedback" button to advise
Oracle of any issues related to this article.
***

PURPOSE
-------
This document are some personal thoughts to describe the steps to add an Extension
to an Apps 11i page using the OA Extensions released with 11.5.10

It is not meant to be a commercial strength application, but simply an simple

exercise to go through the steps to demonstrate some kind of addition to an
existing Apps 11i OA Framework page.

SCOPE & APPLICATION

-------------------
Consultants or Customers who need a guided practise to extend an existing Apps 11i
OAF page

Using OA Extensions to extend existing Apps 11i OA Framework pages (step by step)
--------------------------------------------------------------------------------
I decided to do a simple customization to the "Customer Search" page in the "
iReceivables Internal, Vision Operations (USA)" responsibility

Internal system is a 11.5.10 CU2 VISION installation, with Windows 2000 RDBMS and
middle tier, and also load balanced Linux Middle tier (so I need to deploy Java
code onto both middle tier servers)

STEP BY STEP
------------

Create customization in existing package

-----------------------------------------

1) Create new project

In my simple test, I am creating a new OA Project called "mzExtend"I am using
application shortname "MZ" and responsibility key "MZCUSTOMSSWA" for my project, as
this is already setup on my environment (see Note 216589.1)

In project settings, change the Runner options in configuration section to add the
entry "-Djbo.project=mzExtend" to the end of the line.
Also add "F:\oracle\viscomn\java" to the "Additional Classpath" (this is a shared
network drive to my OA_JAVA directory) You would have to copy the server.xml to
your local PC first, if the Apps 11i instance was on a Unix box.

2) Add existing BC4J Objects to your project

Refer to chapter 9 on the Developers Guide "Extending OA Framework Applications"
The "server.xml" files are shipped with Apps 11i, so you add the server.xml file to
your custom project in order to access the original BC4J objects. You need access
to the original objects in order to select them in the "extends" field when
creating your new object.

Add the file "F:\oracle\viscomn\java\oracle\apps\ar\irec\common\server\server.xml"

to the project. This will create a BC4J Package in your custom project.

For my custom page, I need to create a custom VO and AM

oracle.apps.ar.irec.common.server.InternalCustomerSearchByCustomerIdVO
oracle.apps.ar.irec.common.server.CustomerSearchAM

Create a new VO, extending the original

oracle.apps.ar.irec.common.server.mzInternalCustomerSearchByCustomerIdVO
Manually copy the SQL from the original VO, my customization requires me to
remove the WHERE clause from the original SQL

Create a new AM, extending the original

oracle.apps.ar.irec.common.server.mzCustomerSearchAM
In the view objects selection, add "mzInternalCustomerSearchByCustomerIdVO"

I am modifying these java files, to enable a default selection to show when the
custom page is launched
mzCustomerSearchAMImpl.java
mzInternalCustomerSearchByCustomerIdVOImpl.java

3) Create a new OA Web page called "mzSearchPG.xml"

Simple page, with 4 fields from "mzInternalCustomerSearchByCustomerIdVO"

Add a Page Controller "mzSearchPGCO.java" to send a hard coded customerID to the AM

to show customer data on the page when the page is launched (I told you this was a
simple example :-) ) See java code in Appendix A below.

Run this page through JDeveloper and check it displays the page, with some data on
it..

4) Now I want to deploy this to my Apps 11i instance, so I can run through Apps
itself

a) First copy over the compiled objects, if using your custom scheme, this could be
easiest achieved by copying over the whole of the D:\Jdev_510\jdevhome\jdev\
myclasses\oracle\apps\mz directory to the $OA_JAVA\oracle\apps\mz directory,
although you can be more selective if required
NOTE - it is the "myclasses" files you need to copy (the .class not the .java
files!)
In this case, I have added classes to the existing ar directory structure, so need
to copy the 4 class files from "D:\Jdev_510\jdevhome\jdev\myclasses\oracle\apps\ar\
irec\common\server" to the $OA_JAVA/oracle\apps\ar\irec\common\server directory.

b) I have not yet used the "substitution" mechanism in JDev to use custom objects
rather than the original ones, but had I done so, I would need to load the <Project
Name>.jpx file into the MDS. Follow the instructions in the Developers Guide,
chapter 9 "Deploying Customer Extentions" to do this, but you can use a batch file
like below:-
REM
REM Batch file to set environment to upload JPX file into Apps database
REM Version : 1.0
REM Author : Mike Shaw
 REM Updated : 16th Sept 2004
REM
REM This section is for the PC specific variables
set JDEV_BIN_HOME=D:\Jdev_510\jdevbin
set JDEV_USER_HOME=D:\Jdev_510\jdevhome\jdev
set DB_CONNECTION="(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
(host=hostname.domain.com)(port=1521))(CONNECT_DATA=(SID=VIS)))"
set JPX2UPLOAD=mzExtend
set APPS_PASSWD=apps
REM End of PC specific variables
REM Set PATH to ensure we are using the right Java.exe
set PATH=%JDEV_BIN_HOME%\jdk\bin;%JDEV_BIN_HOME%\jdev\bin;%PATH%
REM This is what we actually want to run...
call jpximport.bat %JDEV_USER_HOME%\myprojects\%JPX2UPLOAD%.jpx -username
apps -password %APPS_PASSWD% -dbconnection %DB_CONNECTION%
pause
REM End of process

This loads the JPX into the MDS, for example to the location

/oracle/apps/ar/irec/common/server/customizations/site/0/mzInternalCustomerSearchBy
CustomerIdVO

To remove the substitution, you would need to use JDR_UTILS, for example
exec
jdr_utils.deleteDocument('/oracle/apps/ar/irec/common/server/customizations/site/
0/mzInternalCustomerSearchByCustomerIdVO');

c) Deploy the XML pages into MDS from local PC. Can use following wrapper script
REM
REM Batch file to set environment to upload XML Page files into Apps
database
REM Version : 1.0
REM Author : Mike Shaw
REM Updated : 27th Jan 2005
REM
REM This section is for the PC specific variables
set JDEV_BIN_HOME=D:\Jdev_510\jdevbin
set JDEV_USER_HOME=D:\Jdev_510\jdevhome\jdev
set JDEV_PROJECT_HOME=%JDEV_USER_HOME%\myprojects
set DB_CONNECTION="(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
(host=hostname.domain.com)(port=1521))(CONNECT_DATA=(SID=VIS)))"
REM example of PAGE2UPLOAD mz\comments\bc4jcomponents\CreateCommentPG
REM can also just specify directory to load all pages in that
directory
set PAGE2UPLOAD=ar\irec\common\server
set APPS_PASSWD=apps
REM End of PC specific variables
REM Set PATH to ensure we are using the right Java.exe
set PATH=%JDEV_BIN_HOME%\jdk\bin;%JDEV_BIN_HOME%\jdev\bin;%PATH%
REM This is what we actually want to run...
call import.bat %JDEV_PROJECT_HOME%\oracle\apps\%PAGE2UPLOAD% -rootdir
%JDEV_PROJECT_HOME% -mmddir %JDEV_BIN_HOME%\jdev\lib\ext\jrad\config\mmd -username
apps -password %APPS_PASSWD% -dbconnection %DB_CONNECTION% -jdk13 -validate
pause
REM End of process

Check they are uploaded OK, using the SQL

REM START OF SQL
 set serveroutput on
set pagesize 132
exec JDR_UTILS.listContents('/oracle/apps/ar/irec/common/server', true);
REM END OF SQL

The following is a general script to look for all pages in your custom schema
REM START OF SQL
set serveroutput on
set pagesize 132
exec JDR_UTILS.listContents('/oracle/apps/mz', true);
REM END OF SQL

d) Create new Function to call the page, for example:

Function Name = MZ_CREATE_COMMENT
User Function Name = mz Create Comment
Type = SSWA JSP Function (JSP)
HTML Call =
OA.jsp?page=/oracle/apps/mz/comments/bc4jcomponents/CreateCommentPG

In my case, I am adding the following:

Function Name = MZ_CUSTOMER_SEARCH
User Function Name = mz Customer Search
Type = SSWA JSP Function (JSP)
HTML Call = OA.jsp?page=/oracle/apps/ar/irec/common/server/mzSearchPG

e) Add function to menu

MZ_CUSTOM_SSWA menu for example.

f) Bounce Apache

g) Test page
Login as user with the responsibility to see the menu
Select the menu function to launch the page and check the results are the
same as from JDeveloper

Create similar customization, in custom schema

----------------------------------------------
I really should have created the above customization in my custom schema, so will
do so now.

Create a new empty BC4J package called

oracle.apps.mz.sanity.server

For my custom page, I need to create a custom VO and AM

Create a new VO, extending the original

oracle.apps.mz.sanity.server.mzSearchVO
Manually copy the SQL from the original VO, my customization requires me to
remove the WHERE clause from the original SQL

Create a new AM, extending the original

oracle.apps.mz.sanity.server.mzSearchAM
In the view objects selection, add "mzSearchVO"

I am modifying these java files, to enable a default selection to show when the
custom page is launched
mzSearchAMImpl.java
mzSearchVOImpl.java

3) Create a new OA Web page called "mzNewSearchPG.xml"

Simple page, with 4 fields from "mzSearchVO"

Add a Page Controller "mzNewSearchCO.java" to send a hard coded customerID to the

AM to show customer data on the page when the page is launched.

Run this page through JDeveloper and check it displays the page, with some data on
it..

4) Deploy the page and java objects to the Apps 11i instance and re-test

5) Once checked that it is working, I am now going to personalize this new screen.
I did not include all the items from the VO in the customization, so will add a new
field to the page directly.

Do a Site level personalization, then add an item.

Type = Stylised Text

ID = ConcatenatedAddress
prompt = Address
VO Attribute = ConcatenatedAddress
VO Instance = mzSearchVO1

On saving this personalization and returning to the page, you will see the Address
text on the page as well

APPENDIX A
--
-- java code for mzSearchPGCO page controller
-- (comments and spacing stripped out)
--
package oracle.apps.ar.irec.common.server.webui;
import java.io.Serializable;
import oracle.apps.fnd.common.MessageToken;
import oracle.apps.fnd.common.VersionInfo;
import oracle.apps.fnd.framework.OAApplicationModule;
import oracle.apps.fnd.framework.OAException;
import oracle.apps.fnd.framework.OAViewObject;
import oracle.apps.fnd.framework.webui.OAControllerImpl;
import oracle.apps.fnd.framework.webui.OADialogPage;
import oracle.apps.fnd.framework.webui.OAPageContext;
import oracle.apps.fnd.framework.webui.OAWebBeanConstants;
import oracle.apps.fnd.framework.webui.beans.OAWebBean;
import oracle.jbo.domain.Number;
public class mzSearchPGCO extends OAControllerImpl
{
public static final String RCS_ID="$Header$";
public static final boolean RCS_ID_RECORDED =
VersionInfo.recordClassVersion(RCS_ID, "%packagename%");
public void processRequest(OAPageContext pageContext, OAWebBean webBean)
{
super.processRequest(pageContext, webBean);
-- NOTE this is hard coded value for quickness and simplicity.
String customerId = "8070";
 OAApplicationModule am = pageContext.getApplicationModule(webBean);
Serializable[] params = { customerId };
am.invokeMethod("initDetails", params);
}
public void processFormRequest(OAPageContext pageContext, OAWebBean webBean)
{
super.processFormRequest(pageContext, webBean);
}
} // end of class

IMPORTANT NOTE
--------------
Ensure you are using the correct version of JDeveloper. Review Note 416708.1 to
confirm the correct patch number

RELATED DOCUMENTS
-----------------
Note 330236.1 "Configuring JDeveloper For Use With Oracle Applications 11i"
Note 357218.1 "Troubleshooting JDeveloper setup for Oracle Applications"
Note 416708.1 "How to found right version of JDeveloper for eBusiness Suite 11i and
12"

SEARCH WORDS
------------
OAF 5.10 11.5.10 OA Framework JDeveloper JDev