Administrator Level Form Personalization

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

1-5

Like Form Personalizations, these features can be used to change or view any data! 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 ;  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  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 – – –

1-11

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

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

1-13

Setting the WIDTH property: 2.5 Creating a Condition based on the value of a numeric field: :block.field >= 2.5 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-NEWBLOCK-INSTANCE or WHEN-NEW-RECORD-INSTANCE Properties that affect a specific item in a block: set at WHEN-NEWITEM-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 – – –

1-17

‘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 iteminstance level

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



What can you do? 1. 2. 3. 4. 5.

1-19

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 Identify all forms affected by a patch Run the personalization screen from any form and select Tools > Administration Identify all forms that have Personalizations and have just been patched Run each function, possibly setting Custom Code to ‘Off’ if it fails to open Run the Personalization screen and select Tools > Validate All 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 FND_FORM_CUSTOM_RULES 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 – 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 –

1-22

Only use the CUSTOM library when significantly more complex processing is required. Copyright © 2004, Oracle. All rights reserved.

Interactions with Folders  

1-23

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.

Copyright © 2004, Oracle. All rights reserved.

Interactions with Folders, continued 

1-24

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

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 

1-26

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.

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.