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

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)
--------------------------------------------------------------------------------
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/mzInternalCustomerSearchByCustomerIdVO

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"