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:
Changing forms
appearance
validation logic
behavior
Changing reports or programs
appearance
logic
Database customizations
adding read-only schemas
augment logic with database triggers
Integrating third party or custom software
relinking programs
These suggestions provide you with the ability to satisfy the following basic business needs. You should be able to:
Enhance Oracle E-Business Suite to meet your needs by:
Developing new components
Modifying existing components
Improve the Oracle E-Business Suite upgrade process by:
Preserving custom components across upgrades
Simplifying the upgrade of custom components
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
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.
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.
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).
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.
A table, index, view, sequence, database trigger, package, grant, or synonym.
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.
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.
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.
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.
Follow these steps to determine your customization needs:
Determine the specific requirement that is not met by Oracle E-Business Suite
Try to meet this requirement by altering the definition parameters of the standard applications, as described in your implementation and user manuals. Often, you can eliminate the need for customization by altering the application configuration (such as by setting up a descriptive flexfield)
Document the requirement that you wish to meet by customization
Determine if you can meet this requirement by extension (adding a new component) or if you must modify an existing component
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.
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:
Define your custom application
Create your custom application directory structure
Add your custom application to your Applications Environment File
Add new components to your custom application
Document your new components
Tip: Use a revision control system to help you keep track of your changes and custom components.
See: Overview of Building an Application
Overview of Setting Up Your Application Framework
You should document at least the following for each new component:
Purpose
Input parameters (for reports and programs)
Sample output (for reports and programs)
Processing logic
Database objects used and type of access (select, update, insert, delete)
You thoroughly document each extension to simplify each of the following tasks:
Component modification due to changing business requirements
Component modification due to Oracle E-Business Suite upgrades or patches
Identification of obsolete extensions following an Oracle E-Business Suite upgrade or patch
Use the Register Flagged Files utility in Oracle Applications Manager to register and document your extensions. Refer to the Oracle E-Business Suite Maintenance Guide for more information on this utility.
Register your application using adsplice. See: AD Splicer, Oracle E-Business Suite Setup Guide and My Oracle Support Knowledge Document 1577707.1, "Creating a Custom Application in Oracle E-Business Suite Release 12.2."
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.
Note: Your application short name must be no more than sixteen (16) characters long.
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
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.
See: Set Up Your Application Directory Structures
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 Setup Guide and the Oracle E-Business Suite Maintenance Guide.
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.
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.
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.
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.
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 Setup Guide. 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
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
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 Security Guide.
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
Use adsplice to define a custom PRODUCT_TOP. For information, see: Creating a Custom Application in Oracle E-Business Suite Release 12.2, My Oracle Support Knowledge Document 1577707.1.
Note: Do not use Oracle Applications Manager to define a custom PRODUCT_TOP.
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.
You should list each component that you modify in the Register Flagged Files utility in Oracle Applications Manager. Refer to the Oracle E-Business Suite Maintenance Guide for more information on this utility.
In addition to your list in the Register Flagged Files utility, , you should also document at least the following for each component modification:
Purpose of the modification
Name of files changed
Changes to input parameters (for reports and programs)
Sample output (for reports and programs)
Changes to processing and validation logic
Changes to database objects used and type of access (select, update, insert, delete)
Tip: Use a revision control system to help you keep track of your changes and custom components.
You thoroughly document each modification to simplify each of the following tasks:
Further modification due to changing business requirements
Identification of obsolete modifications following an Oracle E-Business Suite upgrade
Recreating modifications to upgraded Oracle E-Business Suite components
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.
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:
Identify the file
Copy the file to a custom application and rename the file
Preserve the original file
Make the modifications
Comment the form
Generate the form
Register the customization in the Register Flagged Files utility
Document your customization
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:
Select Help->About Oracle Applications from the menu. Scroll to the Form Information section. The form name, followed by .fmb, is the form source file to be modified.
The first two or three characters of the form file name are the application short name. The file should be located under the forms/<language> directory for that application or in the $AU_TOP/forms/<language> directory.
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.
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
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:
Identify the file
Make the modifications
Comment the report
Create a concurrent program using your 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:
Query the concurrent program name using the Concurrent Programs window (using either the Application Developer responsibility or the System Administrator responsibility). Use the Program field as the query criteria (the program name is the same descriptive name that appears when you submit a request to run that program). Write down the contents of the Name field in the Executable region.
Navigate to the Concurrent Program Executable window using the Application Developer responsibility. Query the executable using the executable name you obtained from the Concurrent Programs window.
You identify the report type from the Execution Method field. The file name is the Execution File Name with the appropriate suffix. The following table lists the report execution method, corresponding file name extension, and subdirectory.
| Execution | Extension | Subdirectory |
|---|---|---|
| SQL*Plus | .sql | sql |
| Oracle Reports Program | .rdf | reports |
| SQL*Loader (control file) | .ctl | bin |
You should be able to find the report file in the appropriate subdirectory in the directory structure of the application that owns the executable file. However, Oracle E-Business Suite programs listed with Spawned or Immediate execution styles are typically C programs, so these programs would not be available for modification. Programs listed with an execution style of PL/SQL Stored Procedure are stored in the database.
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.
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
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
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 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.
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 Setup Guide. 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.
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.
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.
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.
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.
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.
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.
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 Maintenance 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 the Standard data group to the responsibility. When you use that responsibility, you connect to its ORACLE schema through the Standard data group. 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:
Grant privilege on the custom tables from XXGL to APPS
Create synonyms for XXGL tables in APPS
Define custom responsibilities that use the APPS ORACLE schema
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:
Grant privilege on the Oracle E-Business Suite objects from APPS to XXGL
Create synonyms for GL tables in XXGL to the APPS object of the same name
Define custom responsibilities using the XXGL schema
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.
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.
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, Oracle Alert, or Oracle Web Applications Desktop Integrator 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.
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).
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.
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
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.
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.
Create custom objects and grant access to APPS schema.
If you use Multi-Org or have only one product installation group, perform the following:
Grant minimal privileges from each custom data object to APPS.
Create a synonym in APPS to each custom data object in every custom schema.
Create custom code objects in APPS.
Otherwise, create synonyms for each table and sequence in the appropriate APPS schema for the related custom schema. To do this perform the following:
Grant minimal privileges from each custom data object to each APPS schema.
Create a synonym in the APPS schema with the same install group number as your custom schema for every custom data object. For instance, create synonyms in APPS2 for CUST_PO2 objects.
Create custom code objects in each APPS schema.
Drop duplicate code objects.
When creating extensions or integrating with third-party products that require access to objects in the Oracle E-Business Suite database, it is recommended to create and use a database schema separate from the Oracle delivered schemas such as APPS. The separate database schema should be created following the principles of least privileges and separation of duties.
Oracle E-Business Suite database procedures or program units are typically defined with invoker's rights. An invoker's rights procedure executes with the privileges of the user who invokes the procedure. We recommend exposing database procedures by putting a definer's rights wrapper on top of the procedures that you wish to be executed by the separate database schemas. The wrapper will act as a proxy similar to the sudo concept in the UNIX flavor operating systems. You can grant this wrapper only to the database users that require it and leverage the wrapper to limit the functionality and provide validation.
The following process can be leveraged to create the wrapper to expose the Oracle E-Business Suite procedure so that it can be used by the separate database users without the complexity required to determine, assign and manage the individual privileges. Since privileges are not granted directly to the user, the procedure can limit the exposed functionality.
For example, if you want to call PRICING.LOAD_PART_NUMBERS to load part numbers from another schema (MYSCHEMA):
Create a new package in the APPS schema called XXX_PRICING.
This package will contain only the procedures and functions you need to access with exactly the same signature (LOAD_PART_NUMBERS) along with any additional validation.
This procedure will be defined with Definer's rights (AUTHID DEFINER) and it will be a wrapper which calls the underlying APPS procedure.
Grant the MYSCHEMA account execute rights to the XXX_PRICING package.
(Optional) Create a synonym for XXX_PRICING in MYSCHEMA if you don't want to refer to it by its new fully qualified name (PRICING -> APPS.XXX_PRICING).
Now you should be able to execute APPS.XXX_PRICING.LOAD_PART_NUMBERS from the MYSCHEMA account. The wrappers should also contain additional validation to limit the functionality being called, and also validate parameters that are being passed into the PL/SQL package.
Many Oracle E-Business Suite packages will require user context initialization, and you may need to proxy the package that does this as well - APPS.fnd_global.apps_initialize(). Because this can be used to assert the identity of any user, you should consider adding validation to the wrapper which limits the users and responsibilities that can be set via the wrapper.
For information on managing security access with the Oracle database, see "Configuring Privilege and Role Authorization" and "Managing Security for Definer's Rights and Invoker's Rights" in Oracle Database Security Guide.
For information on database object development standards for online patching, see Developing and Deploying Customizations in Oracle E-Business Suite Release 12.2, My Oracle Support Document 1577661.1.
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.
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.
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.
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.
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.
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.
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:
Convert your Oracle Forms 6i. forms to Oracle Forms 10g. Make any required PL/SQL-related changes as well.
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.
Correct any errors found by the upgrade utility, and run the utility again to verify your changes.
Generate the .fmx file for your upgraded form.
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.
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 Setup Guide. The following sections provide additional details on providing online help for your custom forms and applications.
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:
The user presses the Window Help button or selects Help->Window from the menu.
Oracle E-Business Suite instructs the user's web browser to retrieve the appropriate help file from a particular URL. The URL sent to the browser is constructed from:
the base URL specified in the APPLICATIONS_HELP_WEB_AGENT profile option. If this profile option is not set, then the value specified in the APPLICATIONS_WEB_AGENT profile option is used. These profile options are typically set when Oracle E-Business Suite is installed.
the current language code
the application short name specified in the FND_STANDARD.FORM_INFO routine in the form
the name of the form (such as POXACCWO)
the name of the window (such as HEADERS)
the value of the HELP_LOCALIZATION_CODE profile option, if any
Oracle E-Business Suite returns the indicated help file to the user's web browser.
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 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 Setup Guide.
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 Setup Guide.
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 Setup Guide.
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.