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.