User Profiles

Overview of User Profiles

A user profile is a set of changeable options that affects the way your applications run. Oracle Application Object Library establishes a value for each option in a user's profile when the user logs on or changes responsibility. Your user can change the value of profile options at any time. Oracle Application Object Library provides many options that your users can set to alter the user interface of your applications to satisfy their individual preferences.

You, as a developer, can define even more profile options that affect your Oracle Application Object Library-based applications. And, because you may not want your users to be able to override values for each of your options, you can define options at one or more of four levels: Site, Application, Responsibility and User. You can choose at which of these levels you want your system administrator to be able to see and update option values. You also decide which profile options defined at the User level you want your users to be able to see and update.

For example, you can define a user profile option to determine which subset of the organization's data your end user sees. From the point of view of a system administrator or end user, user profile options you define are indistinguishable from those Oracle Application Object Library provides.

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

Definitions

User Profile Levels

User profile options typically exist at Site, Application, Responsibility and User levels. Oracle Application Object Library treats user profile levels as a hierarchy, where User is the highest level of the hierarchy, followed by Responsibility, Application and at the lowest level, Site. Higher-level option values override lower-level option values.

Each user profile option ordinarily exists at each level. For example, Oracle Application Object Library provides a site-level Printer option, an application-level Printer option, and so on. Oracle Application Object Library enforces the level hierarchy to ensure that higher-level option values override lower-level values. As a result, if your Site-level Printer value is "New York", but your User-level Printer value is "Boston", your reports print on the Boston printer.

Site Level

Site is the lowest user profile level. Site-level option values affect the way all applications run at a given installation.

Application Level

Application is the user profile level immediately above Site. Application-level option values affect the way a particular application runs.

Responsibility Level

Responsibility is the user profile level immediately above Application. Responsibility-level option values affect the way applications run for all users of a responsibility.

User Level

User is the highest user profile level and is immediately above Responsibility. User-level option values affect the way applications run for an application user.

Defining New User Profile Options

When you develop a new application, you can define user profile options that affect the way your application runs. For example, you might define a user profile option to determine which subset of the organization's data your end user sees. When you define a new option, you specify criteria to describe valid values for that option. You can also specify whether your end users can change the value of an option.

You can obtain the value of a user profile option using Oracle Application Object Library routines. You can construct your application to react to the value of a profile option as you choose.

Setting User Profile Option Values

A system administrator can set values for user profile options at each profile level. You can set default values for your new profile options by using the System Administrator responsibility. Typically, a system administrator sets site-level option values after installing Oracle Application Object Library-based applications at a site. These site-level option values then work as the defaults until the system administrator or end user sets them at higher levels.

Oracle Application Object Library derives run-time values for each user's profile options based on values the system administrator sets at each level. An option's run-time value is the highest-level setting for that option. For example, for a given end user, assume the Printer option is set only at the Site and Responsibility levels. When the end user logs on, the Printer option assumes the value set at the Responsibility level, since it is the highest-level setting for the option.

If the default value of a user profile option at any level is inappropriate, the system administrator can change it at any time. This change takes effect as soon as end users log on again or change responsibilities.

Setting Your Personal User Profile

Oracle Application Object Library establishes values for user profile options when you log on or change responsibilities. You can change the value of your own user-changeable options at any time.

You change an option value using the Update Personal Profile Options form. Using this form, you can display all your options and review the values your system administrator has set for them. You can also change those that are updatable if you like. Any change you make to a User-level profile option has an immediate effect on the way your applications run for that session. And, when you log on again, changes you made to your User-level options in a previous session are still in force.

If you never set your own User-level option values, your user profile options assume the Site-, Application-, Responsibility-, or User-level values your system administrator has set for them. Only the system administrator can set some profile options.

Implementing User Profiles

You should define user profile options whenever you want your application to react in different ways for different users, depending on specific user attributes.

To provide maximum flexibility, user profiles exist at Site, Application, Responsibility and User levels. When you define a profile option you decide whether your system administrator can set values for your option at each of these levels. You also decide whether your end users can view and update options you define at the User level. For example, you could define a VIEW_SECURE_INFORMATION option to be visible and updatable at all levels, so a system administrator could set values at any level, including values for individual users. You would also define the option such that your end users could not see or change its value.

Oracle Application Object Library provides many options that your users can set according to their needs. You can use these options, and profile options you define, in your application forms and concurrent programs.

Predefined User Profile Options

Database Profile Options

Oracle Application Object Library provides many user profile options that the Oracle E-Business Suite System Administrator or the users can see and update. The Oracle E-Business Suite System Administrator's Guide - Maintenance manual contains a complete list of predefined profile options.

Internally Generated Profile Options

Oracle Application Object Library also provides a set of profile options that you can access via the user profile routines. You can retrieve values for these profile options in your forms and programs; however, except for the profiles CONC_PRINT_OUTPUT and CONC_PRINT_STYLE, you cannot change their values. System administrators and end users cannot see the values for, nor change the values of, these profile options.

Variable Description
USERNAME Your user's current Oracle Application Object Library username.
USER_ID Your user's current Oracle Application Object Library user ID.
RESP_ID Your user's current responsibility ID.
APPL_SHRT_ NAME The short name of the application connected to your user's current responsibility.
RESP_APPL_ID The application ID of the application connected to your user's current responsibility.
FORM_NAME The name of the current form. Not available for concurrent programs.
FORM_ID The form ID of the current form. Not available for concurrent programs.
FORM_APPL_ NAME The name of the application for which the current form is registered. Not available for concurrent programs.
FORM_APPL_ID The application ID of the application for which the current form is registered. Not available for concurrent programs.
LOGON_DATE Your user's logon date for the current session.
LAST_LOGON_ DATE Your user's logon date for the previous session.
LOGIN_ID Your user's Sign-On Audit login ID in Oracle Application Object Library.
CONC_ REQUEST_ID The request ID associated with a particular instance of your running current program. You can only use this profile option in a concurrent program. You use this profile option to fill the REQUEST_ID Who column.
CONC_ PROGRAM_ID The program ID associated with a running current program. You can only use this profile option in a concurrent program. You use this profile option to fill the PROGRAM_ID Who column.
CONC_ PROGRAM_ APPLICATION_ ID The application ID associated with a running current program. You can only use this profile option in a concurrent program. You use this profile option to fill the PROGRAM_APPLICATION_ID Who column.
CONC_LOGIN_ ID The login ID associated with a running concurrent program. You can only use this profile option in a concurrent program. You can use this profile option to fill the LAST_UPDATE_LOGIN Who column.
CONC_PRINT_ OUTPUT The value Yes or No that you enter in the Print Output field when you register a concurrent program. You can use the routine afpoput() from your concurrent programs to change the value of this profile option for a particular instance of your running concurrent program. This profile option determines whether the concurrent managers print the concurrent program's output to the printer.
CONC_PRINT_ STYLE The print style of your concurrent program's output that you enter in the Print Style field when you register a concurrent program. You can use the routine afpoput() from your concurrent programs to change the value of this profile option for a particular instance of your running concurrent program.

FND_PROFILE: User Profile APIs

This section describes user profile APIs you can use in your PL/SQL procedures. You can use these user profile routines to manipulate the option values stored in client and server user profile caches.

On the client, a single user profile cache is shared by multiple form sessions. Thus, when Form A and Form B are both running on a single client, any changes Form A makes to the client's user profile cache affect Form B's run-time environment, and vice versa.

On the server, each form session has its own user profile cache. Thus, even if Form A and Form B are running on the same client, they have separate server profile caches. Server profile values changed from Form A's session do not affect Form B's session, and vice versa.

Similarly, profile caches on the server side for concurrent programs are separate. Also, note that the server-side profile cache accessed by these PL/SQL routines is not synchronized with the C-code cache. If you put a value using the PL/SQL routines, it will not be readable with the C-code routines.

Any changes you make to profile option values using these routines affect only the run-time environment. The effect of these settings ends when the program ends, because the database session (which holds the profile cache) is terminated. To change the default profile option values stored in the database, you must use the User Profiles form.

FND_PROFILE.PUT

Summary

 procedure FND_PROFILE.PUT
      (name IN varchar2,
       valueIN varchar2);

Location

FNDSQF library and database (stored procedure)

Description

Puts a value to the specified user profile option. If the option does not exist, you can also create it with PUT.

All PUT operations are local -- in other words, a PUT on the server affects only the server-side profile cache, and a PUT on the client affects only the client-side cache. By using PUT, you destroy the synchrony between server-side and client-side profile caches. As a result, we do not recommend widespread use of PUT.

Arguments (input)

Variable Description
name The (developer) name of the profile option you want to set.
value The value to set in the specified profile option.

FND_PROFILE.GET

 procedure FND_PROFILE.GET
     (name IN varchar2,
      value OUT varchar2);

Location

FNDSQF library and database (stored procedure)

Description

Gets the current value of the specified user profile option, or NULL if the profile does not exist. All GET operations are satisfied locally -- in other words, a GET on the server is satisfied from the server-side cache, and a GET on the client is satisfied from the client-side cache.

The server-side PL/SQL package FND_GLOBAL returns the values you need to set Who columns for inserts and updates from stored procedures. You should use FND_GLOBAL to obtain Who values from stored procedures rather than using GET, which you may have used in prior releases of Oracle E-Business Suite.

Arguments (input)

Variable Description
name The (developer) name of the profile option whose value you want to retrieve.

Arguments (output)

Variable Description
value The current value of the specified user profile option as last set by PUT or as defaulted in the current user's profile.

Example

 FND_PROFILE.GET ('USER_ID', user_id);

FND_PROFILE.VALUE

Summary

 function FND_PROFILE,VALUE
     (name IN varchar2) return varchar2; 

Location

FNDSQF library and database (stored function)

Description

VALUE works exactly like GET, except it returns the value of the specified profile option as a function result.

Arguments (input)

Variable Description
name The (developer) name of the profile option whose value you want to retrieve.

User Profile C Functions

Oracle Application Object Library provides you with two functions you can call from concurrent programs you write in the C programming language. You can use these functions to store and retrieve profile option values.

afpoget

Get the current value of a profile option. Returns TRUE if successful, FALSE if it cannot find the profile option value. Returns FALSE when retrieving a profile that exists but has no value. You must include the file fdpopt.h in your C code file (#include <fdpopt.h>) to use this C function. For concurrent programs, the current user is the user who submitted the concurrent request, and afpoget() reads the value at the time the request runs, not the time the user submitted the request. When the function afpoget() returns successfully, it sets option_value to the value of your requested user profile option. If you are not sure of the length of the value afpoget() will return, you should define option_value[] to be at least 241 characters long.

Syntax

boolean afpoget(option_name, option_value) 
     text   *option_name; 
     text   *option_value;
Variable Description
option_name The name of the profile option.
option_value the profile option value returned by the function.

afpoput

Change the value of a profile option for the current session. Create a profile option. Returns TRUE if successful, FALSE if it tries to change the value of a profile option for which the WRITE flag is set to No, or if it tries to create a profile option for which the ENABLE_CREATE flag is not set. You must include the file fdpopt.h in your C code file (#include <fdpopt.h>) to use this C function.

Use ENABLE_CREATE if you afpoput() to create an option if the option does not exist. This new option only exists within the current concurrent process, and it is not available to other processes. You can use the | (bitwise OR) operator to combine ENABLE_CREATE with the options ENABLE_WRITE and/or ENABLE_READ. You cannot use ENABLE_WRITE or ENABLE_READ to reset the privileges of an existing profile option. Use ENABLE_WRITE if you want to allow subsequent calls to afpoput() to change the value. Use ENABLE_READ if you want to allow subsequent calls to afpoput() to read the value.

Syntax

boolean afpoput(option_name, option_value) 
     text   *option_name; 
     text   *option_value;
Variable Description
option_name The name of the profile option.
option_value The value to which you wish to change the profile option for the current session. All values are stored as text. The value may be at most 240 characters.

Profiles Window

Define a user profile option. You define new user profile options when you build an application. Once you define an option, you can control access for it at different profile levels.

Before defining your user profile options, define your application using the Applications window.

Profiles Block

You identify a profile option by application name and profile option name.

Name

The profile option name must be unique so that different profile options do not conflict. This is the name you use when you access your profile option using the Oracle Application Object Library profile option routines.

Application

Normally, you enter the name of the application you are building.

User Profile Name

This is the name your users see as their profile option, so it should be short but descriptive.

Description

Provide a better explanation of the content or purpose of this profile option. This description appears in a window with User Profile Name when a user or system administrator chooses profile options to set values.

Hierarchy Type

Choose a hierarchy type for the profile option. The types to choose from are: Security, Server,Server+Responsibility, and Organization.

Hierarchy types enable system administrators to group and set profile options according to their business needs or the needs of the installation.

The default hierarchy type is Security. Profile options that existed before this enhancement that have not been updated use the type Security.

The Server hierarchy type is used when the system needs to determine the server on which the user's session is running. For example, the profile "Applications Web Agent" can be defined using the Server type. The setting of this profile option can differ for an internal server versus an external one. Cookie validation, for example, can then be done against the value of this profile option.

With the Server+Responsibility, you can control the value of a profile option for a particular combination of a server and responsibility.

With the Organization hierarchy type, organization refers to operating unit. For example, clerks in different organizations may need to have different values for a given profile option, depending on their organization, but clerks in the same organization would use the same value. The Organization hierarchy type allows system administrators to set a profile option at the organization level, so that all users within that organization will use the profile option value set once at the organization level.

Profiles that use the Security hierarchy type follow the traditional hierarchy: Site > Application > Responsibility > User. Profiles using the Server type use the hierarchy Site > Server >User. Profiles using the Organization type use the hierarchy Site > Organization > User.

Hierarchy Type Access Level

Define the characteristics of your profile option at each profile level that the system administrator uses to define profile values.

Depending on the hierarchy type you chose for your profile, you can define the characteristics at the Site, Application, Responsibility, Server, Server+Responsibility, Organization, and User levels.

Tip: You should specify Site-level characteristics of every user profile option you create so that the system administrator can assign a Site-level value for every profile option.

You should provide access to each option at the Site level.

Profile option values set at the User profile level override values set at the Responsibility profile level, which override values set at the Application profile level. If no values are set at these three levels, then the value defaults to the value set at the Site profile level if the Site level value has been set.

If you want your end user to be able to update profile option values in the Profile Values window, that is, you chose Updatable in the User Access region, you must provide user visible and updatable access at the User level here.

Active Dates - Start/End

Enter the dates on which the profile option becomes active/inactive. The start date defaults to the current date, and if the end date is not entered, the option will be effective indefinitely. Enter the current date if you want to disable the user profile option. If you wish to reactivate a disabled profile option, change the End Date to a date after the current date.

User Access

SQL Validation used for the Profile Option's List of Values

If you want your profile option to provide a list of values (LOV) when the system administrator or user sets profile options, you must use the following syntax in the SQL Validation field. To validate your user profile option, select the profile option value into the fields :PROFILE_OPTION_VALUE and :VISIBLE_OPTION_VALUE. The Profile Values form uses these fields to ensure that your user enters valid values for your profile option.

Syntax

SQL="SQL select statement"
COLUMN="column1(length), column2(length),..."
[TITLE="{title text|*application shortname:message name}"]
[HEADING="{heading1(length), heading2(length),...
          |*application shortname:message name|N}"]

SQL

A SELECT statement that selects the rows to display in your LOV. In the SQL statement you can specify column aliases, use an INTO clause to put values into form fields, display database values without selecting them into form fields (by selecting values INTO NULL), and mix values to put into form fields with display only values in the same INTO clause.

If you specify more than one column in your COLUMN option, the LOV displays the columns in the order you specify in your COLUMN statement.

Tip: Column aliases cannot be longer than 30 characters. Larger identifiers will cause errors.

The HEADING option overrides the COLUMN lengths and aliases.

This SQL statement differs from a normal SQL statement in some ways. First, if you want to include spaces in your column aliases, you must put a backslash and double quotes before and after the column alias, so that the LOV routine recognizes the double quotes as real double quotes, rather than the end of your parameter. For example, your SQL option might look like the following example:

SQL="SELECT SALES_REPRESENTATIVE_ID,
  SALES_REPRESENTATIVE_NAME 
  INTO :PROFILE_OPTION_VALUE,
  :VISIBLE_OPTION_VALUE 
  FROM OE_SALES_REPRESENTATIVES 
  ORDER BY SALES_REPRESENTATIVE_NAME"   

We recommend that you provide aliases for your column headings in the HEADING options below.

You can use GROUP BY or HAVING clauses in your SQL statement, but only in your main query; you cannot use them in sub-queries. You can use DISTINCT and ORDER BY clauses as you would normally.

Set functions such as MIN(), MAX(), SUM(), and COUNT() can be used in the SELECT or HAVING clause, but you cannot use them on the columns that you select into the PROFILE_OPTION_VALUE or VISIBLE_OPTION_VALUE fields.

Though you can use a fairly complex WHERE clause and/or an ORDER BY clause in your SQL definition, you cannot use UNION, INTERSECT, or MINUS in your main query. If you need a UNION, INTERSECT, or MINUS to select the proper values, you should create a view on your tables, then select from the view, or include these operators as part of a sub-query.

In addition, you cannot use a CONNECT BY or any other operation that would come after the WHERE clause of a SELECT statement.

Finally, if you use OR clauses, you should enclose them in parentheses.

We recommend that you put parentheses around complex columns in your SQL SELECT statements. For example, your SQL option could look like this:

SQL="SELECT (DEPTNO ||':' ||DEPT_NAME)
  Department, LOCATION INTO
  :DEPT.DEPTNAME, :DEPT.LOCATION
  FROM DEPARTMENT" 

COLUMN

Lists the names of columns (or column aliases) you want to display in your LOV window, the order in which to display them, and their display widths. If you specify more than one column in your COLUMN option, your LOV displays the columns in the order you list them. This order can differ from the column order in your SQL statement. You must specify column widths in the COLUMN= "..." parameter, although any column widths you specify in the HEADING="..." option below override these values.

You can specify static or dynamic column widths in your COLUMN option. Specify a static column width by following the column name with the desired width. Specify a dynamic width column by placing an asterisk instead of a number in the parentheses following the column name. When you specify dynamic width for a column, the LOV adjusts the size of the displayed column to accommodate the longest value in the list. Note that a dynamic column width may vary based on the subset of data queried. The following example shows a possible COLUMN option corresponding to the department and location example, and illustrates the use of static and dynamic column widths.

COLUMN="Department(20), LOCATION(*)"  

If you do not use the HEADING option to supply column heading or suppress headings, then the LOV uses the names and widths from your COLUMN option to display the column headings. If you specify a column alias in your SQL statement and you want that column to appear in your LOV window, you must use that column alias in COLUMN. The column headings appear in the LOV window with the same upper- and lowercase letters as you define here. If your column alias has two words, you must put a backslash and double quotes on both sides of the alias. Column aliases cannot be longer than 30 characters. Using the first example from the SQL option, your COLUMN option would look like this:

COLUMN="\"Sales Representative\"(30)"   

If your display width is smaller than your column name or column alias, the LOV uses the length of the column name or alias, even if you suppress headings in your LOV window (see the HEADING option). For your values to display properly, you must specify a number for the column width.

TITLE

Text you want to display centered and highlighted on the top line of your LOV window. The default is no title. You can specify a Message Dictionary token in your LOV definition by providing the application short name and the message name. Any title starting with "*" is treated as a Message Dictionary name, and the message contents are substituted for the title. For example:

TITLE="*FND:MY_MESG_NAME"

HEADING

Lets you specify a list of column headings and column widths, separated by spaces or commas. There should be one heading in the HEADING="..." parameter for each column in the COLUMN="..." parameter. Specify column widths as numbers in parentheses following the column name, or as an asterisk in parenthesis for a dynamic column width.

Column widths you specify in the HEADING ="..." parameter override columns widths you specify in the COLUMN="..." parameter. We recommend setting the widths in the COLUMN option to * (dynamic width) when using the HEADING and COLUMN options together.

You can suppress headings in your LOV window altogether by setting HEADING="N".

You can specify a Message Dictionary token in your LOV definition by providing the application short name and the message name. Any heading starting with "*" is treated as a Message Dictionary name, and the message contents are substituted for the heading. For example:

HEADING="*FND:MY_MESG_NAME(*)"  

If you do not provide an explicit TITLE and HEADING in your SQL validation, your profile has TITLE="user_profile_option_name" and HEADING="N" appended to the definition at runtime. This appended title overrides any heading defined in a COLUMN token or aliases in the SQL statement.

For example, suppose you have an option called SECURITY_LEVEL that uses the codes 1 and 2 to represent the values High and Low respectively. You should select the code column into :PROFILE_OPTION_VALUE and the meaning column into :VISIBLE_OPTION_VALUE. Then, if you want to change the meaning of your codes, you do not have to change your program or form logic. If the value of your profile option is user-defined, you can select the value into both fields. For example, suppose you have a table and form where you maintain equipment information, and you have a profile option called EQUIPMENT. You can select the same value into both :PROFILE_OPTION_VALUE and :VISIBLE_OPTION_VALUE.

Here is an example of a definition for a new profile option called SET_OF_BOOKS_NAME.

SQL="SELECT SET_OF_BOOKS_NAME, SET_OF_BOOKS_NAME \"Set of Books\" '
INTO :PROFILE_OPTION_VALUE, :VISIBLE_OPTION_VALUE,
FROM SETS_OF_BOOKS"
COLUMN="\"Set of Books\"(30)"   

If you do not enter validation criteria in this field, your user or system administrator can set any value for your profile option, if you allow them to update it.

If Oracle Application Object Library cannot successfully perform your validation, it does not display your profile option when the user queries profiles options. If the profile option Utilities:Diagnostics is No, then no error messages appear either. For example, if a user cannot access the table you reference in your validation statement, Oracle Application Object Library does not display the profile option when the user queries profile options on the Profile Values window, and does not display any error message if Utilities:Diagnostics is set to No.