Form-Personalization Oracle Edu

Copyright © 2004, Oracle. All rights reserved.

Form Personalization

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

ObjectivesAfter completing this lesson, you should be able to do the following:

• Understand the basic concepts of Form Personalization: Rules and Actions

• Implement a variety of common Form Personalizations

• Understand the intermediate concepts of Form Personalization: Triggers, Conditions, Multi-Lingual issues, and Debugging

• Understand the advanced concepts of Form Personalization: Global variables, Query-by-Example mode, Special menu entries, and Zooms

• Understand Form Personalization administration: Security, Loading, and Performance


WARNING!

Form Personalization allows for fundamental alterations in the behavior of forms. Please take the following precautions when implementing form personalizations.

• Only allow trusted users access to the feature.

• Thorough plan and test all form personalizations on a test system before moving your form personalizations to the product server.


Overview

Form Personalization allows declarative changes that alter the behavior of Oracle Forms-based screens, including changing properties, executing built-ins, displaying messages, and adding menu entries.


Basic Concepts

• Rules– Event– Condition– Scope

• Actions– Set a property– Execute a built-in– Display a message– Enable a special menu entry


Creating a Form Personalization

• Run the form for which you want to create a form personalization.

• Select Help > Diagnostics > Custom Code > Personalize from the menu.

• The form personalization screen will open, and any existing rules for that form will be queried.


Rules


Rules About RulesRules govern when form personalizations get applied. Each rule consists of the following fields:• Function Name: the name of the function you ran.

Personalizations are made for a function, not a form.• Seq: an ordering from 1 (first) to 100 (last)• Description: optional entry that allows you to record

why you are making the personalization• Enabled: flag used to enable or disable a rule• Trigger Event: the event within the form that causes

invocation of the rule• Trigger object: the context for the trigger event, such as

a particular block or item• Condition: an optional SQL fragment that, when it

evaluates to TRUE, allows the rule to execute.


More Rules About RulesEach rule consists of the following fields (continued):• Fire in Enter-Query Mode: checkbox that controls

whether rules should be processed during enter-query mode processing (QBE)

Context controls to whom form personalizations are applied. At runtime, if the user matches any context of the rule, the rule is applied.• Level: the level at which the rule should be applied,

Site, Responsibility, User or Industry• Value: based on the level, either Disabled or Enables

and Required, in which case it will validate against a list of values


Actions


Rules About ActionsActions govern what the form personalizations does when it is applied. Each action consists of the following fields:• Seq: an ordering from 1 (first) to 100 (last)• Type: Property, Message, Built-in, or Special

– Depending on the Type, the panel will change to show additional fields

• Description: optional entry that allows you to record why you are making the personalization

• Language: a list of installed languages and ‘ALL’– An action associated with a specific language will only be

executed in the context of that language

• Enabled: flag used to enable or disable an action• Apply Now (button): For several types, this button will

be enabled. It allows you to apply changes immediately to target form to test its effect.


Actions: Property

Used to set a property of an item


Actions: Property Example

This action:

Changes this screen: To this:


Actions: Message

Used to display a pop-up message


Actions: Message Example

This action:

Causes this dialog to appear:


Actions: Built-in

Used to perform processing by calling Oracle Forms

and Application Object Library (AOL) functions.


Actions: Built-in Example

This action:

Opens the Responsibilities form (if the user has permission):


Actions: Special

Used to activate up to 45 pre-seeded menu entries


Actions: Special Example

This action:

Activates the Tools menu and creates the menu entry, for all blocks of the form:


Evaluating Strings

Every property that takes a string can work one of two ways.• If the string you type does not start with ‘=’, then it

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


Evaluating Strings Example

This action:

Causes this dialog to appear

(when run on 25-AUG-04):


Intermediate Concepts

• Triggers• Conditions• Sequences• Contexts• String Evaluation• Multi-Lingual Issues• Common Actions• Debugging


Triggers

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.


More Triggers

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.

It’s easy to learn what events a form sends:• From the pulldown menu select Help > Diagnostics >

Custom Code > 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 >

Custom Code > Normal


ConditionsThe 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

processedThe 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

parametersValidate: 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


More ConditionsExamples:• :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.


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 Built-ins, 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


Contexts

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


How It 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.


More Strings

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 }


Multi-Lingual 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


Number Issues

• 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


Date Issues

• 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’)


Common Actions of Type: Property

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


More Common Actions of Type: PropertyFor 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 tabFor Canvasses:• TOPMOST_TAB_PAGE: Determines the currently selected

Tab PageFor Windows:• TITLE: the title of the window• X and Y_POS: the location within the MDI window, in inches


Even More Common Actions: Property

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


Common Actions of Type: Built-in

• 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 modeEXECUTE_QUERY: execute the queryNEXT and PREVIOUS_BLOCK: move to another blockNEXT 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: 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.


Debugging Considerations

• Limitations of Form Personalization

• Interfering with Normal Operations

• Debugging: Why Isn’t It Running?

• Debugging: Is It Really Running?

• Debugging: Why Isn’t It Sticking?

• Debugging: How Do I Stop It From Running?

• Relationship to CUSTOM Library


Limitations of Form Personalization

You can only change what Forms allows at runtime:

• Cannot create new items

• Cannot move items between canvases

• Cannot display an item which is not on a canvas

• Cannot set certain properties

• Cannot change frames, graphics, boilerplate

You can only respond to certain Trigger Events:

• WHEN-NEW-FORM-INSTANCE, WHEN-NEW-BLOCK-INSTANCE, WHEN-NEW-RECORD-INSTANCE, WHEN-NEW-ITEM-INSTANCE

• WHEN-VALIDATE-RECORD (not in all forms)

• Product-specific events


Additional Limitations

Certain personalizations must be performed at specific events:

• To specify an initial value for an item, you must perform the action in the WHEN-NEW-RECORD-INSTANCE event of the block that contains the item.

• Special menu entries can only be created at form startup (WHEN-NEW-FORM-INSTANCE).

Certain objects may not be available to you to change, or can not be validated.

Most importantly, any change you make might interfere with the normal operation of the form.


Interfering with Normal Operations

• You may make a personalization, but it doesn’t take effect because there is code in the form that overrides it. You may be able to perform the personalization by moving the trigger event to a lower level, such as block- or item-level.

• Your personalization may simply produce the wrong result due to interactions with the base code in unexpected or untested ways. At best, this produces an error. At worst, it could affect some later processing.

• In extreme cases, it may prevent your form from running at all. Making it difficult to remove the offending personalization.


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 Built-in '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.


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.


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


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


Relationship to CUSTOM Library

• CUSTOM is a stub library Oracle ships that receives Trigger Events. Customers are free to add any code they like to it.

• CUSTOM and Form Personalizations drive off the same Trigger Events– Form Personalizations are processed first, then

the event is sent to CUSTOM• CUSTOM can do more because it has complete

access to all PL/SQL and SQL• But for most changes, Form Personalizations is

adequate and is significantly simpler.


Advanced Concepts

• Global variables

• Query-by-Example (QBE) mode

• Special menu entries

• “Zooming”


Global Variables Overview

• GLOBAL variables are dynamically created at runtime

• They can hold up to 255 bytes• They are visible across all forms that are

currently running• They are very useful for Form Personalizations!

– Allow you to establish a value once then re-use it

– Allow you to pass information between forms


Global Variable Properties

Two (2) Properties affect them:• VALUE:

– Creates it if it does not exist.– Always sets the value.

• INITIAL VALUE: – Creates it if it does not exist, setting it to null.– Only sets the value if it is currently null.


Global Variables

• Name any you create starting with ‘XX’.– Prevent collisions with global variables that base

product code creates.• In Conditions and evaluated strings, refer to

them with :global.<name>– Example: ='Your password must have at least

'||:global.xx_password_length||' characters.' – References will produce an error if the variable

does not exist yet.Make sure they exist by first setting the INITIAL VALUE property in a prior action or rule.

• Remember, they are shared across all forms.


More Global Variables

• Creates the global variable :global.xx_password_failures if it did not already exist

• Sets its value to :global.xx_password_failures• Because the example is self_referencing, a prior

Action needs to have created it!


Query-by-Example (QBE) Mode

QBE is a power-user mechanism to locate records, instead of Find WindowsNormally invoked by selecting View > Query By Example > Enter from the pulldown menuThe built-in DO_KEY with argument ENTER_QUERY will invoke this mode, for the current blockIt is a ‘mode’• Things operate differently, or are suspended,

until you exit this mode by Running a query or selecting Cancel

• Specifically, any actions after invoking the mode will not be executed until the mode is exited


More QBE Mode

Trigger Events can fire in QBE mode, or not• Set ‘Fire in Enter-Query Mode’ as desired• This will cause the Rule to execute in both QBE

and ‘normal’ mode• It is very, very, very rare that you would want

your rules to fire in this mode!• Later we’ll discuss one example where this could

be used.


Special Menu Entries

Embedded in every menu are 45 entries you can activate

Each has the name SPECIAL#• SPECIAL1 though 15: under ‘Tools’• SPECIAL16 though 30: under ‘Reports’• SPECIAL31 though 45: under ‘Actions’

Must be activated in a Rule based on the WHEN-NEW-FORM-INSTANCE event


More Special Menu Entries

• Menu Entry: which entry you want to activate• Menu Label: the text for the menu entry• Render Line before menu: will draw a separator line above

the menu entry• Enabled In Block(s): the blocks for which the menu entry

should be enabled. – Leave blank to enable for all blocks.

• Icon Name: the name of an optional .ico file, which will render in the toolbar


Special Menu Entry Considerations

But ‘Special’ simply activates the menu entry• At runtime, if the user selects it, it emits an event

name that matches the menu entry name– For example, if you activate SPECIAL1, when

the user selects it the event ‘SPECIAL1’ will be sent

• You create a second rule that triggers off that event and does what you want

WARNING• Base product code uses these menu entries too.

Select an entry they do not use– The Menu Entry list shows the current label if

there is one; no label is an indication it is currently unused


Zooming

One of the most commonly requested enhancements:• The ability to open a function, passing context

from the current function– For example, from the Purchase Orders form,

open the Vendors form, and pass the vendor on the current PO to query its details

Special+Globals+QBE lets you define these yourself!


Administration Concepts

• Securing

• Performance

• Loading Personalizations

• Support Issues


Securing Access to Form Personalization

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!


How Form Personalizations Perform

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


Debugging Personalization 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 built-in can contain arbitrary

PL/SQL blocks• You will see all of these in Trace files


Loading PersonalizationsDownload (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


Support Issues

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


Summary

In this lesson, you should have learned how to:

• Understand the basic concepts of Form Personalization.

• Implement a variety of common Form Personalizations.

• Understand the intermediate concepts of Form Personalization.

• Understand the advanced concepts of Form Personalization.

• Understand Form Personalization administration.

Form-Personalization Oracle Edu

Documents

Transcript of Form-Personalization Oracle Edu