Part 1: Controller Extension in OAF — How to Add Code on a Button Click Event

Introduction

Controller Extension is a fundamental customization technique in Oracle Application Framework (OAF) that allows you to add custom logic to standard Oracle E-Business Suite pages without modifying Oracle's seeded code. You need Controller Extension when you want to:

Add custom validations to standard processes
Add extra monitoring or auditing to standard transactions
Control the standard page behavior to meet specific business requirements
Execute custom code when a user clicks a standard button

This guide walks you through the complete process of creating a Controller Extension on the Expense Reports Home Page, where we will add custom logic to track how many times an expense report is withdrawn and on which date.

Note: This topic is lengthy, so it is split into two parts:
Part 1 (this article): Identifying the controller, downloading it, and setting up the workspace/project
Part 2: Creating the extended controller, adding the custom code, substituting, and deploying

Part 2 Reference: https://docodi.blogspot.com/p/30b-controller-extension-in-oaf-how-to.html

Test Case: Tracking Expense Report Withdrawals

Business Requirement: Whenever a user withdraws an expense report, the system must create a history record in a custom table that tracks:

How many times the expense report has been withdrawn
The date of each withdrawal
The user who performed the withdrawal

To achieve this, we will extend the standard controller behind the Expense Reports Home Page and add custom code to the Withdraw button click event.

Why Controller Extension?

Reason	Description
No Oracle Code Modification	Extends standard behavior without changing seeded code
Survives Upgrades	Customizations are preserved during Oracle patches and upgrades
Follows Oracle Standards	Uses Oracle's official extension mechanism
Maintainable	Clear separation between standard and custom logic
Reversible	Can be easily removed or disabled if needed

Prerequisites

Before you begin, ensure the following:

Oracle JDeveloper is installed and configured with a valid Runtime Connection
Access to the Oracle E-Business Suite server to retrieve the standard controller
Access to the Java_Top directory on the server
The Expense Reports Home Page is accessible in your EBS environment
A custom table exists to store the withdrawal history (e.g., XX_EXPENSE_WITHDRAW_HISTORY)

Custom Table Structure (Example)

CREATE TABLE XX_EXPENSE_WITHDRAW_HISTORY (
    HISTORY_ID        NUMBER PRIMARY KEY,
    REPORT_ID         NUMBER,
    WITHDRAWN_BY      NUMBER,
    WITHDRAWN_DATE    DATE,
    WITHDRAW_COUNT    NUMBER,
    CREATION_DATE     DATE DEFAULT SYSDATE,
    CREATED_BY        NUMBER
);

Step 1: Identify the Standard Controller

The first step is to determine which controller is behind the standard OAF page you want to extend.

Open the Standard OAF Page:
- Navigate to the Expense Reports Home Page in the Oracle E-Business Suite application
- Note the Withdraw button on the right side of each expense report row
Access "About This Page":
- Scroll to the bottom of the page
- Click on the "About this Page" link
Expand All Sections:
- Click on Expand All to see all details
Find the Controller Name:
- In the Controller section, note the controller name
- In this example, the controller is TrackExpenseReportsCO

Result: You now know the controller name. But you also need its location on the server to perform the extension.

Step 2: Find the Controller Location

Now we need to determine where the standard controller is located under Java_Top.

Locate the Controller Path:
- From the "About This Page" details, identify the full path of the controller
- In this example, the path is:
  text
```
oracle/apps/ap/oie/webui/TrackExpenseReportsCO
```
Verify the Path:
- The path follows the standard OAF package structure:
  - oracle — Oracle's root package
  - apps — Oracle Applications
  - ap — Application short name (Payables)
  - oie — Sub-application (Oracle Internet Expenses)
  - webui — Web UI components

Result: You now know the exact location of the standard controller under Java_Top.

Step 3: Download the Standard Controller

Now copy the standard controller from the Oracle server to your local JDeveloper environment.

Navigate to the Server Location:
- Go to the Oracle server
- Navigate to the Java_Top directory
- Follow the path identified in Step 2:
  text
```
$JAVA_TOP/oracle/apps/ap/oie/webui/
```
Copy the Controller File:
- Locate the file TrackExpenseReportsCO.java (and its associated .xml file, if present)
- Copy it to your local desktop
Create the Same Folder Structure in JDev:
- In your JDeveloper jdevhome directory, navigate to:
  text
```
jdevhome/myprojects/
```
- Create the same folder structure:
  text
```
oracle/apps/ap/oie/webui/
```
- Paste the copied TrackExpenseReportsCO file into this location

Important Rule: You must create the same folder structure in your JDev environment as the standard controller has in the application server's Java_Top. This ensures that the extended controller is placed in the correct package and can be properly substituted.

Step 4: Open JDeveloper

Launch Oracle JDeveloper to begin creating the extension project.

Start JDeveloper:
- Double-click on the JDeveloper executable (e.g., jdevW)
- JDeveloper opens with the default workspace

Step 5: Create the OA Workspace and Project

Now we create the workspace and project for the Controller Extension.

Create a New OA Workspace:
- Right-click on Applications in the Application Navigator
- Select New OA Workspace
Name the Workspace:
- Enter a name (e.g., XXTrackExpenseReportsCO)
- Click OK
Configure the Project:
- The Project Wizard opens automatically
- Click Next
Enter Project Details:
- Project Name: Same as the workspace (e.g., XXTrackExpenseReportsCO)
- Package Path: Choose the same path as the standard controller, but change the application prefix to xx (e.g., xxap instead of ap)
For example:
text
```
xxap.oracle.apps.ap.oie.webui
```

Important: The xx prefix is the standard convention for customizations in Oracle E-Business Suite. It distinguishes your custom code from Oracle's seeded code and ensures your changes are preserved during upgrades.

Complete the Project:
- Click Finish to create the project

Result: Your OAF project is now created and ready for the Controller Extension.

Understanding the Package Naming Convention

The package naming convention for Controller Extension follows this pattern:

<custom_prefix>.<standard_path>

Component	Standard	Custom
Prefix	`oracle`	`xx`
Application	`ap`	`xxap`
Full Package	`oracle.apps.ap.oie.webui`	`xxap.oracle.apps.ap.oie.webui`

Note: The xx prefix is a widely used convention in Oracle E-Business Suite for customizations. Some organizations use a different prefix (e.g., c for custom, or a company-specific prefix). Always follow your organization's naming standards.

Directory Structure Overview

After completing Part 1, your JDev environment will have the following structure:

jdevhome/
└── myprojects/
    └── oracle/
        └── apps/
            └── ap/
                └── oie/
                    └── webui/
                        └── TrackExpenseReportsCO.java  (Standard controller downloaded from server)

And your JDev project will have:

XXTrackExpenseReportsCO/
├── xxap/
│   └── oracle/
│       └── apps/
│           └── ap/
│               └── oie/
│                   └── webui/
│                       └── (Extended controller will be created here in Part 2)
└── XXTrackExpenseReportsCO.jpr (Project file)

Understanding the Extension Mechanism

Controller Extension works through three key mechanisms:

Mechanism	Purpose	How It Works
Controller Extension	Adds custom logic to a standard controller	New controller "extends" the standard controller
Substitution	Replaces the standard controller with the custom one	Project property tells the framework to use the custom controller
Deployment	Makes the custom controller available at runtime	Upload to `Java_Top` and register via XML Importer

How It Differs from VO Extension

Aspect	VO Extension	Controller Extension
Purpose	Add new data fields	Add custom logic/behavior
Extends	View Object	Controller
Package	`server`	`webui`
Substitution	VO substitution	Controller substitution
Personalization	Required to display new field	Not required

Key Insight: Controller Extension allows you to intercept and enhance standard page behavior. When a user clicks the Withdraw button, your custom code runs in addition to the standard code, allowing you to add auditing, validation, or business logic.

Best Practices

Practice	Description
Use the `xx` Prefix	Always use the standard customization prefix for custom code
Match Folder Structure	Create the same folder structure as the standard controller
Download the Latest Controller	Always download the current version of the standard controller
Document the Controller Path	Keep a record of the controller location for future reference
Test in Development	Always test Controller Extensions in a development environment first
Back Up Original Files	Keep backups of the original controller files before substitution
Call Super Methods	Always call `super.processFormRequest()` to preserve standard behavior

Troubleshooting Common Issues

Issue	Possible Cause	Solution
Cannot find the controller	Wrong path in About This Page	Re-check the Controller section details
Controller not found in server	Wrong Java_Top path	Verify the Java_Top location and controller name
Folder structure mismatch	Incorrect directory creation	Ensure the folder structure matches exactly
Project creation fails	Wrong package name	Verify the package follows the `xx` convention
Controller file won't open	Corrupted download	Re-copy the controller file from the server
Wrong controller name	Multiple controllers on page	Verify the correct controller from About This Page

What's Next (Part 2)

Now that you have identified the controller, downloaded it, and set up the project, Part 2 of this guide will cover:

Creating the Extended Controller: Extending the standard controller to add custom code
Adding the Custom Code: Implementing the withdrawal history tracking logic
Substituting the Controller: Replacing the standard controller with the custom one
Uploading the Controller: Copying the extended controller to the Oracle Java_Top location
Registering the Controller: Running the XML Importer script to register the new controller
Testing: Verifying that the custom code executes on the Withdraw button click

Summary

Controller Extension in OAF begins with the following foundational steps:

Identify the Controller: Use "About This Page" to find the standard controller
Find the Location: Determine the controller's path under Java_Top
Download the Controller: Copy the controller from the server to your JDev environment
Create the Workspace: Set up the OA Workspace and Project with the xx prefix
Prepare for Extension: The project is now ready for the extended controller (covered in Part 2)

Why Controller Extension Matters

Controller Extension is one of the most powerful customization techniques in Oracle E-Business Suite development because it:

Preserves Oracle Code: No modifications to seeded Oracle objects
Survives Upgrades: Customizations remain intact after patches and upgrades
Follows Standards: Uses Oracle's official extension mechanisms
Is Maintainable: Clear separation between standard and custom code
Enables Auditing: Allows you to track user actions on standard pages
Enforces Business Rules: Lets you add validations and controls to standard processes

By mastering Controller Extension, you gain the ability to enhance standard Oracle pages with custom logic, auditing, and business rules—without compromising the integrity of the Oracle E-Business Suite environment.

References

Part 1: Controller Extension in OAF — https://docodi.blogspot.com/p/30a-controller-extension-in-oaf-how-to.html
Part 2: Controller Extension in OAF (Continued) — https://docodi.blogspot.com/p/30b-controller-extension-in-oaf-how-to.html
Oracle E-Business Suite Documentation: OA Framework Developer's Guide
Oracle E-Business Suite Documentation: Personalization Guide
Oracle JDeveloper Documentation: Available in the jdevdoc folder
Related Guides: OAF VO Extension, Creating a Hello World Page in OAF, Creating an LOV in OAF

Oracle Apps/DBA

Pages

30a. Controller Extension in OAF: How to Add Code in Controller Extension on Button Click Event – Part 1