Forms Personalization

Overview of Form Personalization

  • Form Personalization Overview

  • Using the Personalization form

  • Limitations

  • Examples and Tips

  • Administration Window

  • Moving Personalizations between instances

  • Relationship to CUSTOM library

  • Relationship to Folder

  • Introduction

    This describes the use of the Orcale Form Personalization feature, which allows you to declaratively alter the behavior of Forms-based screens, including changing properties, executing builtins, displaying messages, and adding menu entries.

    The following topics are covered:

    • Form Personalization Overview
    • Using the Personalization form
    • Limitations
    • Examples and Tips
    • Administration Window
    • Moving Personalizations between instances
    • Relationship to CUSTOM library
    • Relationship to Folder


    Form Personalization Overview

    The Form Personalization feature allows you to declaratively alter the behavior of Forms-based screens, For each function you can specify one or more Rules. Each Rule consists of an Event, an optional Condition, the Scope for which it applies, and one or more Actions to perform.

    An Event is a trigger point within a form, such as startup (WHEN-NEW-FORM-INSTANCE), or when focus moves to a new record (WHEN-NEW-RECORD-INSTANCE). There are standard events that almost every form sends, and certain forms send additional product-specific events.

    The Scope is evaluated based on the current runtime context to determine if a Rule should be processed or not. The Scope can be at the Site, Responsibility or User level. Each Rule can have one or more Scopes associated with it.

    The Condition is an optional SQL code fragment that is evaluated when the Event occurs; if it evaluates to TRUE then the Actions are processed.

    Each Action consists of one of the following:

    • Setting a Property, such as making a field Required or Changing prompt value
    • Executing a Builtin, such as GO_BLOCK, DO_KEY or FND_FUNCTION.EXECUTE
    • Displaying a Message, such as show message or error message
    • Enabling a Special menu entry

    Once Rules are defined, when the target function is run then the Rules are automatically applied as events occur within that form.

    Using the Personalization form

    To create personalizations for a particular function, first invoke that function from the Navigation menu. While in the form, choose Help->Diagnostics->Custom Code-> Personalize from the pulldown menu. This menu entry is secured by the FND_HIDE_DIAGNOSTICS (Hide Diagnostics menu entry) and DIAGNOSTICS (Utilities:Diagnostics) profiles, as are most other entries on the Diagnostics menu.

    The Personalization form will open and automatically query existing Rules for that function. After making changes, Save them then close and re-run the function to have them take effect. You can also Validate or Apply certain changes immediately to test them without having to re-run the target form by pressing the 'Validate' or 'Apply Now' buttons.

    The Personalization screen, when opened from the Create Service request form (Function Name CSXSRISR).Each Rule consists of the following fields:

    • Seq: This is a value between 1 and 100. The sequence of rules does not have to be unique.
    • Description: This field is used for document the personalization which you are making.

    Enabled: Uncheck this checkbox to temporarily disable processing of a Rule.

    The following fields appear on the Condition tab:

    Trigger Event: Select the event at which you want the Rule to be processed. You can pick from the list of standard events, or type in a specific event unique to the form. Rules are processed first by matching the Event, then by their Sequence number.

    Trigger Object: Depending on the Trigger Event, this field may be Disabled, or Enabled and Required. For example, if Trigger Event WHEN-NEW-ITEM-INSTANCE is selected, then you must enter a specific block.field for that trigger to be processed.

    Condition: This is an optional SQL code fragment that is evaluated when the Event occurs. if it evaluates to TRUE then the Actions are processed. The condition can contain any of the following:

    • SQL functions and operators
    • References to bind variables (:block.field), including :system, :global and :parameter values.

    Each Rule consists of one or more Scope rows, and Actions. If a Rule has no Action rows, it is not processed. Note that upon saving a Rule, if no Scope rows have been entered the form will automatically create a row at the Site level.

    The following Scope fields appear in the Context region of the Condition tab: Level: Select the level at which you want the rule to be applied, either Site, Responsibility, User, or Industry. Value: Based on the Level, either Disabled, or Enabled and Required in which case it will validate against a List of Values.

    All Action fields appear on the Actions tab: Seq: The sequence in which actions will be processed within that Rule. This is a value between 1 and 100, with 1 being processed first. The sequence does not have to be unique. All of the actions associated with a particular rule are processed as a group.

    Type: the type of action to take:

    • Property: Allows you to select a specific object, a property of that object, and specify a new value for that property
    • Builtin: Allows execution of a standard Forms Builtin, such as GO_BLOCK
    • Message: Displays a message
    • Special: Enables a special menu entry, defining its label, icon name and which blocks it applies to.

    Description: Use this field to document the personalization action you are making.

    Language: Specify 'All' to have the action processed for any language, or select a specific language. Typically text-related personalizations would be applied for a specific language.

    Enabled: Uncheck this checkbox to temporarily disable processing of the action. Apply Now: For several Types, this button will be enabled. It allows you to apply the change immediately to the target form to test its effect.

    The following buttons are enabled conditionally based on the Type field:

    Add Parameter…: List of Values that displays currently used parameters. Applies to the builtin FND_FUNCTION.EXECUTE only. Add Block…: List of Values that displays block names. Add Item…: List of Values that displays item names.

    Validate: Used to test if the syntax of your string is valid. If the evaluation fails, the processing engine will return an ORA error as if the string had been part of a SQL expression. Otherwise, it will display the text exactly as it would appear at runtime in the current context.

    The following fields appear conditionally based on the Type field:

    For a Type of 'Property':

    The fields associated with an action of 'Property'

    Select By Text: This button allows you to select an object based on text appearing on the screen at the point in time that you invoke the Personalization form, including any changes that current rules might have performed. For example, if you want to change a field with the current prompt of 'Item Number', you should see 'Item Number' in this list, and selecting it will automatically fill in the Object Type and Target Object fields.

    Object Type: the type of object, including Item, Window, Block, Tab, Canvas, Radio button, View, GLOBAL, or PARAMETER.

    Target Object: based on the Object Type, the internal name of the object. For Object Types of GLOBAL and PARAMETER, the Target Object name must not include those keywords. For example, to refer to GLOBAL.XX_MY_VARIABLE, only enter XX_MY_VARIABLE.

    Property Name: based on the Object Type, the properties that can be personalized. The Object Type of Item supports a vast array of properties including:

    • Item-level properties, which set the property for all instances of that object.
    • Item-instance properties, which set the property for the current record of that block using set_item_instance_property()
    • Applications cover properties, which are a hybrid of multiple item and item-instance level properties. These are fully documented in the Oracle Applications Development Guide.

    Value: the new value. The appearance and validation of this field changes based on whether the property accepts Boolean values (True/False), numbers, a restricted set of values, or a string (See Evaluation of Strings below)

    Get Value: This button gets the current property value of the object.

    Limitations

    This feature has several significant limitations due to the architecture of Oracle Forms and/or the e-Business Suite.

    You can only change what Oracle Forms allows at runtime. For example, the following cannot be changed:

    • You cannot create new items
    • You cannot move items between canvases
    • You cannot display an item which is not on a canvas (thus, individual flexfield segments cannot be displayed)
    • You cannot set certain properties such as the Datatype of an Item.
    • You cannot change frames, graphics, or boilerplate
    • You cannot hide the item that currently has focus

    Form Personalization can only respond to events that are centrally processed and dispatched by APPCORE. These are limited to:

    • WHEN-NEW-FORM-INSTANCE, WHEN-NEW-BLOCK-INSTANCE, WHEN-NEW-RECORD-INSTANCE, WHEN-NEW-ITEM-INSTANCE. These events occur as the user moves focus within the form.
    • WHEN-VALIDATE-RECORD (in many but not all forms). This event occurs whenever changes have been made to the current record in the current block.
    • SPECIAL1 through SPECIAL45. These occur when the user selects entries from the Tools, Reports and Actions pulldown menus.

    Certain objects may not be available to you to change, or cannot be validated:

    • If a Tab within a form has no items directly rendered on it, that Tab will not appear in the list of objects that you can modify. In some cases, making that Tab the active tab before invoking the Personalization feature may cause it to be detected.
    • The object types GLOBAL and PARAMETER cannot be detected, thus these fields have no LOVs to restrict their input. Use the 'Validate' or 'Apply Now' buttons to determine if the values you have entered actually exist. Note that GLOBAL variables are dynamically created, so whether they exist or not can be a matter of timing.

    Most significantly, any change you make might interfere with the normal operation of the form. This can manifest itself in several ways, such as:

    • You may make a personalization but it doesn't take effect, because there is code in the form that overrides it. In some cases you may be able to perform your personalization by moving the Trigger Event to a 'lower' level, such as block- or item-level.


    Examples and Tips

    Changing the prompt of an item This is a step-by-step example of changing a prompt. In this case, we will modify the 'Create Service Request' form, and change the prompt Item to Product: 1.Open the Create Service request form

    2.Select Help->Diagnostics->Custom Code-> Personalize from the pulldown menu.

    3.Create a rule with the following values:

    • Seq: 1
    • Description: Change prompt of Item

    Accept the defaults for all other values of the Rule and Context

    4.Select the Actions Tab and enter the following values:

    • Seq: 1
    • Press the 'Select By Text' button and choose the 'Item' row from the LOV
    • Property Name: PROMPT_TEXT
    • Value: Product

    Accept the defaults for all other values of the Actions.

    5.Save

    6.Activate the Create Service Request form, then close it.

    7.Re-open the Create Service Request form. You should see that the prompt is now 'Product'.

    8.To disable this Rule, set Enabled to unchecked (at either the Rule or Action level), or just delete the Rule, then Save.


    Administration Window

    The 'Find Personalizations' administration window can be invoked only from the Personalization Form. In the Tools pulldown menu, select 'Administration'. This will allow you to get a list of all functions that currently have Personalizations (Rules) defined.

    Form: The filename of a form.

    If you press the Find button while both Form Name and Function Name are empty, all forms that have any personalizations (enabled or not) will be queried. This is particularly useful after applying a patch; knowing which forms the patch affects, you can quickly detemine if any personalizations need to be re-validated.

    User Function Name: A description of the form function. You see this name when assigning functions to menus. Enabled Rules: The number of active rules that a function has defined.

    Moving Personalizations between instances

    Once you create and test personalizations in your test instance, you can move them to production instances. Personalizations are extracted by the loader on a per-function basis (that is, each loader file will contain all of the personalizations for a single function). Note that upon uploading, all prior personalizations for that function are first deleted, and then the contents of the loader file are inserted.

    The loader syntax is as follows:

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

    Upload: FNDLOAD <userid>/<password> 0 Y UPLOAD $FND_TOP/patch/115/import/affrmcus.lct <filename.ldt>

    Relationship to CUSTOM library

    Form Personalization allows personalizations that could be made in the CUSTOM library, but it does not require that you use the Oracle Forms Builder to edit and compile the CUSTOM file. Depending on the complexity of your personalizations, it may still require a degree of coding skill comparable to that needed to use the CUSTOM library. And the CUSTOM library is able to support more complex personalizations because it gives you access to all of the capabilities of the PL/SQL programming language, including calling client-side program units, all Oracle Forms builtins, and issuing any SQL.

    Both Form Personalization and the CUSTOM library drive off the exact same events. The Form Personalization feature receives and processes them first, then passes them to the CUSTOM library, thus you can use both mechanisms simultaneously. (Note: SPECIALXX and MENUXX events are not passed to the CUSTOM library).

    Both features also respond identically to the Custom Code events of 'Normal', 'Off' and 'Core Code Only'.

    In general, Oracle recommends that you use the Form Personalization feature whenever possible, and only use the CUSTOM library when significantly more complex processing is required.

    Relationship to Folder

    Folders allow an end-user to 'customize' a screen by changing the fields and records displayed. For the most part, folder blocks are identifiable by an enabled 'Folder' menu entry, and an 'Open Folder' icon above the block. In a few cases, folder technology may be used by base code to dynamically alter a block, but no folder functionality is exposed to the end user.

    Folder blocks are constructed differently than 'regular' Forms blocks - they include an extra block that renders the prompts for the fields, and 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:

    The following properties of a folder block 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

    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.