Skip Headers

Oracle E-Business Suite Developer's Guide
Release 12.1
Part Number E12897-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Customization Standards

Overview of Customizing Oracle E-Business Suite

This section provides you with standards for building custom application components that integrate with Oracle E-Business Suite. Using these guidelines, you reduce the administrative effort to build and maintain custom components.

Because all Oracle E-Business Suite products are built using Oracle Application Object Library, you should use Oracle Application Object Library, with other Oracle tools, to customize Oracle E-Business Suite. You should be familiar with the concepts presented in the relevant chapters of the Oracle E-Business Suite Developer's Guide.

The following topics are covered:

There are several different ways you might want to customize Oracle E-Business Suite. Some of the most common types of customizations include:

Basic Business Needs

These suggestions provide you with the ability to satisfy the following basic business needs. You should be able to:

Definitions

More information on many of these features is available in the references below.

Overview of Building an Application

Overview of Setting Up Your Application Framework

Customization By Extension

Develop new components for existing Oracle E-Business Suite applications and develop new applications using the development features of Oracle Application Object Library.

Customization by extension can be as simple as copying an existing Oracle E-Business Suite component to a custom application directory and modifying the copy.

Customization By Modification

Also known as "customization in place". Modify existing Oracle E-Business Suite components to meet your specific requirements. Modifications range from changing boilerplate text to altering validation logic.

Important: Oracle E-Business Suite recommends that you avoid doing customization by modification. You should do customization by extension instead. You should be aware that modifications are often not preserved during an upgrade or patch process.

Component

A module of code (such as forms, reports, or SQL*Plus scripts) or an Oracle Application Object Library object (such as menus, responsibilities, and messages), or a database object (such as tables, views, packages, or functions).

Custom Application

A custom application is a non-Oracle E-Business Suite application that is registered with Oracle Application Object Library and typically has (at least) its own directory structure and other components.

Database Object

A table, index, view, sequence, database trigger, package, grant, or synonym.

Application Short Name

A short reference name for your application that contains no spaces. You use an application short name when you request a concurrent process from a form, call Message Dictionary routines, and so on.

Application Basepath

The name of an environment variable that translates into the top directory of your application's directory tree. Oracle Application Object Library searches specific directories beneath the basepath for your application's executable files, including form files.

Application Directory Structure

The hierarchy of directories for an application. The Oracle E-Business Suite directory structures are created when you install or upgrade Oracle E-Business Suite. You create the directory structure for a custom application.

For more information, see: Oracle E-Business Suite Concepts.

Applications Environment Files

Defines the environment variables for your Oracle E-Business Suite installation. The environment files include <dbname>.env and adovars.env (for UNIX platforms). The <dbname>.env file contains application basepath variables for Oracle E-Business Suite products and other environment variables and is regenerated automatically by Oracle E-Business Suite administration utilities. The adovars.env file contains information on virtual directory structures used with web servers and is modified at installation time by applications system administrators to configure users' environments.

Determining Your Needs

Follow these steps to determine your customization needs:

Whenever possible, you should customize by extension rather than by modification. By doing so, you eliminate the risk of overwriting or losing a required piece of application logic or validation in the existing components.

You may customize by modification, but we strongly discourage this. These modifications introduce a level of risk, and are not supported by Oracle Support Services, nor the Applications Division. A simple change in form navigation may eliminate a validation check resulting in data integrity problems, and may be lost during an upgrade or patch.

If you must modify an Oracle E-Business Suite form, your first choice should be to determine whether you can accomplish your modification using the CUSTOM library. You can use the CUSTOM library to modify the behavior of Oracle E-Business Suite forms without making invasive changes to the form code, making your modifications less difficult to upgrade. Modifications you can do using the CUSTOM library include hiding fields, opening other forms from the Zoom button, enforcing business rules, adding choices to the Special menu, and so on.

See: Using the CUSTOM Library

Customization By Extension

Separate your application extensions from Oracle E-Business Suite components for easy identification and to reduce the risk of loss during an upgrade or patch. To keep new components separate, you implement a custom application and make it the owner of the new components.

You may implement one custom application that owns all custom components, or many custom applications that own custom components. For example, you may want to define a custom general ledger application for extensions to Oracle General Ledger, and a custom payables application for extensions to Oracle Payables. Use many custom applications if you will create more than a few components for each Oracle E-Business Suite product. Use a single custom application if you will only create a few components for all Oracle E-Business Suite products.

Follow these steps for each custom application you wish to implement:

See: Overview of Building an Application

Overview of Setting Up Your Application Framework

Documenting New Components

You should document at least the following for each new component:

You thoroughly document each extension to simplify each of the following tasks:

If your custom component is a modified copy of an Oracle E-Business Suite component, you should list the component in the file applcust.txt. This file, located in the $APPL_TOP/admin directory (or platform equivalent), provides a single location for a brief listing of customizations. Oracle E-Business Suite uses this file during patch processes to generate warning messages that customizations are being overwritten or may need to be replaced after the patch. Also, you can use the list to help determine the scope of changes that may be needed to customizations after an upgrade or patch.

The applcust.txt file provides a place to list the original file name and location, the destination file name and location (the customized file), and a brief comment. You do not need to list components that are not customizations of Oracle E-Business Suite components (that is, you do not need to list components of a custom application that did not start with Oracle E-Business Suite files).

Defining Your Custom Application

Use the Applications window to register your custom application. Use an intuitive application name and short name for your custom application; relate the names to the Oracle E-Business Suite application being extended if appropriate. For example: extensions to Oracle General Ledger could belong to a custom application named Custom General Ledger with an application shortname XXGL.

Although your short name can be up to 50 characters, we recommend that you use only four to six for ease in maintaining your application and in calling routines that use your short name.

To reduce the risk that your custom application short name could conflict with a future Oracle E-Business Suite short name, we recommend that your custom application short name begins with "XX". Oracle reserves all three to four character codes starting with the letter O, the letters CP, and the letter E, as well as all names currently used by Oracle E-Business Suite products (query all applications in the Applications window).

See: Register Your Application

Creating Your Custom Application Directory Structure

Use the appropriate operating system commands to create your application directory structure. You should define a release number as part of the application basepath to allow for multiple versions of your custom application in the future. Use the release number of the Oracle E-Business Suite release in your installation, such as 12.0 for Release 12.

Modifying Your Applications Environment File

Modify your applications environment file to define an environment variable for your application basepath. Add your custom application basepath environment variable to the adovars.env file (or platform equivalent), not the <dbname>.env file.

You must restart your Forms Server and your Internal Concurrent Manager after adding your basepath variable and running your new environment file so that Oracle Application Object Library can find your application components.

For more information, see the Oracle E-Business Suite System Administrator's Guide.

Adding New Components

Each time you develop a new component, place it in the correct subdirectory for the appropriate custom application.

For more information, see the Oracle E-Business Suite Concepts Guide.

Adding a Form

You build new forms using Oracle Application Object Library with Oracle Forms to ensure seamless integration with Oracle E-Business Suite. You must start with the TEMPLATE form and follow the Oracle E-Business Suite form development standards described in this manual to ensure user interface consistency between Oracle E-Business Suite and your extensions.

If your extension is a modified Oracle E-Business Suite form, you copy the original form and make your modifications to the copy.

Move your completed (or modified) form to the proper directory for your custom application. Register the form with Oracle Application Object Library, associating it with your custom application, and define a function for your new form.

After you have registered your form and defined a function for it, you can add it to an existing menu (see Modifying an Existing Menu) or call it from a new menu (see Adding Menus and Responsibilities). You can also connect your form to an Oracle E-Business Suite form using Zoom in the CUSTOM library.

Adding a Report or Concurrent Program

You can write concurrent programs (which include both reports and programs) in Oracle Reports, SQL*Plus, PL/SQL, C, Pro*C, and (on some operating systems) shell scripts. You can run your concurrent programs using the Concurrent Processing features of Oracle Application Object Library to provide the same standard scheduling, prioritization, and specialization features found in Oracle E-Business Suite.

You must be familiar with the Concurrent Processing chapters in this manual before writing your concurrent program.

Adding a New Report Submission Form

Oracle Application Object Library provides you with a Standard Request Submission interface for running and monitoring your application's reports and other programs. You no longer need to design and maintain special forms to submit concurrent programs. Use the Submit Request window to submit reports. If you create custom menus in your application, be sure that the Submit Request window is on your menu.

If you want to submit your report or program from a custom form, Oracle Application Object Library provides a standard routine to submit a concurrent program to the concurrent manager from within an Oracle Forms trigger. A custom report submission form should provide validation for each parameter value a user can specify.

Adding Online Help

For Release 12, Oracle E-Business Suite provides online help in HTML format. You can easily extend Oracle E-Business Suite online help following the guidelines in the Oracle E-Business Suite System Administrator's Guide - Configuration. If you extend the online help you will need to repropagate your custom files after upgrading.

If you have built a custom application with custom forms and you want to create context-sensitive online help for your custom application, you can build a help system for your application.

See: Building Online Help for Custom Applications

Adding Menus

You can define new menus to call your new forms and Oracle E-Business Suite menus and forms. We recommend that you always enter your custom application short name as part of the (hidden) menu name when you define new menus to help clarify which menus are yours and to help avoid collision with future Oracle E-Business Suite menu names. During an upgrade, all menus created by Oracle E-Business Suite are deleted, even if you have modified them or created all new menu options. Patches may also affect Oracle E-Business Suite menus.

See: Overview of Menus and Function Security

Adding Responsibilities

You can define new responsibilities using the Responsibilities window in the Oracle E-Business Suite System Administrator responsibility. You should create new responsibilities for your custom menus and forms. You can associate these custom responsibilities with your custom application or an Oracle E-Business Suite application. Your custom responsibility is preserved across upgrades, regardless of which application it is associated with.

For more information, see the Oracle E-Business Suite System Administrator's Guide - Security.

Adding Message Dictionary Messages

You can define your own messages in Message Dictionary. Always associate new messages with your custom application (use your own application name when you define the message). During an upgrade, all custom messages associated with an Oracle E-Business Suite product are deleted. Messages associated with your custom application are not deleted.

See: Overview of Message Dictionary

Customization By Modification

You modify Oracle E-Business Suite components only when you cannot meet a requirement using Oracle E-Business Suite features and customization by extension is not an option. You must not modify any component without a thorough understanding of the processing logic and underlying database structure for that component. Modifications to Oracle E-Business Suite components introduce a level of risk, and are not supported by Oracle Support Services, nor the Oracle E-Business Suite Division.

If possible, copy the component to be modified into a custom application and follow the guidelines for customization by extension. If you cannot define the modified component in a custom application, you should preserve a copy of the original. An example of a customization that cannot be performed in a custom application is a report that is submitted from an Oracle E-Business Suite report launch form other than the Submit Request window. When the request to run the report is executed, the concurrent manager expects the report to be in the appropriate Oracle E-Business Suite directory with a particular executable file name because the information that identifies the report is typically hardcoded into the launch form.

Documenting Modifications

You should list each component that you modify in the file applcust.txt. This file, located in the $APPL_TOP/admin directory (or platform equivalent), provides a single location for a brief listing of customizations. Oracle E-Business Suite uses this file during patch processes to generate warning messages that customizations are being overwritten or may need to be replaced after the patch. Also, you can use the list to help determine the scope of changes that may be needed to customizations after an upgrade or patch. The applcust.txt file provides a place to list the original file name and location and a brief comment. For customization files that are copies of Oracle E-Business Suite files (customization by extension), you also include the destination file name and location (the customized file).

In addition to your list in applcust.txt, you should also document at least the following for each component modification:

You thoroughly document each modification to simplify each of the following tasks:

Preserving Original Files

You should avoid customizing Oracle E-Business Suite files "in place". Always make a copy of the file and modify the copy, preferably in a custom application directory.

Before customization, place a copy of the unmodified Oracle E-Business Suite application component in a directory separate from your Oracle E-Business Suite for safekeeping (if you no longer need the modification, you can retrieve the original component). For example, on a UNIX system you create a subdirectory named orig beneath your Oracle E-Business Suite installation directory (the directory denoted by the $APPL_TOP environment variable, which typically includes a release number designation). The directory orig contains application directory structures for each modified component. For example, if you modify Oracle General Ledger form GLXSSMHR, you would copy the original versions of GLXSSMHR.fmb and GLXSSMHR.fmx into the directory $APPL_TOP/orig/gl/forms/<language>.

You need to create the application directories only for modified components. For example, if you do not modify any Oracle General Ledger Oracle Reports reports, you do not need to create the directory $APPL_TOP/orig/gl/reports/<language>.

You do not need to copy components into the orig directory if you copy them into a custom application directory for modification and do not modify the original component in the Oracle E-Business Suite directory.

Modifying an Existing Form

Whenever possible, confine your modification of form behavior to the CUSTOM library. If you must modify the form itself, use the following guidelines (which include guidelines for customization by extension).

Oracle Forms .fmb files are provided for Oracle E-Business Suite products. All Oracle E-Business Suite forms are located in the $AU_TOP/forms/<language> directory. Copy the Oracle E-Business Suite form to a custom application for modifications. Follow these steps, using Oracle Forms Developer and Oracle Application Object Library, to modify a form:

  1. Identify the file

  2. Copy the file to a custom application and rename the file

  3. Preserve the original file

  4. Make the modifications

  5. Comment the form

  6. Generate the form

  7. Register the customization in applcust.txt

  8. Document your customization

See: Using the CUSTOM Library

Identifying the file

Once you select a particular Oracle E-Business Suite form for modification, you must identify the underlying form file. You take the following steps to find the file:

Making modifications

Form modifications fall into three categories: cosmetic, navigational, and functional. Cosmetic changes to screen boilerplate text or to the display characteristics of fields will not impact form processing. You can modify field prompts using the CUSTOM library (because prompts are now properties of items and can be manipulated programmatically). However, reordering fields on a form, or altering field attributes between "non-displayed" and "displayed" (which has the effect of reordering fields) are modifications that should be avoided unless you thoroughly analyze the navigation and trigger firing sequence associated with those fields and ensure that no logic or validation changes will result. You should not remove or disable any form validation logic. You may add validation logic, such as permitting only specific formats or ranges for field entries (though this is best done in the CUSTOM library instead of the form itself).

Note that for many Oracle E-Business Suite forms, most logic is contained in libraries attached to the form (found under $AU_TOP/resource) or in stored packages in the database, and these files may also need to be identified and/or copied and/or modified.

Commenting the form

Oracle E-Business Suite forms provide a routine in the PRE-FORM trigger to document the date and author of form modifications. Oracle Forms also provides the ability to enter form-level comments. You should make use of both of the these features when you modify a form.

The Oracle E-Business Suite FND_STANDARD.FORM_INFO routine in the PRE-FORM trigger looks like:

FND_STANDARD.FORM_INFO('$Revision: <Number>$', 
                   '<Form Name>', 
                   '<Application Shortname>', 
                   '$Date: <YY/MM/DD HH24:MI:SS> $',
                   '$Author: <developer name> $');

You should change the Form Name and Application Shortname arguments to reflect your new file name and custom application. However, this particular application short name affects which online help file the user sees after choosing help for the current window. If you want the user to see the original Oracle E-Business Suite online help for the original form, you should keep the original application short name. The online help is the only feature affected by this instance of the application short name.

Each time you modify the form you should update the Date argument (DATE_LAST_MODIFIED) value to the current date and the Author (LAST_MODIFIED_BY) value to indicate who made the modifications. If the Date entry does not exist, add it. You must not update the revision number, as it identifies the original version of the form on which your modified form is based. The date and revision appear in the Help -> About Oracle Applications window.

You should also add a new entry to the form level comments each time you modify the form. Format your form level comments as follows:

Developer  Date	        Description
------------------------------------------------------------------------
J. Smith   12-SEP-2007  Changed boilerplate in Type region
R. Brown   16-SEP-2007  Added ENTRY_STATUS field with LOV to Type region 

Modifying an Existing Report

Oracle Reports .rdf files are provided for Oracle E-Business Suite products. You should copy the Oracle E-Business Suite report to a custom application for modification. Follow these steps, using Oracle Reports and Oracle Application Object Library, to modify a report:

  1. Identify the file

  2. Make the modifications

  3. Comment the report

  4. Create a concurrent program using your file

Identifying the file

Once you select a particular Oracle E-Business Suite report for modification, you must identify the underlying report file. You take the following steps to find the file:

Making modifications

You may modify reports that do not alter data without risk of affecting your applications. You should have a thorough understanding of the underlying data structures before modification to ensure your customized report produces valid information (see the technical reference manual for your Oracle E-Business Suite product). Before you modify a report that alters data you should have a thorough understanding of the report's processing logic. You may add to the validation logic, but you should not remove or disable any validation logic.

Commenting the report

In SQL*Plus and PL/SQL reports, create a comments section to record changes using remark statements and add a comment for each modification you make:

SQL*Plus and PL/SQL:

REM		Developer    Date       	Description
REM		------------------------------------------ 
REM		J. Smith     12-SEP-2007	Changed column 1 heading 
REM		R. Brown     16-SEP-2007	Added subtotal row 

When you change an existing line(s) of code, comment out the original line(s) and include detailed comments about the change in front of the new line of code, the developer's name, and the date. For example:

SQL*Plus and PL/SQL:

REM		B. Cleaver	11-OCT-2007 
REM		Column entered_dr format 99,999.99 heading 'Dr'
REM		Expanded column width and changed heading
Column entered_dr format 9,999,999.99 heading 'Debit Amount' 

In Oracle Reports reports, add comments using the Report screen. Structure the comments as follows:

Developer     Date           Description
-----------------------------------------------------
J. Smith      12-SEP-2007    Changed column 1 heading
R. Brown      16-SEP-2007    Added subtotal row

Create a Concurrent Program Using Your File

Define a concurrent program executable, a concurrent program using that executable, and assign the program to report security groups.

See: Overview of Standard Request Submission

Modifying an Existing C Program

Oracle does not ship Oracle E-Business Suite C source code. You can add new C and Pro*C programs to Oracle E-Business Suite.

Modifying an Existing PL/SQL Stored Procedure

Modifying Oracle E-Business Suite PL/SQL stored procedures may seriously damage the operation of Oracle E-Business Suite. We recommend that you use Customization by Extension to add new stored procedures or database triggers to accomplish your goals, or use the CUSTOM library if possible. Never alter Oracle Application Object Library objects. Only alter Object Library data using Oracle Application Object Library forms, programs or supported APIs. If you do modify Oracle E-Business Suite stored procedures, you may need to reapply your changes each time you upgrade or patch Oracle E-Business Suite. Also, if you have a problem that requires assistance from Oracle Support Services, you may need to reverse your changes to help isolate the problem.

Modifying Existing Online Help

For Release 12, Oracle E-Business Suite provides online help in HTML format. You can easily modify and extend online help following the guidelines in the Oracle E-Business Suite System Administrator's Guide - Configuration. If you modify existing online help you will need to redo your modifications after upgrading. If you extend the online help you will need to re-propagate your custom file after upgrading.

Modifying Existing Message Dictionary Messages

You should not modify existing Message Dictionary messages. Use Customization by Extension to add new messages associated with your custom application. You can create new messages under an existing Oracle E-Business Suite application, but they will be deleted or overwritten during an upgrade, and you will have to redo them. New Oracle E-Business Suite messages that duplicate your message names (associated with Oracle E-Business Suite products) will overwrite your messages during an upgrade. Custom messages associated with your custom application are preserved.

If you must alter the existing messages, thoroughly document the changes to recreate them after each upgrade or patch.

Modifying Existing Menus and Responsibilities

You should not modify existing menus and responsibilities. Instead, you should define new menus and responsibilities as described in the Customization by Extension section.

You can use a function security report to help duplicate an existing menu and then modify the copy. You can call Oracle E-Business Suite menus and sub-menus from your custom application responsibilities and menus. There are exceptional cases when a reference to an Oracle E-Business Suite menu will become invalid following an upgrade. This occurs when the form, menu, or sub-menu becomes obsolete or its ID changes. You protect against this by running function security reports before upgrading so you have a record of what your menu should call.

Oracle E-Business Suite Database Customization

You may alter your applications database by adding objects. You can also modify existing objects, but we strongly discourage this approach. Any changes made to Oracle E-Business Suite database objects are not supported by Oracle Support Services or the Oracle E-Business Suite Division and may conflict with future releases of Oracle E-Business Suite.

Always make a full backup of your database before doing any customization.

Manipulating Oracle E-Business Suite Data

We strongly recommend that you do not manipulate Oracle E-Business Suite data in any way other than using Oracle E-Business Suite. Oracle E-Business Suite tables are interrelated. When you use Oracle E-Business Suite, any changes made to the data in the Oracle E-Business Suite tables are validated, and any relationships are maintained. When you modify Oracle E-Business Suite data using SQL*Plus or customized applications components, you are at risk of violating the audit ability and potentially destroying the integrity of your data. You must be aware of the potential damaging problems that improper customization may cause.

Modifying Oracle Application Object Library Database Objects and Data

Never alter Oracle Application Object Library objects such as tables or programs. Only alter Oracle Application Object Library data using Oracle Application Object Library forms, programs or supported APIs. Oracle Application Object Library is a data-driven system with complex interrelationships between tables. Any changes you make to Oracle Application Object Library's underlying data may destroy the integrity of your data and the functionality of the application.

Documenting Database Modifications

Define all custom database objects and modifications to existing database objects using SQL*Plus scripts. Place these SQL*Plus scripts in your custom application admin/sql directory. These may include object creation scripts and grant, synonym, view, and object modification scripts. You then use these scripts to rebuild objects following an upgrade or patch and to migrate changes to other Oracle E-Business Suite installations.

Defining Your Custom Application ORACLE ID

When you create new database objects, associate them with your custom application. Define an ORACLE schema (ORACLE ID) specifically for your custom application objects. Use your custom application's application short name as the ORACLE schema name for easy identification. You must register your ORACLE schema with Oracle Application Object Library.

For more information on registering your ORACLE schema, see the Oracle E-Business Suite System Administrator's Guide.

You must use grants and synonyms to allow other ORACLE schemas to access your custom objects and to allow your custom ORACLE ID access to Oracle E-Business Suite objects. When you define a responsibility, you assign a data group to the responsibility. When you use that Responsibility, you connect to its ORACLE schema. Typically, most responsibilities connect to the APPS schema, and you grant privileges on your custom tables to the APPS schema. .

For example, if you define a custom general ledger application, with a corresponding XXGL ORACLE schema that owns several custom tables, you have two options (Oracle General Ledger is installed in the GL ORACLE schema). If you have relatively few custom tables, and they do not require more security than the Oracle E-Business Suite tables, the recommended approach ("tightly integrated with APPS schema") is:

If you wish to have additional security for the custom tables beyond the security for the Oracle E-Business Suite tables, use the following approach instead:

Note: Oracle E-Business Suite share data among applications. The correct privileges and synonyms for Oracle E-Business Suite products are automatically created during an upgrade. Your custom ORACLE schema may need privileges from Oracle E-Business Suite schemas other than the particular product you are customizing.

Defining Custom Views

If your new or modified code accesses Oracle E-Business Suite data, use views to insulate your code from changes in the standard applications database structure. Define views in the APPS schema. If an Oracle E-Business Suite object definition changes, you may only need to alter the view, rather than altering code.

Adding New Objects

Because Oracle E-Business Suite products are developed using the ORACLE RDBMS, you can easily extend the database by adding objects and relating them to existing Oracle E-Business Suite objects. Use standard naming conventions for the new objects (see Naming Standards), and place the new objects in your custom ORACLE schema or the APPS schema as appropriate. New tables that contain columns used by flexfields or Oracle Alert must be registered with Oracle Application Object Library.

Oracle Application Object Library runs forms and programs in the ORACLE schema associated with your current responsibility (usually APPS). Any database objects that need to be accessed must have grants provided to and synonyms created in the ORACLE schema used.

Naming Standards

Table Registration API

Modifying Oracle E-Business Suite Database Objects

You only modify an Oracle E-Business Suite database object when you cannot satisfy your needs using flexfields or new database objects. Never drop an object, including columns from tables. If absolutely necessary, alter tables by adding new columns that are defined as null allowed. Always export the table structure before alteration. When upgrading or patching Oracle E-Business Suite you will have to ensure that the modified objects will not affect or be affected by the upgrade (see Oracle E-Business Suite Upgrades and Patches).

Oracle E-Business Suite Upgrades and Patches

By following these standards you minimize the impact of an Oracle E-Business Suite upgrade or patch on your customizations. During the upgrade process you need to perform specific tasks to preserve your customizations. Many of these tasks are detailed in Upgrading Oracle E-Business Suite. You should review the manual for your specific platform and release, including any release updates, thoroughly before performing an upgrade. A patch may affect customizations less than a full upgrade, but should be given similar attention.

Check Database Modifications

If you have altered Oracle E-Business Suite database objects, you should unload the new versions of your Oracle E-Business Suite from the shipped media (or unload the patch) and review all the scripts in the drivers before upgrading or patching. You must determine if your modifications will affect these scripts. If your modifications will impact the scripts, you must reverse the modifications, run the upgrade or patch, and then reapply the modifications.

If changes to the Oracle E-Business Suite database structure affect any views you have created, you will need to modify the views after the upgrade completes. If your customized components access Oracle E-Business Suite tables directly, you will need to alter your components if the underlying Oracle E-Business Suite data structures change.

Identify Obsolete Customizations

Review each customization and determine if the new release of Oracle E-Business Suite satisfies the need that the customization met. If the customization is no longer needed, archive the changes and do not migrate them to the new release.

Migrate Customizations

All changes that are not obsolete must be migrated to the new release. You must migrate all components that were modified in the Oracle E-Business Suite directory structure, and you must migrate all components in your custom application directories.

To migrate customized components that you modified in the Oracle E-Business Suite application directory, you must first determine if the unmodified component changed between releases. Compare the original version of the prior release component (in the orig directory) to the new version of the component. If they are different, you have to apply the customizations to the new component (follow the guidelines for modifying an existing component). If the component did not change between releases, you create a copy of the new release of the component in the appropriate orig directory and copy the modified component from the previous release directory to the new release directory.

To migrate your custom applications code, document your modifications to your applications environment file before upgrading. After the upgrade process creates your new applications environment file, you modify the new file.

You can also use Oracle Application Object Library loaders and APIs to extract custom Oracle Application Object Library objects, upgrade, then use the extracted loader scripts to reapply your customizations.

Rerun Grant and Synonym Scripts

After determining which modifications are still valid upon upgrading, you should rerun all of the appropriate grant and synonym scripts for your customizations. These should all be located in the admin/sql directories of your custom applications. This is necessary because the upgrade process may lose grants by dropping and recreating an object for which you had previously granted access to your custom application.

Test All Customizations

As the last step of upgrade confirmation, you should test all of your customized components to ensure they work properly and that no changes to Oracle E-Business Suite have affected your modifications.

Building Online Help for Custom Applications

For general information on customizing the help files supplied with Oracle E-Business Suite, see Customizing Oracle E-Business Suite Help, Oracle E-Business Suite System Administrator's Guide - Configuration. The following sections provide additional details on providing online help for your custom forms and applications.

How the Help System Works

The Oracle E-Business Suite help system provides context-sensitive online help at a window-level granularity (that is, different help for each window in the application) and for individual Standard Request Submission reports and programs. Here is how the context-sensitivity works:

Prepare Your Forms

Verify that your custom forms refer to your custom application short name in the FND_STANDARD.FORM_INFO routine in the PRE-FORM trigger:

FND_STANDARD.FORM_INFO('$Revision: <Number>$', 
                   '<Form Name>', 
                   '<Application Shortname>', 
                   '$Date: <YY/MM/DD HH24:MI:SS> $',
                   '$Author: <developer name> $');

If you leave the Application Shortname value as FND, your user will not see any help, because Oracle E-Business Suite will not be able to construct a valid help target.

Create HTML Help Files

Create your HTML help files using your favorite HTML editor. Your help files can contain any links and information you want. To allow them to be called from your custom forms, you must include HTML anchor tags of the following form near the beginning of the file:

<A NAME="form_name_window_name"></A> 

For example, your help file might contain the anchor:

<A NAME="poxaccwo_headers"></A> 

You can also create context-sensitive help for your Standard Request Submission reports and programs, and include anchors for them in your HTML files using the following syntax:

<A NAME="srs_report_shortname"></A> 

For example, your help file might contain the anchor:

<A NAME="srs_poxacrcr"></A> 

Note: Both file names and HTML anchor names are treated in a case-insensitive fashion by the Oracle E-Business Suite help system.

We recommend that you have approximately one HTML help file for every window or report in your application, but this is not required. You can organize your HTML files however you want, provided any particular anchor name occurs only once per application short name.

Once you have created your files, upload them to the help system following the instructions given in Customizing Oracle E-Business Suite Help, Oracle E-Business Suite System Administrator's Guide - Configuration.

Create a Help Navigation Tree

You can also create a help navigation tree for your custom application, and add a link to it in the main "Library" section of the Oracle E-Business Suite help navigation tree. For information on creating and customizing help navigation trees, see Customizing Help Navigation Trees, Oracle E-Business Suite System Administrator's Guide - Configuration.

The HELP_TREE_ROOT profile option determines which help navigation tree is displayed when context-sensitive help is invoked from your custom application. For further information on this profile option, see Profile Options in Oracle Application Object Library, Oracle E-Business Suite System Administrator's Guide - Maintenance.

Upgrades and Patches

Upgrades and patches to the Oracle E-Business Suite help system should have no effect on help files and navigation trees associated with custom application short names. It is always a good practice, however, to keep copies of your files and tree structures in a safe place, so you can move them back into position after your upgrade or patch if a mishap occurs.

Important: The help system mechanism is subject to change for Release 12 or later, and you may need to revise your help system when you upgrade.

Integrating Custom Objects and Schemas

If you have custom objects or custom schemas that need to be tightly integrated with Oracle E-Business Suite, follow the instructions in this section.

Note: We recommend that you consult with an Oracle E-Business Suite consultant when integrating custom objects or schemas with Oracle E-Business Suite.

  1. Create custom schemas.

    If you have custom objects in Oracle E-Business Suite schemas, you must move them to custom schemas before you integrate with an APPS schema.

    Create one new schema to hold your custom data objects for each Oracle E-Business Suite schema in which your objects currently reside. Export your custom tables, indexes, and sequences from these schemas and then import them into the new custom schemas.

    Your data objects will be integrated with an APPS schema and your code objects will be created in Step 5.

    Important: Make sure your custom objects follow Oracle E-Business Suite naming conventions.

    See: Naming Standards

  2. Register custom schemas.

    If you have not done so already, register your custom schema by using the System Administrator responsibility in Oracle E-Business Suite. Use the navigator to select Security: ORACLE: Register.

  3. Determine and set install group number.

    If you have not done so already, set the install group number for each custom schema. You can do this by using the System Administrator responsibility in Oracle E-Business Suite. Use the navigator to select Security: ORACLE: Register.

    Use install group number 0 to represent your custom schemas that need only single installations.

    If you use Multi-Org or have only one product installation group, enter 0 for the install group number for your custom schemas and skip to the next step.

    For the remaining custom schemas, you must choose an install group number that matches the install group number of the Oracle E-Business Suite product it customizes. For instance, if the schema PO2 lists an install group number of 2 and your custom schema CUST_PO2 is based upon it, then you set 2 as the install group number for CUST_PO2 also.

  4. Change your data groups to use the APPS schema.

    Using the System Administrator responsibility in Oracle E-Business Suite, select Security: ORACLE: Register from the Navigator. Change the name in the ORACLE schema column to be the appropriate APPS schema for each data group that previously used your custom schema.

  5. Create custom objects and grant access to APPS schema.

    If you use Multi-Org or have only one product installation group, perform the following:

    Otherwise, create synonyms for each table and sequence in the appropriate APPS schema for the related custom schema. To do this perform the following:

  6. Drop duplicate code objects.

Upgrading Custom Forms

This section covers upgrading custom forms originally built with Oracle Forms 6i, the Oracle E-Business Suite coding standards, and Oracle Application Object Library. It applies to custom forms originally built to integrate with Release 11i.

Upgrading your custom forms to Release 12 consists of the following basic steps:

  1. Convert your Oracle Forms 6i. forms to Oracle Forms 10g. Make any required PL/SQL-related changes as well.

  2. Use the Oracle E-Business Suite upgrade utility on the Oracle Forms 10g .fmb file to apply changes that help your form conform to Release 12 standards.

  3. Correct any errors found by the upgrade utility, and run the utility again to verify your changes.

  4. Generate the .fmx file for your upgraded form.

  5. Test your upgraded form within Oracle E-Business Suite Release 12.

Note that while it is technically possible to skip the first step and go directly to the Oracle E-Business Suite upgrade utility step, we recommend that you do the first step separately to better isolate the changes to your form should there be any problem with either upgrade step.