Forms PersonalizationOracle Applications

Release 11.5.10

2 Version 1.0

Objectives of this session

1. Forms Personalization: Need and benefits.

2. Understand Rules, Condition, Context and Actions.

3. Build rules that fire conditionally.

4. Understand Sequencing.

5. Use string evaluation.

6. Use Validate feature to confirm Conditions & Strings.

7. Understand Multilingual Issues.

8. Know the most commonly used Actions.

9. Debugging features available in Personalization.

10. Form Personalization v/s Form Customization.

11. Personalization Database Tables

3 Version 1.0

» The Form Personalization feature allows you to declaratively alter the behavior of Forms-based screens, including…

• Changing properties• Executing built-ins• Displaying messages• Adding menu entries.

» Form Personalization is independent to each form. This means the personalization done on one form will not reflect on other form.

» The form mainly contains four sections. They are…

• Rules, Conditions• Context• Actions

The NeedMost of the customers wish to modify the way the forms look and behave. They want to change the labels on the form fields, hide fields, hide buttons, amend custom logic etc.

The motives could beManaging un-necessary fields.To match the customer specific business requirements.To match the language (lingo) used by the customer.

What is Forms Personalization ?

4 Version 1.0

1. 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.

2. Avoid building Personalizations on a production system directly. Form Personalizations should first be entered and thoroughly tested on a Test System before they are actually loaded to a production system.

Warning

Important:

By default the “Personalize” menu is visible to all the users; this can be controlled with help of profile options. By setting up the below profile options, the access to the Personalize menu can be limited for the authorized users. This will prevent unauthorized users from changing the look and behavior of the forms.

The profile options are • Utilities: Diagnostics = Yes/No • Hide Diagnostics = Yes/No

W A

R N

I N G

5 Version 1.0

How to Invoke Forms Personalization

Menu Navigation: Help Diagnostics Custom Code Personalize

6 Version 1.0

Rules

1. Rules administer the personalization needs to be implemented on the form.2. Each rule contains a sequence number and the description. 3. The rule can be activated or de-activated using the “Enabled” checkbox.4. The rule can be deleted when no longer needed.5. Defining rules doesn’t identify when the rule should get evaluated or

applied. For each rule, there should be conditions attached which power the execution of the rule.

For example: 1. A Rule can be “Change the Order Number prompt to Claim Number”. 2. Hide Customer field.

7 Version 1.0

Condition

Trigger Object

Trigger Event

Condition

Processing Mode

Validate

8 Version 1.0

Condition

Condition decide the event the rule to be executed.

» Each condition mainly contains three sections. They are…

» Trigger Event: Trigger Event specifies the occurrence where the rule should be executed.

» Trigger Object: Trigger Object is the object on the form to determine at what level the rule should be

executed.

The values can be “<Form Name>”, ‘<Block Name>” or “<Item Name>”

» Condition: Condition is any SQL statement to control the execution of rule when the mentioned criterion is

met.

9 Version 1.0

Condition : Trigger Event & Trigger Object

10 Version 1.0

• 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.

Condition : Trigger Event & Trigger Object

11 Version 1.0

• 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.

• 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.

Note: To Know what events a form sends :

1. Menu Navigation: Help Diagnostics Custom Code Show Events

2. Run the form of interest and a dialog will appear each time an event is sent

3. Turn this mode off by selecting Help > Diagnostics > CustomCode > Normal

Condition : Trigger Event & Trigger Object

12 Version 1.0

Condition: Condition / Process Mode / Validate

13 Version 1.0

I. Condition :

1. 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.

2. The Condition expression can refer to:– Bind variables, like :block.field– SQL operators, such as || (Concatenation), TO_CHAR( ), DECODE( )

and NVL( )– Server-side functions that do not have OUT parameters.

Examples:

1. :users.user_name is not null and :users.description is nullTRUE if the User Name has a value & the Description doesn’t

have value 2. sysdate >= to_date(‘1-1-2005’, ‘DD-MM-RRRR’) TRUE if today’s date is equal to or greater than January 1, 2005.

Condition: Condition

14 Version 1.0

Condition: Processing Mode & Validate

II. Processing Mode:

1. Not in Enter Query Mode: The Rule will not be executed in Enter Query Mode. 2. Only in Enter Query Mode: The Rule will be executed in Enter Query Mode

only. 3. Both: The Rule will be executed in both the Enter & Execute query modes.

III. Validate :

1. When you press the Validate button, the Condition will process immediately and return either True, False, or an Error.

2. Errors are in standard ORACLE error format, with an ORA error number.

15 Version 1.0

Context

16 Version 1.0

Context manages to whom the personalization should apply.

• This is similar to the concept of using profile options in Oracle Applications with a slight difference. We will see this in next slide.

• The various levels are Site, Responsibility, Industry and User.

• During runtime, the values provided in the context are evaluated and personalization rules will be applied.

• Usage of context is very vital in implementing the personalization to prevent the inappropriate users accessing these personalization of the form.

Example : Context = Responsibility Value = Customer Support

• The scope of 'Industry' is reserved for future.

Context

17 Version 1.0

1. If a Rule has a context of ‘Site’, it will be applied for everyone.

2. A rule with a context of Responsibility does not ‘override’ Site.

3. A rule with a context of User does not ‘override’ Site or Responsibility.

4. 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’.

Context is not a hierarchy

18 Version 1.0

Actions

19 Version 1.0

Actions

Actions decide the exact operation to be performed when the conditions and context return TRUE during the runtime.

• Usually each rule should be associated with at least one action.

• The types of actions available are…• Property• Message• Builtin• Special

• Each Action contains a Sequence number, Description and Language.

• Based on the action type selected, the fields on the right sector of the actions tab will be refreshed where the action parameters are entered.

• Actions can be enabled, disabled or deleted.

20 Version 1.0

Actions: Sequence

1. Both Rules and Actions have a Sequence that must be entered.

2. It is there in case you need things to be processed in a specific order.

3. The sequence does not have to be unique.

4. 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.

21 Version 1.0

Actions Type: Property

The action type “Property” is used to set the properties of the objects.

• The various objects include “Item, Window, and Block etc”.• Actual object name defined in the form should be entered after

selecting the object type.• Property Name is the Property to be changed.• Value is the new desired value for the property.• The current value of the property will be displayed when clicked

on the “Get Value” button.Example: Object Type = “Item”,

Target Object = “:ORDER.ORDER_NUMBER” Property Name = “PROMPT_TEXT” Value = “Claim Number”

• The value can be interpreted at runtime, so you can use SQL functions and operators.

• Any value start with “=” operator will be interpreted at runtime, • otherwise the value is treated as is entered in the value field. Example: Value => =’Welcome to the Sales Order Entry Mr. ‘||user.

22 Version 1.0

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• LABEL: The label of a button, checkbox or radio button• 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.

Common Actions of type Property

23 Version 1.0

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 inchesFor 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

Common Actions of type Property

24 Version 1.0

Actions Type: Message

• The action type “Message” is used to display custom messages during runtime.

• Message Type and Description should be entered after selecting the action type as “Message”.

• The available message types are

Show Hint Error Debug Warn

• Depending on the response expected from the user, the appropriate message type should be selected.

Example: Message Type = “Hint”Message Text = “Please Follow the Date format DD-MON-YYYY”

25 Version 1.0

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.

Common Actions of type Message

26 Version 1.0

Actions Type: Builtin

The action type “Builtin” is used to execute the form and AOL API’s.

Depending on the API type selected, the parameters should be entered.

Example: Builtin Type = FND_UTILITIES.OPEN_URLArgument = http://dms.dell.com

27 Version 1.0

• 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.

Common Actions of type Builtin

28 Version 1.0

Actions Type: Special

29 Version 1.0

Actions Type: Special

The action type “Special” is used to activate the available specialmenus on the Tools menu.

• Oracle Applications provide 45 special menus under Tools menu which can be used by customers based on their requirements.

• Select the SPECIAL menu which is not used by the form. • Menu label is the prompt which appears to the users when Tools menu is

invoked, block specifies the blocks for which the special menu should be activated

• Icon name is the .ico file name.

• A separator can be created above the activated special menu by selecting the “Render line before menu” checkbox.

Example:Menu Entry = SPECIAL4Menu Label = Additional Customer InformationEnabled in Blocks(s) = CustomerIcon Name = Flower.ico

30 Version 1.0

Triggers » Conditions » Sequences » Actions

In short 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.

31 Version 1.0

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 etc– SQL operators, such as ||, TO_CHAR(), DECODE(), and NVL()– Server-side functions that do not have OUT parameters.

Working with Strings in Value Field

String Typed In Result at Runtime

='Your password will expire on '||(sysdate+7)

Your password will expire on 31-DEC-2004 {if sysdate is currently 24-DEC-2004}

='Your password must have at least '||:context.passwd_length||' characters.'

Your password must have at least 8 characters. {if passwd_length has a value of 8}

=‘User: ‘||NVL(:user.user_name, ‘New’)

User: SYSADMIN {if :user.user_name is ‘SYSADMIN’} User: New {if :user.user_name is null}

=The field value is: :items.part_number

{an ORACLE error because the syntax is incorrect. It should be: =‘The field value is: ‘|| :items.part_number}

32 Version 1.0

• 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

Multilingual Issues

33 Version 1.0

• 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

Multilingual Issues

34 Version 1.0

Let’s Check for 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’)

Multilingual Issues

35 Version 1.0

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 ?

36 Version 1.0

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.

Debugging: Is it really running ?

37 Version 1.0

Often an Action may execute, but by the time control returns to the user theproperty 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 is sticking ?

38 Version 1.0

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.

Debugging: How to stop personalization ?

39 Version 1.0

Form Personalization v/s Form Customization

Personalization Customization

Not Require CUSTOM library Mainly use CUSTOM library

For a limited functionality like hiding columns, changing labels and showing custom messages etc. (Look & Feel)

To Implement the complex business logic

Easy, faster and requires minimum development effort.

Depends on the complexity of business logic and require considerable development effort.

Doesn’t violate the support from Oracle and these rules also conceded with the future upgrades without any additional effort.

40 Version 1.0

Form Personalization: Database Tables

Some of the Important Database tables for personalization

FND_FORM_CUSTOM_RULES

FND_FORM_CUSTOM_ACTIONS

FND_FORM_CUSTOM_PARAMS

FND_FORM_CUSTOM_PROP_LIST

FND_FORM_CUSTOM_PROP_VALUES

FND_FORM_CUSTOM_SCOPES

41 Version 1.0

In this session we have seen :

• Forms Personalization

• 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

Summary

42 Version 1.0

Thank You