The CUSTOM library allows extension of Oracle E-Business Suite without modification of Oracle E-Business Suite code. You can use the CUSTOM library for customizations such as Zoom (such as moving to another form and querying up specific records), enforcing business rules (for example, vendor name must be in uppercase letters), and disabling fields that do not apply for your site.
You write code in the CUSTOM library, within the procedure shells that are provided. All logic must branch based on the form and block for which you want it to run. Oracle E-Business Suite sends events to the CUSTOM library. Your custom code can take effect based on these events.
Attention: The CUSTOM library is provided for the exclusive use of Oracle E-Business Suite customers. The Oracle E-Business Suite products do not supply any predefined logic in the CUSTOM library other than the procedure shells described here.
The CUSTOM library is an Oracle Forms Developer PL/SQL library. It allows you to take full advantage of all the capabilities of Oracle Forms Developer, and integrate your code directly with Oracle E-Business Suite without making changes to Oracle E-Business Suite code.
The as-shipped CUSTOM library is located in the AU_TOP/resource directory (or platform equivalent). Place the CUSTOM library you modify in the AU_TOP/resource directory in order for your code to take effect.
After you write code in the CUSTOM procedures, compile and generate the library using Oracle Forms. Then place this library into $AU_TOP/resource directory (or platform equivalent). Subsequent invocations of Oracle E-Business Suite will then run this new code.
Warning: If there is a .plx (compiled code only) for a library, Oracle Forms Developer always uses the .plx over the .pll. Therefore, either delete the .plx file (so your code runs directly from the .pll file) or create your own .plx file using the Oracle Forms compiler. Using the .plx file will provide better preformance than using the .pll file. Depending on your operating system, a .plx may not be created when you compile and save using the Oracle Forms Developer. Form Builder. In this case, you must generate the library using the Oracle Forms Developer compiler from the command line (using the parameter COMPILE_ALL set to Yes).
The specification of the CUSTOM package in the CUSTOM library cannot be changed in any way. You may add your own packages to the CUSTOM library, but any packages you add to this library must be sequenced after the CUSTOM package. To ensure that your packages remain sequenced after the CUSTOM package even after a conversion from a .pld file, when program units are alphabetized, we recommend you name your packages with characters that come after C (for example, we recommend you name your own packages with names that begin with USER_).
Note: Custom packages must explicitly indicate 'AUTHID DEFINER' in the package header. Even though 'AUTHID DEFINER' is the default, it must be specified in a custom package header.
Be aware of the open form environment in which Oracle E-Business Suite operates. Also, each running form has its own database connection.
The following considerations and restrictions apply to the CUSTOM library and any libraries you attach to CUSTOM:
You cannot use any SQL in the library. However, you can use a record group to issue SELECT statements, and you can use calls to stored procedures for any other DML operations such as updates, inserts, or deletes.
Oracle Forms global variables in your code are visible to all running forms.
You may attach other libraries to the CUSTOM library. However, you cannot attach the APPCORE library to CUSTOM because it would cause a recursion problem (because CUSTOM is attached to APPCORE). You may attach the APPCORE2 library to CUSTOM. The APPCORE2 library duplicates most APPCORE routines with the following packages:
APP_ITEM_PROPERTY2
APP_DATE2
APP_SPECIAL2
These packages contain the same routines as the corresponding APPCORE packages. Follow the documentation for the corresponding APPCORE routines, but add a 2 to the package names. For example, where you would have a call to the APPCORE routine APP_ITEM_PROPERTY.SET_PROPERTY in a form, you can have a corresponding call to the APPCORE2 routine APP_ITEM_PROPERTY2.SET_PROPERTY in the CUSTOM library.
The CUSTOM library comes with the FNDSQF library already attached. FNDSQF provides Oracle E-Business Suite routines for function security (for opening forms), flexfields, and other utility routines.
Frequently you need to know the names of blocks and items within Oracle E-Business Suite forms for your CUSTOM logic. You should use the Examine feature available on the Help->Diagnostics menu while running the form of interest; it will give you easy access to all object names. You should not open Oracle E-Business Suite forms in the Oracle Forms Developer to learn this information.
You should exercise caution when changing any properties or values of items in the form from which CUSTOM logic is invoked. The CUSTOM library is intended to be a mechanism to augment Oracle code with your own. Using the CUSTOM library to alter Oracle code at runtime may bypass important validation logic and may jeopardize the integrity of your data. You should thoroughly test all logic you add to the CUSTOM library before using it in a production environment.
Within the CUSTOM library, you are free to write almost any code supported by Oracle Forms Developer, so long as you follow all Oracle E-Business Suite coding standards.
Where you would normally use Oracle E-Business Suite routines in the APPCORE library, you should use the corresponding routine in the APPCORE2 library (which you would attach to your copy of the CUSTOM library).
If you use Zoom or the CUSTOM library to invoke forms that you have developed, those forms must adhere completely to all of the Oracle E-Business Suite coding standards.
Attention: To invoke another form, use the function security routines in the FND_FUNCTION package. Do not use the CALL_FORM built-in since the Oracle E-Business Suite libraries do not support it.
The CUSTOM library receives two different kind of events, generic and product-specific. Generic events are common to all the forms in Oracle E-Business Suite. These events are:
WHEN-FORM-NAVIGATE
WHEN-NEW-FORM-INSTANCE
WHEN-NEW-BLOCK-INSTANCE
WHEN-NEW-RECORD-INSTANCE
WHEN-NEW-ITEM-INSTANCE
WHEN-VALIDATE-RECORD
SPECIALn (where n is a number between 1 and 45)
ZOOM
EXPORT
KEY-Fn (where n is a number between 1 and 8)
Logic you code for WHEN-FORM-NAVIGATE, WHEN-NEW- BLOCK-INSTANCE, WHEN-NEW-RECORD-INSTANCE, or WHEN-NEW-ITEM-INSTANCE fires after any existing logic in those triggers for the form, block or item.
Logic you code for WHEN-NEW-FORM-INSTANCE fires during the call to APP_STANDARD.EVENT. That call may be anywhere within existing WHEN-NEW-FORM-INSTANCE logic in the form.
Logic you code for WHEN-VALIDATE-RECORD fires during the call to APP_STANDARD.EVENT or FND_FLEX.EVENT. One of those calls may be within existing WHEN-VALIDATE-RECORD logic in the form or block, depending on how the form was originally coded.
Logic you code for SPECIALn, where n is a number, fires before any logic in the existing SPECIALn trigger (if there is one).
The ZOOM event occurs when the user invokes Zoom from the menu (View->Zoom) or the toolbar. The EXPORT event occurs after an export operation is complete (File->Export).
Logic you code for KEY-Fn events, where n is a number between 1 and 8, fires when the user presses the corresponding function key or key combination. Use the Help->Keyboard menu choice to determine the actual key combination corresponding to the appropriate function (F1-F8). Oracle E-Business Suite does not currently provide any logic associated with these KEY-Fn events.
The CUSTOM library also receives some product-specific events associated with the business rules of that product (for example, the NAVIGATE event in Oracle Human Resources). Please refer to the Open Interfaces Manual for your Oracle E-Business Suite product to see what product-specific events, if any, are passed to CUSTOM.
There are several main cases for which you can code logic using the CUSTOM library. Each of these cases must be coded differently.
Zoom - The addition of user-invoked logic on a per-block basis. A Zoom typically consists of opening another form and (optionally) passing parameter values to the opened form through the Zoom logic.
Logic for generic events - Augment Oracle E-Business Suite logic for certain generic form events such as WHEN-NEW-FORM-INSTANCE or WHEN-VALIDATE-RECORD. You can use generic events to change field prompts and other properties, hide fields, add validation, and more.
Logic for product-specific events - Augment or replace Oracle E-Business Suite logic for certain product-specific events that enforce business rules.
Setting visual attributes - Use the CUSTOM library to change the visual attributes of Oracle E-Business Suite fields at runtime. Use the Oracle Forms built-in SET_VA_PROPERTY to set the properties of the CUSTOM1-CUSTOM5 visual attributes, and then use APP_ITEM_PROPERTY2.SET_PROPERTY to apply the visual attribute to an item at runtime.
Zoom allows the addition of user-invoked logic on a per-block basis. For example, you may want to allow access to the Vendors form from within the Enter Purchase Order form while the user is in the PO Header block of that form. You can enable Zoom for just that block, and when the user invokes it, you can open the Vendors form.
Only Oracle E-Business Suite customers use the Zoom feature; Oracle E-Business Suite products do not ship any predefined Zoom logic.
Zoom behaves as follows:
Oracle E-Business Suite provides a menu entry and a button on the toolbar for the user to invoke Zoom when available. The button and the menu entry are disabled unless Zoom logic has been defined in the CUSTOM library for that form and block.
Whenever the cursor changes blocks in the form, the form calls the ZOOM_AVAILABLE function in the CUSTOM library. If this function returns TRUE, then the Zoom entries on the menu and toolbar are enabled; if it returns FALSE, then they are disabled.
If the Zoom entries are enabled, then when the user invokes Zoom the form calls the ZOOM event code in the CUSTOM library. You write code for this event that branches based on the current form and block.
Follow these steps to code Zooms into the CUSTOM library:
Add a branch to the CUSTOM.ZOOM_AVAILABLE function that specifies the form and block where you want a user to be able to invoke Zoom.
Add a branch to the CUSTOM.EVENT procedure for the ZOOM event.
Inside that branch, specify the form and block where you want a user to be able to invoke Zoom. Add the logic you want to occur when the user invokes Zoom.
Oracle E-Business Suite provides a referenced list of values (LOV) and corresponding referenced parameter for Zooms in all forms built using the TEMPLATE form (including custom forms). They are the following:
List of values: APPCORE_ZOOM
Parameter: APPCORE_ZOOM_VALUE
Use the LOV and parameter to provide users with an LOV where you have more than one Zoom from a particular block.
In the CUSTOM library (within your ZOOM event code):
Create a record group and populate it with names and values of available Zooms for the block.
Attach the record group to the APPCORE_ZOOM list of values (LOV).
Call show_lov to display the LOV to the user.
If user picks a Zoom, the value is returned into the APPCORE_ZOOM_VALUE parameter in the form.
Retrieve the parameter value and branch your Zoom code accordingly.
The following example sets up a Zoom LOV that contains three choices.
procedure event(event_name varchar2) is
form_name varchar2(30) :=
name_in('system.current_form');
block_name varchar2(30) :=
name_in('system.cursor_block');
zoom_value varchar2(30);
group_id recordgroup;
col_id groupcolumn;
begin
IF (event_name = 'ZOOM') then
if (form_name = 'FNDSCAUS' and
block_name = 'USER') then
-- set up the record group
group_id := find_group('my_zooms');
if id_null(group_id) then
group_id := create_group('my_zooms');
col_id := add_group_column(group_id,
'NAME', char_column, 30);
col_id := add_group_column(group_id,
'VALUE', char_column, 30);
set_lov_property('APPCORE_ZOOM',
GROUP_NAME, 'my_zooms');
else
Delete_Group_Row( group_id, ALL_ROWS );
end if;
Add_Group_Row( group_id, 1);
Set_Group_Char_Cell('my_zooms.NAME', 1,
'Personal Profiles Form');
Set_Group_Char_Cell('my_zooms.VALUE', 1, 'FNDPOMSV');
Add_Group_Row( group_id, 2);
Set_Group_Char_Cell('my_zooms.NAME', 2,
'System Profiles Form');
Set_Group_Char_Cell('my_zooms.VALUE', 2, 'FNDPOMPV');
Add_Group_Row( group_id, 3);
Set_Group_Char_Cell('my_zooms.NAME', 3,
'Responsibilities Form');
Set_Group_Char_Cell('my_zooms.VALUE', 3, 'FNDSCRSP');
-- test the LOV results and open different forms
if show_lov('APPCORE_ZOOM') then
zoom_value := name_in(
'parameter.APPCORE_ZOOM_VALUE');
if zoom_value = 'FNDPOMPV' then
fnd_function.execute(
FUNCTION_NAME=>'FND_FNDPOMPV',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y');
elsif zoom_value = 'FNDSCRSP' then
fnd_function.execute(
FUNCTION_NAME=>'FND_FNDSCRSP',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y');
elsif zoom_value = 'FNDPOMSV' then
fnd_function.execute(
FUNCTION_NAME=>'FND_FNDPOMSV',
OPEN_FLAG=>'Y',
SESSION_FLAG=>'Y');
end if;
end if;
end if; -- end of form branches within Zoom event branch
END IF; -- end of branches on EVENT_NAME end event; ----------------------------------------------------------
You can code logic that fires for a particular form and block at a particular form event. You can code logic for the following events:
WHEN-FORM-NAVIGATE
WHEN-NEW-FORM-INSTANCE
WHEN-NEW-BLOCK-INSTANCE
WHEN-NEW-RECORD-INSTANCE
WHEN-NEW-ITEM-INSTANCE
WHEN-VALIDATE-RECORD
SPECIALn (where n is a number between 1 and 45)
ZOOM
EXPORT
KEY-Fn (where n is a number between 1 and 8)
Some Oracle E-Business Suite forms, such as most Oracle Human Resources forms, may provide additional events that call the CUSTOM library. These additional events are listed in the documentation for the product that owns the form. You can code logic in the CUSTOM library for such events the same way you would code logic for generic form events.
Add a branch to the CUSTOM.EVENT procedure for the particular event you want. I
nside that branch, specify the form and block where you want your logic to occur. Add the logic you want to occur when that event fires for the form and block you specify.
Example CodeThe following example changes various field properties and prompts. This example also sets up and applies a custom visual attribute (CUSTOM1), and prevents inserts and updates to a block.
procedure event(event_name varchar2) is
form_name varchar2(30) :=
name_in('system.current_form');
block_name varchar2(30) :=
name_in('system.cursor_block');
begin
if (event_name = 'WHEN-NEW-FORM-INSTANCE') then
if (form_name = 'FNDSCAUS') then
--
-- Hide the Fax field, force the E-mail
-- field to be uppercase,
-- make the description field required,
-- change the person field
-- color to magenta, change the Supplier
-- field prompt.
--
app_item_property2.set_property('user.fax',
DISPLAYED, PROPERTY_OFF);
app_item_property2.set_property(
'user.email_address',
CASE_RESTRICTION, UPPERCASE);
app_item_property2.set_property('user.description',
REQUIRED,
PROPERTY_ON);
app_item_property2.set_property('user.employee_name',
BACKGROUND_COLOR, 'r255g0b255');
app_item_property2.set_property(
'user.supplier_name',
PROMPT_TEXT, 'Vendor Name');
--
-- Set up CUSTOM1 visual attribute as bright yellow.
--
set_va_property('CUSTOM1', BACKGROUND_COLOR,
'r255g255b0');
-- apply CUSTOM1 visual attribute to fields
-- (color will override
-- gray of disabled fields, but will not
-- override pale yellow
-- of required fields)
--
app_item_property2.set_property('user.supplier_name',
VISUAL_ATTRIBUTE, 'CUSTOM1');
app_item_property2.set_property('user.email_address',
VISUAL_ATTRIBUTE, 'CUSTOM1');
ELSIF (event_name = 'WHEN-NEW-BLOCK-INSTANCE') then
IF (form_name = 'FNDSCAUS' and
block_name = 'USER_RESP') THEN
-- prevent users from adding
-- responsibilities
set_block_property(block_name, insert_allowed,
property_false);
set_block_property(block_name, update_allowed,
property_false);
END IF;
END IF; -- end of branches on EVENT_NAME end event; ----------------------------------------------------------
Please refer to the Open Interfaces Manual or User's Guide for your Oracle E-Business Suite product to see what product-specific events, if any, are passed to CUSTOM. For product-specific events passed by Oracle Application Object Library, see: Product-Specific Events in Oracle Application Object Library.
Add a branch to the CUSTOM.EVENT procedure for the particular product - specific event you want.
Within that branch, add logic for that specific business function
If custom execution styles are supported for this product - specific event (many product - specific events do not support custom execution styles), add a branch to the CUSTOM.STYLE function that specifies the execution style (before, after, override, or standard) you want for your product - specific event logic. You can only specify one of the styles supported for that particular product - specific event.
To manage your customizations and handle upgrade considerations follow these guidelines:
If a form is operating incorrectly, and you have coded CUSTOM library or Zoom logic for it, use the menu to disable the CUSTOM library code temporarily (Help->Diagnostics->Custom Code->Off) so you can determine whether the problem comes from the customizations or Oracle E-Business Suite code.
An Oracle E-Business Suite upgrade will typically create a new directory structure that includes the default (as-shipped) version of the CUSTOM library, so you must keep a backup copy of CUSTOM with the changes you make. Place your custom version of the CUSTOM library in the new AU_TOP/resource directory after the upgrade. You may need to upgrade and/or regenerate the CUSTOM.plx file as part of the upgrade.
An Oracle E-Business Suite patch will never include a new CUSTOM library.
Remember, form and block names may change after an upgrade or patch to Oracle E-Business Suite. You should test any custom logic that you have defined to confirm that it still operates as intended before using it in a production environment.