Administrator Level Form Personalization

1-1 Copyright © 2004, Oracle. All rights reserved.

Form PersonalizationAdministration


After completing this module, you should be able to do the following:

Secure access to Personalizations

Understand the basic architecture

Debug Personalizations, including Performance and multilingual issues

Validate Personalizations after applying patches

Use the Loader to move personalizations between instances

Understand interactions with CUSTOM and Folders

Know when to call Oracle Support

Objectives


Agenda

Securing Access

The Architecture

Debugging

After Applying a Patch

Using the Loader

Interactions with the CUSTOM library

Interactions with Folders

Support


Form Personalizations allows you to fundamentally alter the behavior of the product that Oracle ships, and access any and all data. Therefore,

This feature should only be made available to trusted users.

Avoid building Personalizations on a production system. – Form Personalizations should first be entered and

thoroughly QA’ed on a test system before they are loaded to a production system

WARNING!


Personalizations are created by invoking Help > Diagnostics > Custom Code > Personalize on the pulldown menu

Profile ‘Hide Diagnostics menu entry’ – ‘No’: makes the Diagnostics menu entry visible– ‘Yes’: hides the menu entry completely

Profile ‘Utilities:Diagnostics’– ‘Yes’: allows direct access of the feature– ‘No’: requires entry of the Apps password first

These same profiles control access to features like ‘Examine’, ‘Item Properties’ and ‘Trace’

– Like Form Personalizations, these features can be used to change or view any data!

Securing Access


Personalizations are stored in tables, separate from the forms they alter:

FND_FORM_CUSTOM_RULES FND_FORM_CUSTOM_ACTIONS FND_FORM_CUSTOM_SCOPES FND_FORM_CUSTOM_PROP_LIST FND_FORM_CUSTOM_PROP_VALUES FND_FORM_CUSTOM_PARAMS FND_INDUSTRIES

The Architecture


At startup of each form, Rules for the current function are queried and cached in memory

Rules are queried if they are:– For the proper function– For the proper language, or ‘All’ languages– Enabled (both Rule and Action level)– List the current scope (Site, Responsibility, User, or Industry)

Industry is a feature that will be activated in a future release

Note that Personalizations are created per Function, not per Form

The Architecture, continued


Context is not a hierarchy If a Rule has a context of ‘Site’, it will be applied for everyone A rule with a context of Responsibility does not ‘override’ Site A rule with a context of User does not ‘override’ Site or

Responsibility If 2 rules have the same Trigger Event, and Actions that

change the same property, the rule with the higher sequence number will be performed last, thus it will ‘win’

The Architecture, continued


The Architecture, continuedWhen an event occurs in the form, we look for all Rules

that match that Trigger Event and Trigger Object

– Starting with the Rule that has the lowest sequence,

if the Condition is empty or evaluates to TRUE, we process each enabled Action, in the order of the Action Sequence

– Then we look for the next-highest sequenced Rule and process it, until there are no more Rules for that Event.

– Then the event is passed to the CUSTOM library


Debugging: PerformanceConditions, and some Values, are evaluated in the database Conditions create a SQL statement like:

– select 'x' from dual where <condition>; String evaluations that start with ‘=‘ create a SQL

statement like:– select <string> the_text from dual;

Strings can also include arbitrary SQL statements of the form:

– SELECT <something> A FROM <remainder of SQL> The FORMS_DDL builtin can contain arbitrary PL/SQL blocks You will see all of these in Trace files


Debugging: Performance, continued If you see an excessive number of any of

these calls, make sure they are really needed– Rules may have been defined at the wrong Trigger

Event– It might be possible to get values once and cache them

in GLOBAL variables– Strings using arbitrary SELECT statements should only

return 1 row


Some Actions are insensitive to language, such as setting the Required property for a field.

– For these, set the Language to ‘All’ But many Actions have text, such as Properties (PROMPT_TEXT, LABEL,

TOOLTIP…), Messages (Message Text), and Special (Menu Label) – For these, create one Action per language– Pick the appropriate language, and enter the proper text for that

language Don’t create Conditions that are language sensitive

– Refer to internal values of fields, not displayed values

Debugging: Multilingual Issues


You can count on numbers to be confusing! Depending on your profiles, you may see numbers in fields as

1234.56 or 1234,56 However, much of Forms Personalization involves SQL fragments,

which require that numbers always be in ‘english’ format (1234.56). So, regardless of what your current settings are, enter all numeric

values in english format Examples:

– Setting the WIDTH property: 2.5– Creating a Condition based on the value of a numeric field: :block.field >= 2.5

Debugging: Numbers


Let’s make a Date• WRONG:

sysdate >= to_date(‘1-JAN-05’)• ‘JAN’ will not mean ‘January’ in all languages• Always specify an exact mask when converting a string to a

date• Avoid Y2K issues – enter years with all 4 digits

• RIGHT:sysdate >= to_date(‘1-1-2005’, ‘DD-MM-RRRR’)• Uses a language-insensitive date mask that specifies a 4-digit year

Debugging: Dates


A rule or action may not run for a variety of reasons: The Rule or Action is not enabled The Condition has evaluated to FALSE The Trigger Event and/or Trigger Object were not what you expected The scope of the rule only consists of Responsibility, Industry and/or User, and

none is true for the current context An action is executing the Builtin 'RAISE FORM_TRIGGER_FAILURE' . That will

abort all further processing for that event. The Language of the Action, if not ‘All’, is different than what you are currently

running You have set Custom Code to ‘Off’ or ‘Core code only’ in the pulldown menu. Rules are created for a Function. You might be running the same form, but as a

different function.

Debugging: why isn’t it running?


Debugging: is it really running? It may not be obvious that your change was applied in

some cases. To resolve that:– Create a Message of Type ‘Debug’ after the Action

of interest. Add some useful text.– Save your changes.– Check the ‘Display Debug messages’ checkbox– Re-run the form– You should see your message pop up when the

proper event occurs


Often an Action may execute, but by the time control returns to the user the property you set has been overridden. What can you do?

Try performing the action at a ‘lower’ event.– Properties that affect all records of a block: set at WHEN-NEW-BLOCK-INSTANCE

or WHEN-NEW-RECORD-INSTANCE– Properties that affect a specific item in a block: set at WHEN-NEW-ITEM-INSTANCE– The downside of the ‘lower’ events is that they fire more frequently, and they may

yield a misleading UI (for example, a field may look to be updateable until you navigate into it)

Be aware of ‘item’ vs. ‘item-instance’ properties– ‘item’ level affects all instances of that item– ‘item-instance’ affects only the current row of that item– If a property is ‘off’ at item level, it cannot be turned ‘on’ at item-instance level

Debugging: why isn’t it ‘sticking’?


Debugging: how do I stop it from running?

It is possible that a change you make completely breaks a form, to the point that it will not even run! Here’s how to recover:

On the pulldown menu, choose Help > Diagnostics > Custom Code > Off

– This will disable all callouts to Forms Personalization

Run the form of interest– It should run now, because your changes were skipped

Invoke the Personalization screen and correct the problem On the pulldown menu, choose Help > Diagnostics > Custom

Code > Normal to re-enable processing of Personalizations


After Applying a Patch

A patch will not change any personalizations you have created; however, they may no longer be valid

– Objects within a form may have been renamed or deleted– Functionality at the various trigger points may have changed– Property settings could interfere with your Rules

What can you do? 1. Identify all forms affected by a patch

2. Run the personalization screen from any form and select Tools > Administration

3. Identify all forms that have Personalizations and have just been patched

4. Run each function, possibly setting Custom Code to ‘Off’ if it fails to open

5. Run the Personalization screen and select Tools > Validate All


After Applying a Patch, continued

‘Validate All’ will check all object references in your Rules: References to objects like Items and Windows for setting

properties References to :block.fields within conditions and strings that are

evaluated Errors are shown in a window that allows you to ‘Go To’ them one

at a time.

BUT ‘VALIDATE ALL’ CANNOT DO IT ALL! Even though object references may be valid, it doesn’t mean that

the end result will be what you planned There simply is no substitute for testing!


Using the Loader Download (extracting from a test system):

FNDLOAD <userid>/<password> 0 Y DOWNLOAD $FND_TOP/patch/115/import/affrmcus.lct <filename.ldt> FND_FORM_CUSTOM_RULES function_name=<function name>

– Function_name is a required parameter; if it is not supplied then no personalizations are downloaded.

– Rules can only be extracted one function at a time

Upload (inserting into a production system):FNDLOAD <userid>/<password> 0 Y UPLOAD

$FND_TOP/patch/115/import/affrmcus.lct <filename.ldt> – Before uploading, all rules for that function in the target db are

first deleted


Interactions with the CUSTOM library The CUSTOM library is an alternative mechanism for changing behavior, which

requires coding– It can do more than Form Personalization because it has the full power of

the PL/SQL

Form Personalization and CUSTOM drive off the exact same events. – Form Personalization processes them first, then passes them to the

CUSTOM library.

Both respond identically to the Custom Code events 'Normal', 'Off' and 'Core Code Only'.

Use the Form Personalization feature whenever possible– Only use the CUSTOM library when significantly more complex processing

is required.


Interactions with Folders Folders allow an end-user to 'customize' a screen by

changing the fields and records displayed. Folders are constructed differently than ‘regular’ blocks

– they include an extra block that renders the prompts for the fields

– many properties of the block are dynamically managed by the Folder code as it receives events.

– As a result, when using the Form Personalization feature on a folder block, you must be aware of certain restrictions.


Interactions with Folders, continued The following properties can only be set at form startup

(WHEN-NEW-FORM-INSTANCE). More specifically, they must be set before any folder code attempts to read the values otherwise unexpected results may occur:– PROMPT_TEXT– DISPLAYED– WIDTH– DEFAULT_WHERE– ORDER_BY– X_POSITION and Y_POSITION in a single-row folder block


Interactions with Folders, continued The following properties also have special considerations:

– ENABLED: within a folder block, it is invalid to set this property to FALSE. The cursor must be able to navigate to every item in a folder block. Consider setting ALTERABLE to FALSE instead.

– NEXT_ NAVIGATION_ITEM and PREVIOUS_NAVIGATION_ITEM: These properties have no effect in a Folder block. In a single-row folder block, the navigation sequence is computed

based on X_POSITION and Y_POSITION. The navigation sequence of a multi-row folder block cannot be

changed.


Interactions with Folders, continued When a folder loads, it will override any properties you

set– Folders can load ‘by default’, either based on User

or Responsibility– Each folder definition includes everything about

the folder including prompts, positions, size, etc.


Support Oracle supports that the feature will invoke the indicated action

at the indicated event.

We do not support:

– That all desired changes can be made

– That product team code will not override or interfere with a change

– That a personalization will work after an upgrade. Oracle Support and Development cannot provide assistance on

how you can make personalizations to a particular form using this mechanism.


Support, continued Before contacting Oracle Support, you should

always confirm that your personalizations are not the source of the problem. – Check that a problem still reproduces after

choosing Help > Diagnostics > Custom Code > Off


In this module, you should have learned how to:

• Secure access to Personalizations

Understand the basic architecture

Debug Personalizations, including Performance and multilingual issues

Validate Personalizations after applying patches

Use the Loader to move personalizations between instances

Understand interactions with CUSTOM and Folders

Know when to call Oracle Support

Summary

Administrator Level Form Personalization

Documents

Transcript of Administrator Level Form Personalization