Skip Headers

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

Menus and Function Security

Overview of Menus and Function Security

Function security lets you restrict application functionality to authorized users.

Application developers register functions when they develop forms. A System Administrator administers function security by creating responsibilities that include or exclude particular functions.

For additional information on using Oracle Application Object Library Function Security, see the Oracle E-Business Suite System Administrator's Guide - Security.

Basic Function Security

Advanced Function Security

Terms

Function

A function is a part of an application's functionality that is registered under a unique name for the purpose of assigning it to, or excluding it from, a menu (and by extension, a responsibility).

There are several types of functions: form functions, subfunctions, and non-form functions. We often refer to a form function simply as a form.

Form (Form Function)

A form function (form) invokes an Oracle Forms Developer form. Form functions have the unique property that you may navigate to them using the Navigator window.

Subfunction

A subfunction is a securable subset of a form's functionality: in other words, a function executed from within a form.

A developer can write a form to test the availability of a particular subfunction, and then take some action based on whether the subfunction is available in the current responsibility.

Subfunctions are frequently associated with buttons or other graphical elements on forms. For example, when a subfunction is enabled, the corresponding button is enabled.

However, a subfunction may be tested and executed at any time during a form's operation, and it need not have an explicit user interface impact. For example, if a subfunction corresponds to a form procedure not associated with a graphical element, its availability is not obvious to the form's user.

Self-Service Function (Non-form Function)

Some functions provide a way to include other types of code, such as HTML pages or Java Server Pages (JSPs) on a menu and responsibility. These functions are typically used as part of the Oracle Self-Service Web Applications. These functions include other information such as URLs that point to the appropriate files or functionality.

Menu

A menu is a hierarchical arrangement of functions and menus of functions that appears in the Navigator. Each responsibility has a menu assigned to it.

The Oracle E-Business Suite default menu appears as the pulldown menu across the top of a window and is not generally controlled using Function Security.

See: Pulldown Menus and the Toolbar.

Menu Entry

A menu entry is a menu component that identifies a function or a menu of functions. In some cases, both a function and a menu of functions correspond to the same menu entry. For example, both a form and its menu of subfunctions can occupy the same menu entry.

Responsibility

A responsibility defines an application user's current privileges while working with Oracle E-Business Suite. When an application user signs on, they select a responsibility that grants certain privileges, specifically:

Forms and Subfunctions

A form is a special class of function that differs from a subfunction in two ways:

A form as a whole, including all of its program logic, is always designated as a function. Subsets of a form's program logic can optionally be designated as subfunctions if there is a need to secure those subsets.

For example, suppose that a form contains three windows. The entire form is designated as a function that can be secured (included or excluded from a responsibility.) Each of the form's three windows can be also be designated as functions (subfunctions), which means they can be individually secured. Thus, while different responsibilities may include this form, certain of the form's windows may not be accessible from each of those responsibilities, depending on how function security rules are applied.

How Function Security Works

Developers Register Functions

Developers can require parts of their Oracle Forms code to look up a unique function name, and then take some action based on whether the function is available in the current responsibility.

Developers register functions. They can also register parameters that pass values to a function. For example, a form may support data entry only when a function parameter is passed to it.

Register your functions and subfunctions on the Form Functions window.

Developers Create Menus

Typically, developers define a menu including all the functions available in an application (that is, all the forms and their securable subfunctions). For some applications, developers may define additional menus that restrict the application's functionality by omitting specific forms and subfunctions.

When developers define menus of functions, they typically group the subfunctions of a form on a subfunction menu they associate with the form.

When you create a menu, you typically include each form, each subfunction, and each submenu on a separate line of the menu. Generally, each form and each submenu should have a prompt so it will show up as a separate item in the Navigator window.

Important: Usually you should not include a prompt for subfunctions, as you usually do not want them to be visible to the user on the Navigator. This also applies for form functions that you may open using the CUSTOM library and Zoom, but that you do not want the user to navigate to explicitly (that is, you should include the form function on the menu so it will be available to the responsibility, but you should not give it a prompt).

See: Coding Zoom.

System Administrators Exclude Functions

Each Oracle E-Business Suite product is delivered with one or more predefined menu hierarchies. System Administrators can assign a predefined menu hierarchy to a responsibility. To tailor a responsibility, System Administrators exclude functions or menus of functions from that responsibility using exclusion rules.

When a menu is excluded, all of its menu entries, that is, all the functions and menus of functions that it selects, are excluded.

When you exclude a function from a responsibility, all occurrences of that function throughout the responsibility's menu structure are excluded.

Available Functions Depend on the Current Responsibility

When a user first selects or changes their responsibility, a list of functions obtained from the responsibility's menu structure is cached in memory.

Functions a system administrator has excluded from the current responsibility are marked as unavailable.

Form functions in the function hierarchy (that is, the menu hierarchy) are displayed in the Navigator window. Available subfunctions are accessed by working with the application's forms.

Using Form Functions

To call a form from the Navigator window menu, you define a form function that consists of your form with any arguments you need to pass. You then define a menu that calls your form function.

You should use FND_FUNCTION.EXECUTE instead of OPEN_FORM whenever you need to open a form programatically. Using FND_FUNCTION.EXECUTE allows you to open forms without bypassing Oracle E-Business Suite security, and takes care of finding the correct directory path for the form. If you need to open a form programmatically and then restart the same instance of the form (for example, with different parameters), use APP_NAVIGATE.EXECUTE instead of FND_FUNCTION.EXECUTE.

Query-Only Forms

When you define a form function in the Form Functions window or call an existing form function using FND_FUNCTION.EXECUTE or APP_NAVIGATE.EXECUTE, you can add the string:

QUERY_ONLY=YES 

to the string in the Parameters field or in the arguments string (using the other_params argument). This argument causes the form to be called in query-only mode. The FND_FUNCTION.EXECUTE procedure (which is also used by the Oracle Application Object Library Navigator) sets the QUERY_ONLY flag that sets all database blocks to non-insertable, non-updatable, and non-deletable.

To dynamically determine when to call a form in query-only mode, add the string to the other_params argument of the call to FND_FUNCTION.EXECUTE.

Disable or remove all functionality that does not apply when the form is run in Query-Only mode, such as 'New' buttons in Find Windows. Entries on the menu (other than Special) are handled automatically. Turn off any logic that defaults values into new records when the form is in Query-Only mode (this logic is usually called from the WHEN-CREATE-RECORD triggers). Check for this mode by checking the parameter query_only:

IF name_in('parameter.query_only') != 'YES' THEN
<defaulting logic here> END IF;

Important: Use query-only forms only when the user does not have update privileges on the form; not when the primary purpose of the form is viewing values.

Do not limit a form to query only because the primary need is viewing values. If the user has update privileges on a form, you should not create a separate query-only form function, even when calling the form from a special menu for the purpose of querying information. Forcing users to use the Navigator to reopen a form in an updatable mode if they need to make a change is a clear violation of our user interface standards.

There may be rare cases where technical limitations force you to limit the user to query mode on particular calls to a form. In general, however, update privileges should remain constant within a responsibility, regardless of how the user accesses the form (from a branch of the Navigator menu, or from a special menu in another form).

Form Window Name Changes

Some forms (such as the Submit Requests form) accept arguments that change the form window name. With the Submit Requests form, you use the parameter TITLE to specify the name of a message in the Message Dictionary. That message becomes the window title.

The syntax to use is:

TITLE="<appl_short_name>:<message_name>"

If the message REP_ROUTING contained (in English) the text "Report Routing", you use the argument

TITLE="MFG:REP_ROUTING" 

to open the Submit Request window with the title Report Routing.

See the Oracle E-Business Suite System Administrator's Guide for more information on customizing the Submit Requests form.

Help Target Changes

When a user selects the help button in Oracle E-Business Suite, the applications try to open the correct help file at a help target consisting of the form name and the window name: form_name_window_name. You can override the form name portion (and optionally the application short name of the help file) of this target by passing the parameter

HELP_TARGET="Application_short_name/Alternate_Form_name"

For example, to use Oracle Receivables help for the Submit Requests form, you could define your form function for the FNDRSRUN form name with the following parameter:

HELP_TARGET="AR/FNDRSRUN"

You can pass the HELP_TARGET parameter either when calling the form function using FND_FUNCTION.EXECUTE or APP_NAVIGATE.EXECUTE (using the other_params argument) or when you define the function in the Form Functions window.

See the Oracle E-Business Suite System Administrator's Guide - Configuration for more information on help targets in Oracle E-Business Suite.

Function Security Standards

The section contains the function security standards followed by Oracle developers.

General Function and Menu Standards

The Oracle E-Business Suite menu structure includes two types of items: functions, and menus of functions. Generally, functions are either forms (form functions) or subfunctions within those forms (non-form functions).

There may be some cases of functions that are neither forms nor subfunctions, but those cases should be rare, and thus are not addressed by these standards.

A "full access" responsibility with a menu that includes all the functions in an application is predefined for each Oracle E-Business Suite product and shipped to customers. This menu includes one link to each of the product's forms.

Menus are Object-based

A standard Oracle E-Business Suite menu structure is object-based (as opposed to the type of action taken on an object). It has as many levels of categorical grouping as necessary until eventually getting to a menu entry for a single object, such as Purchase Orders. All Purchase Order forms are grouped together, including transaction forms, maintenance forms, inquiry forms, and any other form that works with Purchase Orders.

Menu Categories

At the top level of a menu, two general categories should always exist: Setup and Report. The setup forms are grouped separately, since they are primarily used at installation time, and after that would be "in the way" if they were mixed with other forms. The report forms are grouped separately for users whose sole task is to run reports. Report forms are easy to secure using such a structure; moreover, reports frequently do not group purely by single object. Thus, all reports should be grouped under the Report top-level menu entry, not under other category areas or other branches.

Here is a simplified example of a product's top-level menu, with the Purchase Orders entry decomposed to a second menu level:

Purchase Orders 
    Purchase Orders          (<-Purchase Orders Gateway) 
    View Expiring Purchase Orders 
    Mass Delete Purchase Orders 
Quotes 
Suppliers 
Setup 
Reports

Reports versus Processes

If you create separate instances of the Submit Requests form to launch specific processes (programs) or groups of processes, place that form function under the appropriate object-based name in your menu. (A process is a program that manipulates data, rather than a report that only sorts or displays the data.)

In the above example, the "Mass Delete Purchase Orders" menu entry might open a specialized Submit Request window to launch the Mass Delete Purchase Order standard request submission program. Since this process deletes data, it appears under the Purchase Order menu entry rather than the Reports menu entry.

Multi-row and Single-row Displays

When you have both a multi-row and a single row display of data in a form (usually in a combination block), title the multi-row window and associated menu entry using the plural of the entity name followed by "Summary", for example: "Purchase Orders Summary". Title the single-row window (and the associated menu entry, if there is one) with the plural of the entity name, for example: "Purchase Orders". If you have only a single-row version of a form, the form name and associated menu entry are simply the plural of the entity name, for example: "Purchase Orders".

Form Function Standards

Function Names and User Function Names

The user function name (which is defined using the Form Functions form, and which is the selection value in the LOV on the Menus form) is simply the form name, for example: "Purchase Orders". It is important to follow these user function naming standards, since end users see user function names in the Navigator window's Top Ten List.

Create function names (not user function names) as: <APPLICATION_SHORTNAME>_<FORMNAME>_<MODE>. <MODE> is optional; use it if there are several functions that reference the same form. If you create a function that references a form in another product, use your products shortname as the application shortname. For example, WIP_FNDRSRUN_AUTOCREATE.

Never begin a user function name with a number, such as "2-Tier Pricing Structure", since the number would conflict visually with the Top Ten List in the Navigator window. Menu entry prompts should not have numbers anywhere in them, because the numbers would conflict with the keyboard accelerators for the Top Ten List in the Navigator.

When the same form is used for multiple functions, differing only in the parameters passed to it, make the user function name the logical name for the function, for example, "View Purchase Orders". Internally, use a function like "PO_POXPOMPO_VIEW", for example, if you want to show this is the version of the form used only for viewing purchase orders. Do not use separator characters other than underscores.

Subfunction Standards

Hide Unavailable Functions

If a subfunction determines whether a button, field, menu choice or other form item is available, code the subfunction to hide the item if the user does not have access to that function. Hide anything not enabled while the user is in the form (as opposed to item that are enabled/disabled based on actions taken in the form).

Subfunction Menus

A form may have subfunctions within it whose availability to the user is determined by responsibility. To accomplish this, a menu of these subfunctions is placed in the menu hierarchy below the level of the form. A menu of subfunctions always assumes the name of the form entry with "_MENU" appended, for example: "PO_POXPOMPO_MENU". The user menu name should be the <form name>: Subfunctions, for example: "Purchase Orders: Subfunctions".

Subfunctions are tied directly to forms in the shipped menu to make it easier for the System Administrator to understand which subfunctions are part of which forms. In other words, there is one hierarchy combining the menu structure with the security structure, as opposed to separate menu and security structures following different hierarchies.

Subfunction Names

All subfunctions for each form are predefined by the developer, and are named <form>_<subfunction>, for example: "PO_POXPOMPO_ DELETE". The user function name should be <form name>: <subfunction>, for example: "Purchase Orders: Delete". This naming standard is important because it enables the System Administrator to find all the available functions to include or exclude from a responsibility by using Autoreduction in the LOV in the Responsibilities form. For example, the System Administrator can enter "Purchase Orders", and then see the Purchase Orders form itself, the subfunctions menu(s) for that form, and all the restrictable subfunctions. Without this naming standard, it would be difficult to find all the subfunctions of a form.

Grouping Subfunctions into Categories

Where there are many restrictable subfunctions for a particular form, and those subfunctions group well into categories (Approvals, for example), group the subfunctions according to their category, creating for example, "PO_POXPOMPO_APPROVALS_MENU", linking all the approval subfunctions below it. Grouping all Approval subfunctions into a single category allows the System Administrator to restrict access to all Approval subfunctions with one menu exclusion for that responsibility.

Grouping subfunctions by category should be done only when multiple subfunction categories exist, but not when all subfunctions of a form belong to a single category. The user names for these subfunction menus and the subfunctions under them follows the standard described above for subfunctions, for example: "Purchase Orders: Approvals", "Purchase Orders: Approvals: Batch Approval". Note that the word "Menu" is not included in the subfunction menu names to help clarify that while subfunctions are stored like menus, they are not really menus in the user presentation. Instead, plurality indicates multiple subfunctions, as in "Approvals" instead of "Approval".

Forms Appearing Multiple Times in a Menu

To add a form somewhere else in the menu, the System Administrator links the form into the additional location. There is no need to create a second copy of the subfunction menu since only one is applicable per form. However, the System Administrator is free to copy what existed elsewhere, linking both the subfunction menu and form onto the new location. (The results would be the same.) It is not possible to have the same form appear with access to different subfunctions in different places on the menu.

Some forms appear several times in a menu under different function names (for example, the QuickCodes form or the Submit Request form). Do not combine subfunctions for these forms into subfunction categories. Each subfunction should exist as a separate menu entry on the form's _menu rather than on a lower level subfunction menu.

For this special case, the standard ensures that System Administrators explicitly exclude by subfunction rather than by menu. Since the form window names may change, it is not always obvious that the form appears more than once in a menu. If System Administrators try to exclude a subfunction menu, they may not realize that the menu includes another copy of that subfunction menu under a separate occurrence of the form.

Including a subfunction anywhere in a menu permits the use of that subfunction wherever it is called in the menu. Excluding a subfunction for a responsibility restricts the use of that subfunction throughout the menu.

Function Security Reports

Use the function security reports to document the structure of your Navigator menus. You can use these reports as hardcopy to document your customized menu structures before upgrading your Oracle E-Business Suite software.

The function security reports consist of the Function Security Functions Report, the Function Security Menu Report, and the Function Security Navigator Report.

These reports are available through the Function Security Menu Reports request set in the System Administrator responsibility. For each report, specify the responsibility whose function security you want to review.

Function Security Function Report

Specify a responsibility when submitting the report. The report output lists the functions accessible by the specified responsibility.

The report does not include items excluded by function security rules.

Function Security Menu Report

Specify a responsibility when submitting the report. The report output lists the complete menu of the responsibility, including all submenus and functions.

The report indicates any excluded menu items with the rule that excluded it.

Function Security Navigator Report

Specify a responsibility when submitting the report. The report output lists the menu as it appears in the navigator for the responsibility specified.

This report does not include items excluded by function security rules, or non-form functions that do not appear in the Navigator.

Function Security APIs for PL/SQL Procedures

This section describes function security APIs you can use in your client-side PL/SQL procedures.

FND_FUNCTION.TEST and FND_FUNCTION_QUERY indicate whether a particular function is currently accessible. You can construct your code to test the availability of a particular function, and then take some action based on whether the function is available or not.

You can use FND_FUNCTION.EXECUTE to execute a particular form function or self-service function.

FND_FUNCTION.TEST

Summary

function FND_FUNCTION.TEST
   (function_name IN varchar2) return boolean;

Description

Tests whether a particular function is currently accessible. Typically you would test for a function's availability at form startup (for example, to prevent certain buttons from being displayed or certain windows from being accessible).

Arguments (input)

Variable Description
function_name The name of the function to test.

Example

IF (FND_FUNCTION.TEST('DEM_DEMXXEOR_PRINT_ORDER')) THEN  
/* Put Print Order on the Special menu */     
     app_special.instantiate('SPECIAL1','&Print Order'); 
ELSE  
/* hide the corresponding button on the form
       (and the special menu is not instantiated) */
   app_item_property.set_property('orders.print_order',
                                   DISPLAYED, PROPERTY_OFF); 
END IF;

FND_FUNCTION.QUERY

Summary

 procedure FND_FUNCTION.QUERY
   (function_name   IN varchar2,
    accessible      OUT varchar2,
    function_type   OUT varchar2,
    form_path       OUT varchar2,
    arguments       OUT varchar2);

Description

Checks whether a particular function is currently accessible, and if so, returns information about the function in function_type, form_path, and arguments. If the function is not accessible, function_type, form_path, and arguments are set to empty strings.

Arguments (input)

Variable Description
function_name The name of the function to check.

Arguments (output)

Variable Description
accessible Set to 'Y 'or 'N' to indicate whether the function can be accessed by the current responsibility.
function_type The type of the function as specified in the Form Functions form.
form_path The file system path to the form (or an empty string if there is no form associated with this function.)
arguments The list of arguments specified for this function.

FND_FUNCTION.EXECUTE

Summary

 procedure FND_FUNCTION.EXECUTE
          (function_name   IN varchar2,
           open_flag       IN varchar2  default 'Y',
           session_flag    IN varchar2  default 'SESSION',
           other_params    IN varchar2  default NULL,
           activate        IN varchar2  default 'ACTIVATE',
           browser_target  IN varchar2  default NULL);

Description

Executes the specified form function. Only executes functions that have a form attached. Displays a message to the end user if the function is not accessible.

Make sure that the function is defined with Oracle Application Object Library. Also, the function must be somewhere on the menu for the responsibility, though the form does not need to be accessible from the menu in the Navigator (do this by adding the function to the menu but leaving the prompt blank). Otherwise, the user will get a message saying that function is not available.

You should use FND_FUNCTION.EXECUTE instead of OPEN_FORM whenever you need to open a form programatically. Using FND_FUNCTION.EXECUTE allows you to open forms without bypassing Oracle E-Business Suite security, and takes care of finding the correct directory path for the form.

FND_FUNCTION.EXECUTE is similar to APP_NAVIGATE.EXECUTE, except that APP_NAVIGATE.EXECUTE allows a form to be restarted if it is invoked a second time.

APP_NAVIGATE.EXECUTE and FND_FUNCTION.EXECUTE store the position and size of the current (source) window in the following global variables so that the target form being opened can access them:

The intended usage is so that the target form can be positioned relative to the current window of the calling form. When calling APP_NAVIGATE.EXECUTE, these values are available when the target form is opened the first time.

APP_NAVIGATE.EXECUTE and FND_FUNCTION.EXECUTE allow you to open functions for Oracle Self-Service Applications (self-service functions) from Oracle Forms Developer-based forms and the Navigator window as well. The arguments require URL-style syntax instead of OPEN_FORM-style syntax. You cannot use APP_NAVIGATE.EXECUTE and FND_FUNCTION.EXECUTE to open functions from Oracle Self-Service Applications, however (because these routines are contained in Oracle Forms Developer-based libraries).

Arguments (input)

Variable Description
function_name The developer name of the form function to execute.
open_flag 'Y' indicates that OPEN_FORM should be used; 'N' indicates that NEW_FORM should be used. You should always pass 'Y' for open_flag, which means to execute the function using the Oracle Forms OPEN_FORM built-in rather than the NEW_FORM built-in.
This argument is ignored if the function type is one of the following function types: WWW, WWK, JSP, or SERVELET.
session_flag Passing 'NO_SESSION' or 'N' opens the form in the same session as the existing form; passing anything else opens your form in a new database session (including 'SESSION', the default).
Opening a form in a new database session causes the form to have an independent commit cycle. You should always pass 'SESSION' or 'Y' (which has the same effect as 'SESSION' for backwards compatibility).
This argument is ignored if the function type is one of the following function types: WWW, WWK, JSP, or SERVELET.
other_params An additional parameter string that is appended to any parameters defined for the function in the Parameters field of the Form Functions form. You can use other_params to set some parameters dynamically. It can take any number of parameters.
For calling forms: if there are multiple additional parameters, the values passed to those parameters must have double quotes around them. For example, suppose a form accepts two pieces of context information to perform a query when the form is accessed from a particular window. The concatenated string to pass should have the following syntax:
 FND_FUNCTION.EXECUTE(
                    FUNCTION_NAME=> function_name,
                    OPEN_FLAG=>'Y', SESSION_FLAG=>'Y',
                    OTHER_PARAMS=> 'CONTEXT1="'||:block.context1 || ' " 
                    CONTEXT2=" || :block.context2 || ' " ');

For calling Oracle Self-Service Applications functions, anything in the other_params argument is appended to the URL as constructed from the function definition (with an ampersand & delimiter). The URL is constructed as follows:
 HTML_Call_field&Parameters_field&OTHER_PARAMS

Use URL-style syntax for other_params if you are calling a self-service function. For example, your call might look like the following:
 FND_FUNCTION.EXECUTE(
                    FUNCTION_NAME=> function_name,
                    OPEN_FLAG=>'Y', SESSION_FLAG=>'Y',
                    OTHER_PARAMS=>'partyId='||
                           to_char(:cust.party_id));
Variable Description
activate_flag Either ACTIVATE or NO_ACTIVATE (default is ACTIVATE). This flag determines whether the focus goes to the new form (ACTIVATE) or remains in the calling form (NO_ACTIVATE).
This argument is ignored if the function type is one of the following function types: WWW, WWK, JSP, or SERVELET.
browser_target Use this argument only for calling self-service functions. This argument allows you to specify which browser frame should be used. The NULL default means that the function opens in a new browser window.

Example

The following is an example of calling a form function (not a self-service function):

FND_FUNCTION.EXECUTE(FUNCTION_NAME=>'DEM_DEMXXEOR', 
    OPEN_FLAG=>'Y', SESSION_FLAG=>'Y', 
    OTHER_PARAMS=> 'ORDER_ID="'||param_to_pass1||
   '" CUSTOMER_NAME="'||param_to_pass2||'"');

FND_FUNCTION.USER_FUNCTION_NAME

Summary

 function FND_FUNCTION.USER_FUNCTION_NAME
         (function_name IN varchar2) 
          return        varchar2;

Description

Returns the user function name.

Arguments (input)

Variable Description
function_name The developer name of the function.

FND_FUNCTION.CURRENT_FORM_FUNCTION

Summary

function FND_FUNCTION.CURRENT_FORM_FUNCTION return varchar2;

Description

Returns the function name with which the current form was called.

Forms Window

the picture is described in the document text

Register an application form with Oracle E-Business Suite.

You must register a form before you can call it from a menu or a responsibility.

Before registering your form, register your application with Oracle Application Object Library using the Applications window.

Forms Block

The combination of application name and form name uniquely identifies your form.

Form

Enter the filename of your form (without an extension). Your form filename must be all uppercase, and its .fmx file must be located in the forms/<language> subdirectory of your application directory structure.

Application

This is the application that owns your form. You can define an application by using the Applications window.

Oracle E-Business Suite looks for your form in the appropriate language directory of your forms directory, based on the application owning your form.

For example, if you are using American English on a UNIX platform, Oracle E-Business Suite expects to find your form files in the directory /<Your application top directory>/forms/US.

User Form Name

This is the form name you see when selecting a form using the Functions window.