Form Personalization

Administration

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

 Objectives
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

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

 Agenda

 Securing Access
 The Architecture
 Debugging
 After Applying a Patch
 Using the Loader
 Interactions with the CUSTOM library
 Interactions with Folders
 Support

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

 WARNING!
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

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

 Securing Access
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!

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

 The Architecture
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

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

 The Architecture, continued
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

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

 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’

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

 The Architecture, continued
When 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

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

 Debugging: Performance
Conditions, 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

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

 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

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

 Debugging: Multilingual Issues
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

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

 Debugging: Numbers
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

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

 Debugging: Dates
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

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

 Debugging: why isn’t it running?
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.

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

 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

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

 Debugging: why isn’t it ‘sticking’?
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

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

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

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

 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

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

 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!

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

 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

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

 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.

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

 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.

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

 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

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

 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.

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

 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.

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

 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.

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

 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

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

 Summary
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

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