DEVELOPING FORM EXTENSIONS FOR ORACLE EBUSINESS SUITE CUSTOMERS

Susan Behn, Solution Beacon, LLC Introduction

The purpose of this paper is to provide developers with a guide to getting started with development of form extensions for Oracle E-Business Suite Customers. Form extensions are defined as new forms created for the customer to provide functionality that does not exist in the E-Business Suite or does not exist in the products the customer chooses to license. While the primary focus of this paper is to cover form extensions, I will also briefly cover the tool provided for protected customizations to the E-Business Suite. Due to the limited length of the presentation and paper, I have included only a subset of the most often referenced standards. Please refer to the documentation materials identified later in this paper for a complete reference to all standards for the E-Business Suite.

Why Follow Standards?

Oracle had done a great job documenting highly detailed standards to ensure that developers can add extensions to the applications with out it looking like an add-on. Strictly following these standards will make the extensions appear to be seamlessly integrated with the application software. Even if you are not extending Oracle Applications, I would encourage you to implement these standards for other applications. The Oracle E-Business supplied objects will not be available, but most concepts are transferable.

Faster Development
Following development standards results in faster development for several reasons. The highest percentage of time savings result from the Oracle supplied libraries, property classes, object groups, code and other existing objects that can be reused. The developer does not need to code for standard behavior such as calendar functionality, open and closing windows, toolbar and more. Faster development is also achieved by eliminating the time in the design phase to determine look and feel and standard behaviors.

Consistent User Interface

Using the same user interface reduces training, user frustration and on-going support after deployment. Navigation should only be taught once and should be the same for all users across all applications, seeded and extensions.

Web Compatibility
Using Oracle standards for form development will ensure the forms will work for web based deployment.

Easier Maintenance
When development is standardized, a developer can quickly find the correct object or code that must be changed. The developer will not need to spend valuable time trying to figure out how and where the original developer designed the code.

Compliance with American Disabilities Act

All software purchased by government entities must comply with the American Disabilities Act, also referred to as Section 508. Low vision or blind users, hearing impaired users and physically impaired users must be able to use the software. This topic will be discussed in more detail later in this paper.

Language and Currency Translation

Using Oracle standards for form development will ensure the forms will translate language and currency correctly.

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle

Behn

Assumptions
To fully understand the topics covered in this paper, it is assumed the reader has at least some experience with Forms 6i. This paper is applicable to E-Business Suite releases 11i. The most recent release of Oracle Applications E-Business suite is 11.5.10 which still uses Forms 6i. It is also assumed you are using a local workstation to develop forms. This paper refers to standard directories in Oracle Applications which is beyond the scope of this paper.

Getting Started
The first step required to develop forms for E-Business Suite customers is to download the template form and related forms and libraries to your local workstation. These forms are located in the Oracle Applications database in $AU_TOP/forms/US. Form libraries are located in $AU_TOP/resource. Download the following two forms from $AU_TOP/forms/US into the local directory where your form files will reside. 1. TEMPLATE.fmb 2. APPSTAND.fmb TEMPLATE.fmb provides standardized sample objects and references. Examples of sample objects included are sample blocks, canvases, LOVs, parameters, windows, built in triggers, the toolbar, calendar, menu and property classes. This form file is platform independent and includes references to APPSTAND.fmb. APPSTAND.fmb contains the standard objects referenced by TEMPLATE.fmb and also references libraries. These libraries will be discussed in a later section. APPSTAND.fmb is a platform specific form file. By using referenced objects, forms can be developed then deployed across multiple platforms.

Property Classes
One of the most important but overlooked features in form development is the use of pre-defined property classes. Property classes are especially important for E-Business Suite form extensions because using property classes will provide the bulk of what is required to achieve the same look and feel as the applications forms. Property classes, provided in APPSTAND.fmb for almost every object type, provide the visual and behavioral attributes for objects. You will even find property classes defined for horizontal and vertical lines and region frames. The item inherits properties from the property class. Not only does this achieve that same look and feel, but it will also ensure some of the Section 508 requirements are met. For example, property classes establish the color scheme that is used by the E-Business suite. This color scheme is designed to be aesthetically pleasing as well as easily adjustable for low vision users. Inherited properties defined by the property class should not be overridden without careful consideration. Modifications compromise the consistency of the user interface. Using property classes is the single most important thing you can do to standardize!

Development Standards
The logical order to build a form is to create the module from the template with the attached libraries, then build windows, canvases and data blocks. Next, arrange the fields. Finally, add or update any pl/sql code in triggers and program units. In this section, a sampling of standards and requirements are presented in the logical design order.

Module
There are a few items that must be addressed at the module (form) level. Change the module name from TEMPLATE to the name of the form and set the first navigation block. In the template, the property class is already set to module. Hopefully, there is a design for your form and the name of the first navigation block is known. If not, be sure to go back and change it later. Save the form NOW using File Save As. Dont overwrite TEMPLATE.fmb!

Libraries
Oracle provides 22 libraries that must be attached to the form. Download these libraries from $AU_TOP/resource to your local workstation. If you choose to place these libraries in a separate directory, which I do recommend, set the FORMS60_PATH on your desktop to the location of the local libraries. This can be done by setting an environment variable or by modifying your registry. Refer to the documentation for your workstation platform for specific instructions. As indicated in the list below by indentions, some libraries have additional libraries attached. If an attached library is missing, an error message will appear when you open the form. This indicates a required library does not exist on your local workstation or the FORMS60_PATH is not set correctly.

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle Core The list of libraries below provide functionality that is used by every form. APPCORE.pll VERT.pll GLOBE.pll JA.pll JE.pll JL.pll Application Standards, toolbar Specific industry features Global or regional features Asia/Pacific features Europe/Middle East/Africa features Latin America Code Customizations of standard forms

Behn

CUSTOM.pll

FNDSQF.pll APPDAYPK.pll APPFLDR.pll

Flexfields, Profiles, Currency, Concurrent Request Submission, Record History, Message Dictionary Calendar Packages for Folder Blocks

Application Specific The list of libraries below are application specific, but they must be attached to every form because they are attached to the template. FV.pll HRKPI.pll GHR.pll GMS.pll IGILUTIL.pll IGILUTIL2.pll PSAC.pll PQH_GEN.pll PSA.pll PSB.pll OPM.pll APPCORE2.pll Federal Financials Human Resources Knowledge Provider Global Human Resources Encumbrances International Public Sector International Public Sector Public Sector Applications Public Sector Human Resources Public Sector Applications Public Sector Budgeting Process Manufacturing Application standards (for CUSTOM.pll)

In addition to the libraries listed above, note that Oracle uses many other libraries that are either application specific or specific to a country. Typically Oracle does not support the use of these libraries in custom forms. Additionally, Oracle does not support direct references to APPFLDR, VERT, GLOBE, PSAC, PQH_GEN, GHR, JA, JE or JL for custom forms.

Windows
There are three types of windows in the template defined by property classes. A modal window is used to require the user to answer a question. A non-modal window is used for all other purposes. Do not use ROOT_WINDOW. This window type is only for the toolbar. Use of this property class will interfere with the toolbar. Modal To create a modal window with standard behavior, complete the following steps in order. 1. 2. 3. Create the window with the property class set to WINDOW_DIALOG. Set and center the window using APP_WINDOW.SET_WINDOW_POSITION. Disable all key triggers and set navigation to keep the user in the dialog box. Key triggers can be disabled by creating a block level Key-Others trigger with the NULL statement. Set previous block and next block to the name of the dialog block prevent navigation to any other block.

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle 4. 5. 6. 7.

Behn

Write code to explicitly close the window. Create a dialog block with the property class set to BLOCK_DIALOG. Code OK and Cancel buttons in the WHEN-BUTTON-PRESSED trigger to prevent getting stuck in a dialog box during testing with no way out other than closing the application. Create remaining items.

Non-Modal This is where the users will enter the majority of the data. There is much more flexibility in the design of non-modal windows, however, Oracle provides exhaustive standards to ensure the forms all look the same. Set the property class to WINDOW. Each window should contain one logical entity. A logical entity can be compared to a single paper form. For example, a purchase order is a logical entity. A single window may include the purchase order header and purchase order lines, but the accounting distributions for the lines are not considered part of the purchase order entity even though they are related. They should be in the same form, but a separate window. Do not attach scroll bars to windows. Scroll bars are attached to blocks. Windows should be sized only as large as necessary. The minimum size is 2 x 2. The maximum size is 7.8w x 5.0h. There should be 1 character space margin between the window border and any text. This includes top, bottom, left and right. Boundary lines are allowed in this margin. Always include a window title, but do not use singular/plural forms for the window title to distinguish windows. Some languages, such as Japanese, do not have plural forms and the translated titles will both be the same. For example, instead of Customers for the first window and Customer for the drill down window, use Customers and Customer Detail. Do not change the word order for window titles to distinguish windows. This is also a problem for language translation. Do not pad window titles with spaces.

Canvases
Before placing items on the canvas, set the ruler settings as shown in the figure 1 and turn on snap to grid. Ruler settings must be set for each canvas.

1. Ruler Settings

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle

Behn

The property class for a canvas can be set to CANVAS, TAB_CANVAS or CANVAS_STACKED. Each window contains one content canvas. Tab or stacked canvases may be placed in front of a content canvas. Stacked canvases always raise on entry. Utilize tabs to avoid scrolling. Set the property class appropriately for the type of block. Two sample blocks are provided in the template. Cut and paste from these blocks as needed. Delete the sample blocks, BLOCKNAME and DETAILBLOCK prior to deployment. Do not delete the CALENDAR or PROGRESS_INDICATOR blocks. Base simple blocks on tables. Base complex data blocks on views to minimize network traffic by denormalizing foreign keys on the server, eliminate the need to write POST-QUERY and PRE-QUERY code for non-database fields and account for multi-org and multi-language. Views are also patched easily. Attempt to place all blocks for a logical entity in one window. Exceptions to this rule are fields that are not frequently used and information not perceived as attributes of the logical entity. Use tabs or alternating regions to avoid horizontal scrolling. Tabs also make security easier to implement for the form because groups of fields that must be hidden or restricted can be placed on a tab and the security control can be implemented at the tab level rather than at the item level. An exception to this rule is when the fields that must be accessed by scrolling are rarely used or there is no logical way to divide the fields into tabs. Always add a scroll bar and current record indicator for multi-record blocks. If there is one block in a window, set the navigation style to Same Record. This is the default. When the user tabs from the last item, the input will move to the first item on the form in the same record. If there are multiple blocks in a window, set the navigation style to Change Record or Change Block.

Data Blocks

Data Block Items

Property classes exist for almost all items text, display, buttons, dates, LOVs, etc Make sure the correct property class is applied. (Have you counted how many times I have mentioned property classes so far? Its important! ) Cut and paste sample items from BLOCKNAME and DETAILBLOCK, then modify as necessary. Enable the calendar for every date field and control valid dates. For example, the user should not be able to enter a check date before the current date. Set a default value for check boxes. Check boxes are always mandatory. Set the maximum size of items to database column size. Validate items immediately when possible. LOVs LOVs should only show valid rows. Validate from List = Yes for items with LOVs. Base LOVs on views to allow sharing. The title in the first item of the LOV should match the prompt of the field calling the LOV. Sort the LOV data by the first column which should be the column for which the user is searching. Place buttons in the block in which they appear to sit. Provide an access key for every button. For multi-row blocks, set Keyboard Navigable to No.

Buttons

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle

Behn

For single row blocks, set Keyboard Navigable to Yes. In the WHEN-BUTTON-PRESSED trigger, set Fire in Enter Query mode to No.

Compliance with the American Disabilities Act Section 508

There are four primary requirements to comply with the American Disabilities Act. Software purchased by government entities must comply with the requirements of this act. This includes any customizations or extensions to the software. 1. All actions must be executable using the keyboard. This is achieved by specifying access keys for all non-navigable items using & in the label property for buttons, check boxes, radio buttons and tab pages. Navigate through the items in the form from left to right, top to bottom.

Cycle through all fields on multi-record blocks. The user must not be required to use the scroll bar. 2. Timed functions are prohibited. 3. The user must be able to control color. Using defined property classes will meet this requirement. 4. Sufficient information must be available to assisted technology (i.e. screen readers). Some specific items to address are abbreviated prompts, flexfield high/low ranges, items without prompts that are identified by the region title and nonunique prompts. To comply with this requirement, enter hint text or enter tool tip help for all items where the prompt does not clearly identify the item. The first non null attribute in order as shown in the list below is sent as the prompt to the screen reader. 1. Hint Text 2. Prompt 3. Label 4. Tool tip help

Layout
At this point it is time to arrange the items. Also set any properties that are not inherited from the property class such as prompt, justification, prompt alignment and others. Items The leftmost button in the window should be the default button unless it is a help button. Allow 30% additional text space for prompts, buttons, check box labels, pop lists, option groups, region titles and display only fields for language translation. Set alignment for text to start or end rather than left or right to allow for language translation. Allow one character space between fixed and alternating regions. Place the coordination check box outside the tabbed region. The coordination check box allows the user to choose whether querying is immediate or deferred. For example, if the user changes the supplier in the header record, the detail invoices for the supplier are not queried until the window containing the detail block is opened. However, if the user has both windows open, querying can be changed to immediate by checking the box. On windows that contain the header and detail, the default for the coordination check box should be set to immediate (checked). If the header and detail are in separate windows, the default for the coordination check box is set to deferred (unchecked). Draw a region frame/line around logical groups of data. For example, currency code and amount are separate items that are enclosed in a region frame. Select all the items in a multi-record block and set the alignment to stacked. There is no space between items.

Tabbed regions

Regions

Allow 4 character cells for standard abbreviations. Standard abbreviations are documented in the standards guide.

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle

Behn

Additional Code
After layout is complete, code triggers and program units. It is recommended that program units be used for the majority of the code to keep it modular and in one location. Generally, if a trigger contains more than one line of code, call a program unit. Always use who fields in the table and include standard code to update these fields. This information is displayed when the user chooses Help Record History from the standard toolbar. Refer to the developer guide for details. The template includes the APP_CUSTOM package. In this package, the developer must set the first window, modify code to close windows and modify code to control deferring of master-detail relations. This package is very well documented in the package body. Follow the instructions.

Triggers
One of the most important and overlooked settings for triggers is the execution hierarchy. Generally, set New triggers to Before, Post triggers to After, Key triggers to Override and all others to before. There are some exceptions to these rules. If there is a flexfield using a POST-QUERY trigger at the form level, set the block-level POST-QUERY trigger to After and reset the record status to Query in this trigger. If there are custom entries for the right mouse button, set those block or item level triggers to After. If you encounter unexpected behavior during testing, this is the first place to look. Modification Required The only trigger that absolutely must be modified is the PRE-FORM trigger at the form level. BLOCKNAME must be changed to the name of the first block of your form. FIRST_WINDOW must also be changed to the first window in the form. The revision, date, author and form name should also be changed for the correct information to appear in Help About on the HELP drop down menu. Modification Optional Code can be added to the following triggers at the form level. KEY-CLRFRM add code after APP_STANDARD.EVENT. POST-FORM add code before APP_STANDARD.EVENT. QUERY-FIND replace the code or add block-level triggers to override the form level trigger. ACCEPT replace the standard call.

Modification Not Allowed at Any Level Do not modify the following triggers at any level. STANDARD_ATTACHMENTS ZOOM FOLDER_ACTION KEY-HELP KEY-EXIT KEY-EDIT KEY-COMMIT WHEN-WINDOW-CLOSED CLOSE_WINDOW

Modification Allowed Only at Block or Item Level WHEN-NEW-RECORD-INSTANCE WHEN-NEW-BLOCK-INSTANCE WHEN-NEW-ITEM-INSTANCE POST-QUERY KEY-DUPREC

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle

Behn

KEY-MENU KEY-LISTVAL QUERY-FIND ACCEPT ON-ERROR

CUSTOM.pll Library for Protected Customizations

CUSTOM.pll is a library provide by Oracle to allow for limited customizations of forms without compromising the ability to upgrade. This library is often used by E-Business suite customers to provide defaults for data, limit the scope of data and creating additional application security such as hiding fields, making fields non-updateable, etc If you find yourself in a large E-Business implementation with a significant amount of requirements for CUSTOM.pll, you will quickly discover some issues that must be addressed. There is only one CUSTOM.pll library for the entire E-Business suite. There is a size limitation depending on the platform. Some E-Business Suite customers have encountered this size limitation. 2. It is difficult to manage the need for multiple developers making changes concurrently. The recommended method is to create a separate .pll library for the form that requires customizations. Attach this library to CUSTOM.pll. The only code modifications in CUSTOM.pll are the attachment and a call to the package when the form is opened. Note: This is a Solution Beacon recommendation and is not documented in the Oracle reference documents. Applicable portion of CUSTOM.pll:
Form_name varchar2(30) := name_in(system.current_form); Begin If form_name = XXXXXAPXVDMVD THEN xxxxxapxvdmvd.event(event_name); Elsif form_name = XXXXXOEXOEORD THEN xxxxxoexoeord.event(event_name); end if; end event;

1.

Example of your own custom library program unit:

PACKAGE XXXXXAPXVDMVX IS Procedure event(event_name VARCHAR2); END; PACKAGE BODY XXXXXAPXVDMVX IS PROCEDURE event (event_name VARCHAR2) IS BEGIN IF event_name = WHEN-NEW-FORM-INSTANCE THEN SET_ITEM_PROPERTY(VENDOR_TYPE_DISP,REQUIRED,PROPERTY_TRUE); END IF; END event; END XXXXXAPXVDMVX;

Additional Resources
Reference Guides Provided by Oracle
In the limited time for a presentation, I have only touched the surface of standards. The first reference guide on the list below provides the majority of the information provided in this paper. Refer to the other guides for additional standards and application APIs. These guides are available via MetaLink. Oracle Applications User Interface Standards for Forms-Based Products

www.odtug.com

ODTUG 2005

Developing Form Extensions for Oracle

Behn

Oracle Application Developers Guide Oracle Applications System Administrators Guide Oracle Applications User Guide American Disabilities Act http://www.access-board.gov/sec508/guide/scope.htm http://www.oracle.com/technology/tech/blaf/specs/ssAda.html

Other References

MetaLink Oracle Applications User Group - www.oaug.org White Papers New Customizations and Extensions Special Interest Group Newsletter White papers and presentations Free scripts, pocket guides and other tools

Solution Beacon Web site www.solutionbeacon.com

Summary
When developing form extensions for E-Business Suite customers, developers should refrain from being overly creative when coding for the user interface. It is more important to follow standards facilitate a seamless extension. Start with TEMPLATE.fmb, APPSTAND.fmb and Oracle provided libraries. Always apply property classes Follow object and layout standards Comply with the American Disabilities Act Use program units to keep code modular Set trigger execution hierarchy correctly Make it look good!

www.odtug.com

ODTUG 2005