Form Personalization

Intermediate Concepts

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

 Objectives
After completing this module, you should be able to do
the following:
 Understand Trigger Events
 Build rules that fire conditionally
 Understand Sequencing
 Use string evaluation
 Use the Validate feature to confirm Conditions and
Strings
 Understand multilingual issues
 Know the most commonly used Actions
 Use debugging features

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

 Related Course Material

 This course builds on material presented in the

module Introduction to Forms Personalization, and
the viewlet Oracle Applications Form
Personalization Demonstration.
 The viewlet Oracle Applications Form
Personalization Demonstration – Intermediate
Concepts shows many of the concepts included in
this module.

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

 Agenda

 Understanding Trigger Events

 Building rules that fire conditionally
 The Sequence fields
 Triggers+Conditions+Sequences
 Working with Strings
 How to handle multiple languages
 Focus on common Properties and Builtins
 Using debugging features

1-4 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-5 Copyright © 2004, Oracle. All rights reserved.

 Trigger Events

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

 Trigger Events, continued
 All E-Business Suite forms send the following events:
– WHEN-NEW-FORM-INSTANCE: once, when the form starts up. Trigger Object does not
apply.
– WHEN-NEW-BLOCK-INSTANCE: each time the cursor moves to a new block. Trigger Object
must contain the blockname of interest.
– WHEN-NEW-RECORD-INSTANCE: each time the cursor moves to a new record. Trigger
Object must contain the blockname of interest.
– WHEN-NEW-ITEM-INSTANCE: each time the cursor moves to a new item. Trigger Object
must contain the blockname.itemname of interest.
– SPECIAL1 through SPECIAL45: each time the user selects a menu entry from the Tools,
Actions or Reports menu.
 Many forms send the following event:
– WHEN-VALIDATE-RECORD: each time the current record has any change that needed to be
validated. Trigger Object must contain the blockname of interest.

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

 Trigger Events, continued
 Some forms send custom events
– For example, a form may send a message like ‘REPRICE-ITEM’ at a
specific event within it’s processing.
– We seed the Trigger Event item with the standard events, but you can type
other events into the field too.
 It’s easy to learn what events a form sends
– From the pulldown menu select Help > Diagnostics > CustomCode > Show
Events
– Run the form of interest and a dialog will appear each time an event is sent
– Turn this mode off by selecting Help > Diagnostics > CustomCode > Normal

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

 Conditions

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

 Conditions, continued
 The Condition field lets you create an expression in SQL
– If it is empty or evaluates to TRUE at runtime, then the Actions are performed
– If it evaluates to FALSE at runtime, then the Actions are skipped
– The Condition is re-evaluated each time the rule is processed
 The Condition expression can refer to:
– bind variables, like :block.field
– SQL operators, such as ||, TO_CHAR(), DECODE(), and NVL()
– Server-side functions that do not have OUT parameters
 Validate: this will process the Condition immediately and return either True,
False, or an Error
– Errors are in standard ORACLE error format, with an ORA error number

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

 Conditions, continued

 Examples:
– :users.user_name is not null and :users.description is null
TRUE if the User Name field has a value and the Description field does not
– sysdate >= to_date(‘1-1-2005’, ‘DD-MM-RRRR’)
TRUE if today’s date is equal to or greater than January 1, 2005
 Fire in Enter-Query mode: if checked, will cause the trigger to be
processed while in QBE mode.
– It is rare that you would want this.

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

 Sequences
Both Rules and Actions have a Sequence that must
be entered
– It is there in case you need things to be processed in a
specific order
– The sequence does not have to be unique
For an Action, the Sequence is very important in
various situations, for example:
– When using Builtins, you might first move the cursor to a
particular block, then issue a query in that block
– With Properties, if you are moving an item you might first
have to make the canvas a different size

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

 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-13 Copyright © 2004, Oracle. All rights reserved.

 Triggers+Conditions+Sequences
Here’s how it all works:
When an event occurs in the form, we look for all enabled
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.

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

 Working with Strings
Every property that takes a string can work one of
two ways
 If the string you type does not start with ‘=’, then it will be
used exactly as you typed it
 If the string you type starts with ‘=’, then it will be evaluated
at runtime. You can refer to:
– bind variables, like :block.field
– SQL operators, such as ||, TO_CHAR(), DECODE(), and NVL()
– Server-side functions that do not have OUT parameters
 Validate: this will process the string immediately and return
either the result or an Error
– Errors are in standard ORACLE error format, with an ORA error
number

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

 Working with Strings, continued
String Typed In Result at Runtime
='Your password will expire on '|| Your password will expire on 31-
(sysdate+7) DEC-2004 {if sysdate is currently
24-DEC-2004}
='Your password must have at Your password must have at least
least '||:context.passwd_length||' 8 characters. {if passwd_length
characters.' has a value of 8}
=‘User: ‘||NVL(:user.user_name, User: SYSADMIN {if
‘New’) :user.user_name is ‘SYSADMIN’}
User: New {if :user.user_name is
null}
=The field value is: {an ORACLE error because the
:items.part_number syntax is incorrect. It should be:
=‘The field value is: ‘||
:items.part_number }

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

 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-17 Copyright © 2004, Oracle. All rights reserved.

 Multilingual Issues, continued
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-18 Copyright © 2004, Oracle. All rights reserved.

 Multilingual Issues, continued
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’)

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

 Common Actions of type Property (1)
 For Items (fields):
– PROMPT_TEXT: the prompt of the item, typically next to or above the
item
– DISPLAYED: if False, the item is hidden
– INITIAL_VALUE: the value to default on a new record. This can only be
set in the WHEN-NEW-RECORD-INSTANCE event
– UPDATE_ALLOWED: if False, prevents the user from changing the
value on a queried row
– LABEL: the label of a button, checkbox or radio button
– NEXT and PREVIOUS_NAVIGATION_ITEM: to control the behavior of
Tab and Shift+Tab
– REQUIRED: if True, the user must enter a value
– TOOLTIP_TEXT: the bubble tip on the item
– X and Y_POS: the location on the canvas, in inches
– WIDTH: the width, in inches
– VALUE: copy a value into the item, as if the user typed it

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

 Common Actions of type Property (2)
 For Tab Pages:
– DISPLAYED: If False, the tab page is hidden. Note that keyboard
navigation may need to be changed to prevent access to items on the
page
– LABEL: the title of the tab
 For Canvasses:
– TOPMOST_TAB_PAGE: Determines the currently selected Tab Page
 For Windows:
– TITLE: the title of the window
– X and Y_POS: the location within the MDI window, in inches

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

 Common Actions of type Property (3)
 For Blocks:
– DEFAULT_WHERE: the WHERE clause of the SQL statement
controlling queried records
– ORDER_BY: the ORDER_BY clause of the SQL statement of
the queried records
– INSERT_ALLOWED: if False, prevents the user from creating
new records
– UPDATE_ALLOWED: if False, prevents the user from updating
any item in a queried record
– DELETE_ALLOWED: if False, prevents the user from deleting
queried records

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

 Common Actions of type Builtin
 GO_ITEM and GO_BLOCK: move the cursor to a specific item or the first
item in a block
 DO_KEY: acts like a macro, simulating user actions.
– Common Arguments:
ENTER_QUERY: invoke QBE mode
EXECUTE_QUERY: execute the query
NEXT and PREVIOUS_BLOCK: move to another block
NEXT and PREVIOUS_ITEM: move to another item
 FND_UTILITIES.OPEN_URL: launch a URL. Can be as simple as
‘www.yahoo.com’, or as complex as a Discoverer page
 FND_FUNCTION.EXECUTE: open a function, applying security rules.
Parameters can be passed if the target accepts them.

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

 Common Actions of type Message
 Show: displays a message of type Note, with an OK button.
 Hint: displays text on the message line
 Error: displays a message of type Error, with an OK button.
Processing is aborted afterwards.
 Debug: displays a message of type Note, with an OK button.
– Only displays when ‘Display Debug messages’ is checked.

 Warn: displays a message of type Question, with OK and

Cancel buttons.
– If the user selects Cancel, processing is aborted.

1-24 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-25 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-26 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-27 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-28 Copyright © 2004, Oracle. All rights reserved.

 Summary
In this module, you should have learned how to:
Build rules associated with the proper Trigger Event
Build rules that fire conditionally
Use Sequencing
Use the Validate feature to confirm Conditions and Strings
Use string evaluation
Handle multilingual situations
Use the most commonly used Properties, Builtins and
Messages
Use debugging features

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