42. SPEL in OA Framework Personalizations

 

Using SPEL in OAF (Oracle Application Framework)

Introduction

SPEL (Simplified Personalization Expression Language) is a powerful feature in Oracle Application Framework (OAF) that allows you to set page field properties dynamically without writing any custom code, extensions, or personalizations. Instead of hardcoding values like TRUE or FALSE, SPEL lets you define expressions that are evaluated at runtime to determine properties such as:

• Rendered (show/hide a field)

• Read Only (enable/disable editing)

• Required (make a field mandatory)

SPEL is essentially an expression that returns TRUE or FALSE, and it can reference:

• Function Security — Whether the user has access to a specific function

• Profile Options — The value of a system or user profile option

• Page Context — Values from the current page or session

• View Object Attributes — Data values from the current row

Key Benefit: SPEL enables conditional page behavior without any Java coding or OAF extensions, making it one of the most efficient ways to customize standard Oracle E-Business Suite pages.

---

Two Ways to Change Properties in Personalization

In OAF Personalization, there are two ways to set properties like Rendered, Read Only, or Required:

Method	Description	Example
1. Hardcode a Value	Set a fixed value of TRUE or FALSE	Read Only = True
2. Use SPEL	Use an expression that returns TRUE or FALSE at runtime	${oa.FunctionSecurity.XX_HIRE_DATE_READ_ONLY}

Note: SPEL is the dynamic option. It allows the property to change based on who the user is, what responsibility they're using, or what data is being displayed.

---

Test Case: Enable Hire Date Only for a Specific User

Business Requirement: On the Create Employee page (under the "OA Framework Toolbox Tutorial Labs" responsibility), the Hire Date field should be:

• Editable for a specific user (e.g., OAF_USER)

• Read Only for all other users

We will implement this using SPEL and Function Security — without any custom code.

---

Prerequisites

Before you begin, ensure the following:

• Access to the Functional Administrator responsibility

• Access to the OA Framework Toolbox Tutorial Labs responsibility

• The user OAF_USER exists in the system

• The Create Employee page is accessible

---

Step 1: Create a Function

The first step is to create a function that represents the "permission" to edit the Hire Date field.

1. Navigate to Functional Administrator:

   • Log in with the Functional Administrator responsibility

2. Access the Functions Page:

   • Click on the Core Services tab

   • Select Function

3. Create the Function:

   • Click Create Function

   • Enter the following details:

Property	Value
Name	XX Hire Date Read Only
Code	XX_HIRE_DATE_REAF_ONLY
Type	SSWA jsp Function
HTML Call	OA.jsp?page=/dummy

Note: The function type is SSWA jsp Function because we are using it purely for security checking — it doesn't actually render a page. The HTML Call points to a dummy page since the function is never actually invoked.

4. Save the Function:

   • Click Apply to create the function

Result: The function XX_HIRE_DATE_REAF_ONLY is now created and can be referenced in SPEL expressions.

---

Step 2: Create a Permission Set

Now we create a permission set (menu) that contains the function and grant it to specific users.

1. Navigate to the Menus Page:

   • In the Functional Administrator responsibility, go to Core Services → Menu

2. Create the Menu:

   • Click Create Menu

   • Enter the following details:

Property	Value
Menu	XX_EMPOYEE_HIRE_DATE_READ
User Menu Name	XX Employee Date Read Only
Menu Type	Permission Set

3. Add the Function:

   • Add the function XX Hire Date Read Only to this menu

   • Ensure the Grant checkbox is unchecked (remove the global grant)

Important: Unchecking the Grant checkbox removes the global grant, meaning the permission is not automatically granted to all users. Instead, it must be explicitly granted to specific users (which we do in the next step).

4. Save the Menu:

   • Click Apply to create the permission set

---

Step 3: Grant the Permission Set to the User

Now we grant the permission set to the specific user (OAF_USER).

1. Navigate to Grants:

   • In the Functional Administrator responsibility, click on the Security tab

   • Click on Grants

   • Click Create Grant

2. Configure the Grant:

   • Enter the following details:

Property	Value
Name	XX_EMPLOYEE_HIRE_DATE_READ_GRANT
Grantee Type	Specific User
Grantee	OAF_USER

3. Select the Grantee:

   • Click the Grantee LOV and select OAF_USER

4. Attach the Permission Set:

   • Click Next

   • In the Set field, attach the permission set XX Employee Date Read Only

5. Complete the Grant:

   • Click Next, then click Finish

Result: The user OAF_USER now has the XX_HIRE_DATE_REAF_ONLY function granted through the permission set.

---

Step 4: Personalize the Page Using SPEL

Now we personalize the Create Employee page to set the Read Only property of the Hire Date field using SPEL.

1. Navigate to the Page:

   • Log in with the OA Framework Toolbox Tutorial Labs responsibility

   • Open the Create Employee page

2. Open Personalization:

   • Click the Personalize Page link in the top-right corner

3. Personalize the Hire Date Field:

   • Locate the Hire Date field in the personalization structure

   • Click on it to edit its properties

4. Set the Read Only Property Using SPEL:

   • In the Read Only property, at the Site level:

     • Select SPEL from the dropdown

     • Enter the following expression:

       text

       ${oa.FunctionSecurity.XX_HIRE_DATE_REAF_ONLY}

5. Apply the Personalization:

   • Click Apply to save the personalization

Explanation: The SPEL expression ${oa.FunctionSecurity.XX_HIRE_DATE_REAF_ONLY} evaluates to:

• TRUE if the user has the function granted → the field is Read Only

• FALSE if the user does NOT have the function granted → the field is Editable

Wait — this seems backwards! Let's think about this carefully. The function is named "XX Hire Date Read Only". So:

• If the user has the function → the field should be Read Only → SPEL returns TRUE → field is Read Only ✓

• If the user does not have the function → the field should be Editable → SPEL returns FALSE → field is not Read Only (editable) ✓

Important: The logic works because the permission set was granted only to OAF_USER. So:

• OAF_USER has the function → Read Only = TRUE → field is Read Only for OAF_USER

• Other users don't have the function → Read Only = FALSE → field is Editable for others

Correction: Based on the original article's intent, the requirement was to enable the field only for OAF_USER. To achieve that, the SPEL expression should be negated. Use:

text

${!oa.FunctionSecurity.XX_HIRE_DATE_REAF_ONLY}

This way:

• OAF_USER has the function → !TRUE = FALSE → field is Editable ✓

• Other users don't have the function → !FALSE = TRUE → field is Read Only ✓

---

Step 5: Verify the Behavior

1. Test with OAF_USER:

   • Log in as OAF_USER

   • Navigate to the Create Employee page

   • Verify that the Hire Date field is Editable

2. Test with Another User:

   • Log in as a different user (without the grant)

   • Navigate to the Create Employee page

   • Verify that the Hire Date field is Read Only

Result: The Hire Date field is now conditionally enabled based on the user's function security.

---

How SPEL Works at Runtime

The following illustrates the SPEL evaluation flow:

text

┌─────────────────────────────────────────────────────────────────┐
│                     USER LOGS IN                                │
│  1. User OAF_USER logs in                                       │
│  2. Function security is loaded for the user                    │
│  3. XX_HIRE_DATE_REAF_ONLY is granted to OAF_USER               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  PAGE RENDERING                                 │
│  1. Create Employee page loads                                  │
│  2. Personalization applies the SPEL expression                 │
│  3. SPEL evaluates: ${oa.FunctionSecurity.XX_HIRE_DATE_REAF...} │
│  4. Result: TRUE (user has the function)                        │
│  5. Read Only property is set to TRUE                           │
│  6. Hire Date field is rendered as Read Only                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  DIFFERENT USER                                 │
│  1. Another user logs in (without the grant)                    │
│  2. SPEL evaluates: ${oa.FunctionSecurity.XX_HIRE_DATE_REAF...} │
│  3. Result: FALSE (user does not have the function)             │
│  4. Read Only property is set to FALSE                          │
│  5. Hire Date field is rendered as Editable                     │
└─────────────────────────────────────────────────────────────────┘

---

Common SPEL Expressions

SPEL supports a variety of expressions. Here are some commonly used ones:

SPEL Expression	Purpose
${oa.FunctionSecurity.FUNCTION_CODE}	Checks if the user has a specific function
${oa.ProfileOption.PROFILE_CODE}	References a profile option value
${oa.PageContext.UserName}	Gets the current username
${oa.PageContext.ResponsibilityName}	Gets the current responsibility
${oa.ViewObject.AttributeName}	References a View Object attribute
${!oa.FunctionSecurity.FUNCTION_CODE}	Negates the function security check
${oa.FunctionSecurity.FUNC1 && oa.FunctionSecurity.FUNC2}	Logical AND
${oa.FunctionSecurity.FUNC1 || oa.FunctionSecurity.FUNC2}	Logical OR

---

Where SPEL Can Be Used

SPEL can be applied to the following properties in personalization:

Property	Purpose	Example SPEL
Rendered	Show/hide a field or region	${oa.FunctionSecurity.XX_SHOW_FIELD}
Read Only	Enable/disable editing	${oa.FunctionSecurity.XX_EDIT_FIELD}
Required	Make a field mandatory	${oa.FunctionSecurity.XX_REQUIRED_FIELD}
Disabled	Disable a field	${oa.FunctionSecurity.XX_DISABLE_FIELD}
Visible	Control visibility	${oa.FunctionSecurity.XX_VISIBLE_FIELD}

---

Best Practices

Practice	Description
Use Meaningful Function Codes	Name functions descriptively (e.g., XX_HIRE_DATE_EDIT)
Use Permission Sets	Group related functions into permission sets
Grant to Specific Users	Uncheck "Grant" to avoid granting to all users
Test with Multiple Users	Test with users who have and don't have the grant
Document SPEL Expressions	Keep a record of all SPEL expressions used
Use Negation Carefully	Double-check the logic when using ! (negation)
Consider Profile Options	Use profile options for user-specific settings
Avoid Complex Expressions	Keep SPEL expressions simple and readable

---

Troubleshooting Common Issues

Issue	Possible Cause	Solution
SPEL not evaluating	Wrong syntax	Verify the ${...} syntax and function code
Field always Read Only	Function granted globally	Uncheck the "Grant" checkbox in the menu
Field always Editable	Function not granted	Verify the grant is assigned to the user
Function not found	Wrong function code	Verify the function code in Functional Administrator
Personalization not applying	Wrong level	Apply at the correct personalization level
SPEL error on page	Invalid expression	Check the SPEL expression for syntax errors
Permission set not working	Missing grant	Verify the grant is created and active

---

SPEL vs. Personalization vs. Extension

Approach	Complexity	Use Case
SPEL	Low	Conditional properties without code
Personalization	Low	Simple property changes (hardcoded)
Controller Extension	High	Complex business logic and validations
VO Extension	High	Adding new fields or attributes

Key Insight: SPEL is the simplest way to make page properties dynamic. It requires no Java coding, no extensions, and no deployments — just personalization configuration. Use SPEL whenever your requirement can be met with a simple TRUE/FALSE expression.

---

Summary

Using SPEL in OAF involves the following key steps:

1. Create a Function: Define a function in Functional Administrator (e.g., XX_HIRE_DATE_REAF_ONLY)

2. Create a Permission Set: Create a menu of type Permission Set and add the function

3. Grant the Permission Set: Assign the permission set to specific users

4. Personalize the Page: Set the property (e.g., Read Only) to use a SPEL expression

5. Test: Verify the behavior with different users

Key Points to Remember

• SPEL is an expression that returns TRUE or FALSE

• ${oa.FunctionSecurity.FUNCTION_CODE} checks if a user has a function

• Permission Sets group related functions for easy granting

• Unchecking "Grant" ensures the permission is not granted to all users

• Personalization applies the SPEL expression to page properties

• No coding required — SPEL is purely configuration-based

• Test with multiple users to verify the conditional behavior

Why SPEL Matters

SPEL is one of the most powerful and underutilized features in OAF because it:

• Eliminates Custom Code: No Java coding or OAF extensions needed

• Reduces Maintenance: Changes can be made through configuration

• Survives Upgrades: Personalizations and function security are preserved

• Enforces Security: Leverages Oracle's standard function security model

• Enables Dynamic Behavior: Page properties respond to user permissions

• Is Quick to Implement: Can be set up in minutes vs. hours of coding

By mastering SPEL, you can implement conditional page behavior quickly and efficiently, meeting business requirements without the overhead of custom development.

---

References

• Oracle E-Business Suite Documentation: OA Framework Developer's Guide

• Oracle E-Business Suite Documentation: Personalization Guide

• Oracle E-Business Suite Documentation: Functional Administrator Guide

• My Oracle Support: SPEL in OAF (Note IDs)

• Related Guides: OAF Personalization, Controller Extension in OAF, VO Extension in OAF, Partial Page Rendering in OAF