Intermediate Level Form Personalization

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

1-7

WHEN-VALIDATE-RECORD: each time the current record has any change that needed to be validated. Trigger Object must contain the blockname of interest. 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 – – –

1-8

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

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 –

1-10

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

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

1-12

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

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 –

1-15

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

Copyright © 2004, Oracle. All rights reserved.

Working with Strings, continued String Typed In

Result at Runtime

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

Your password will expire on 31DEC-2004 {if sysdate is currently 24-DEC-2004} Your password must have at least 8 characters. {if passwd_length has a value of 8} User: SYSADMIN {if :user.user_name is ‘SYSADMIN’}

='Your password must have at least '||:context.passwd_length||' characters.' =‘User: ‘||NVL(:user.user_name, ‘New’)

=The field value is: :items.part_number

User: New {if :user.user_name is null} {an ORACLE error because the 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: – –

1-18

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.

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): – – – – – – – – – – – 1-20

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

1-21

TITLE: the title of the window X and Y_POS: the location within the MDI window, in inches

Copyright © 2004, Oracle. All rights reserved.

Common Actions of type Property (3)  For Blocks: – – – – –

1-22

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

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

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