Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Developer's Guide
11g Release 8 (11.1.8)
E15524-16
June 2014
Documentation for external Oracle Fusion Applications
developers that describes Oracle Fusion Middleware
components, installing JDeveloper, deploying applications
on WebLogic Server (WLS), using Applications Core
Technology (ApplCore), customization, security, Flexfields,
developing web applications with the UI Shell page template
and patterns, Enterprise Crawl and Search (ECSF), database
schema deployment, seed data, and use cases.
Contents
Preface ................................................................................................................................................................. lv
Audience....................................................................................................................................................... lv
Documentation Accessibility ..................................................................................................................... lv
Related Documents ..................................................................................................................................... lv
Conventions ............................................................................................................................................... lvii
Part I
iii
2.2.3
How to Start Integrated WebLogic Server ............................................................... 2-36
2.2.3.1
Managing Integrated WebLogic Server ............................................................. 2-38
2.3
Improving Shared and Personal Environments Performance ........................................ 2-38
2.3.1
How to Create the OWSM_MDS Schema ................................................................ 2-38
2.3.1.1
Creating the OWSM_MDS Schema ................................................................... 2-39
2.3.2
How to Use Alternate Database Schemas ................................................................ 2-46
2.3.3
How to Set Up the Personal Environment for Standalone WebLogic Server ........... 2-47
2.3.3.1
Creating a Domain for Standalone WebLogic Server ........................................ 2-48
2.3.3.1.1
How to Create a Special SOAINFRA Schema ............................................. 2-49
2.3.3.1.2
How to Set Up the Environment for Standalone WebLogic Server ............ 2-49
2.3.3.1.3
How to Fix Domain Creation Errors ........................................................... 2-53
2.3.3.1.4
How to Test the Server ............................................................................... 2-54
2.3.3.1.5
How to Manage the Standalone WebLogic Server Lifecycle ....................... 2-54
2.4
Configuring Oracle SOA Suite and Oracle Enterprise Manager Fusion Middleware Control
....................................................................................................................................... 2-55
2.4.1
How to Use the Application Logging Service .......................................................... 2-55
2.5
Using Deployment Profiles Settings ............................................................................... 2-56
2.5.1
How to Use Service Deployments ........................................................................... 2-57
2.5.2
How to Update the Standard ................................................................................... 2-57
2.6
Configuring the Oracle Enterprise Scheduler (ESS) ....................................................... 2-58
2.6.1
How to Provision the Runtime Environment .......................................................... 2-58
2.6.2
How to Create Supporting Database Schema .......................................................... 2-59
2.6.3
Post-Installation Checks ........................................................................................... 2-60
2.6.3.1
Verifying the Temp Directory Location and Write Permissions ........................ 2-60
2.6.3.2
Verifying ESS Artifacts Deployment Targets .................................................... 2-60
2.6.3.3
Checking ESS Health ......................................................................................... 2-60
2.7
Testing Your Installation ................................................................................................ 2-60
2.8
Using Best Practices for Setting Up the Development Environment .............................. 2-69
2.8.1
How to Implement Best Practices for JDeveloper .................................................... 2-69
2.8.2
How to Refresh the Oracle ADF Library Dependencies Library ............................. 2-70
2.8.3
How to Manage OutOfMemory Exceptions (PermGen) .......................................... 2-71
2.8.4
How to Work with Oracle ADF Libraries at Design Time ....................................... 2-72
2.9
Configuring Hierarchy Providers for Approval Management (AMX) ........................... 2-72
3.7.2
What Happens When You Add the Search Navigation Tab to the Overview Editor . 3-9
3.8
Overriding the Default Resource Bundle ......................................................................... 3-9
3.9
Deploying Oracle SOA Suite ............................................................................................ 3-9
3.10
Implementing Oracle Enterprise Scheduler Service Workspace and Deployment ......... 3-10
3.10.1
How to Create the SuperEss Project ......................................................................... 3-11
3.10.2
How to Build the EAR/MAR Profiles ...................................................................... 3-11
3.10.2.1
Deploying a Project-level Metadata Archive (MAR) ......................................... 3-11
3.10.2.1.1
How to Enable Your Application Workspace for Project-level MAR
Deployment ................................................................................................ 3-12
3.10.2.2
Building the EAR Profile ................................................................................... 3-13
3.10.2.3
Deploying an Oracle Enterprise Scheduler Service Hosting Application .......... 3-14
3.11
Implementing Oracle Application Development Framework UI Workspace and Projects
........................................................................................................................................ 3-14
3.11.1
How to Set Up Your Web Project ............................................................................. 3-15
3.11.1.1
Configuring Your User Interface Project ........................................................... 3-15
3.11.2
How to Create the SuperEss Project in the ADF UI Workspace ............................... 3-22
3.11.3
How to Deploy Your Web Project ............................................................................ 3-22
5 Developing Services
5.1
Introduction to Services .................................................................................................... 5-1
5.2
Designing the Service Interface ........................................................................................ 5-2
5.2.1
Identifying Business Objects ...................................................................................... 5-2
5.2.1.1
Business Object Attributes ................................................................................... 5-2
5.2.2
Identifying Service Operations on the Business Objects ............................................ 5-3
5.2.2.1
Types of Operations ............................................................................................ 5-3
5.2.2.2
Identifying Operations ........................................................................................ 5-4
5.2.2.3
Defining Service Operations - General Guidelines .............................................. 5-5
5.2.3
How to Identify Services ............................................................................................ 5-7
5.2.4
How to Define Service Exceptions and Information .................................................. 5-7
5.2.4.1
Defining Service Exceptions ................................................................................ 5-7
5.2.4.2
Defining Partial Failure and Bulk Processing ...................................................... 5-8
5.2.4.3
Defining Informational Messages ....................................................................... 5-8
5.3
Developing Services ......................................................................................................... 5-8
5.3.1
How to Create Service Data Objects .......................................................................... 5-9
5.3.1.1
SDO Attributes .................................................................................................... 5-9
5.3.1.2
Parent-Child Relationships ............................................................................... 5-12
5.3.1.3
Enabling Partial Failure ..................................................................................... 5-12
5.3.1.4
Enabling Support Warnings .............................................................................. 5-12
5.3.1.5
Defining a List of Values (LOV) to Resolve Foreign Key ID .............................. 5-13
5.3.2
How to Create Services ............................................................................................ 5-15
5.3.2.1
What You May Need to Know About Design Time .......................................... 5-15
5.3.3
How to Generate Synchronous and Asynchronous Service Methods ..................... 5-16
5.3.4
How to Expose Flexfields ........................................................................................ 5-17
5.3.5
How to Enable Security ........................................................................................... 5-17
5.3.5.1
Authentication ................................................................................................... 5-17
5.3.5.2
Authorization .................................................................................................... 5-17
5.3.6
Using the Java Transaction API ............................................................................... 5-20
5.3.6.1
Data Source ....................................................................................................... 5-20
5.3.6.2
Transaction Attributes ....................................................................................... 5-22
5.3.7
Deploying Services .................................................................................................. 5-22
5.3.7.1
Service Context Root ......................................................................................... 5-22
5.3.8
Testing Services ....................................................................................................... 5-23
5.3.8.1
What to Test ...................................................................................................... 5-23
5.3.8.2
How to Test ....................................................................................................... 5-24
5.4
Invoking Services ........................................................................................................... 5-24
5.4.1
How to Invoke a Synchronous Service .................................................................... 5-25
5.4.1.1
Using Service Factory ........................................................................................ 5-25
5.4.1.2
Using Service-Based Entity Object and View Object ......................................... 5-35
5.4.1.3
Using the JAX-WS Client ................................................................................... 5-36
5.4.1.4
Using SOA ......................................................................................................... 5-37
5.4.2
How to Invoke an Asynchronous Service ................................................................ 5-37
vi
7.1
7.2
7.3
7.3.1
7.3.2
7.3.3
7.3.4
7.3.5
7.4
7.5
7.6
7.6.1
vii
9.1
10 Implementing Lookups
10.1
Introduction to Lookups ................................................................................................ 10-1
10.1.1
Overview of Lookups .............................................................................................. 10-2
10.1.2
Standard, Set-Enabled, and Common Lookup Views .............................................. 10-3
10.1.3
Lookup Customization Levels ................................................................................. 10-5
10.1.3.1
What Happens to Customization Levels at Runtime ........................................ 10-5
10.2
Preparing Entities and Views for Lookups ..................................................................... 10-6
10.2.1
How to Prepare Custom Lookup Views .................................................................. 10-6
10.3
Referencing Lookups ...................................................................................................... 10-8
10.3.1
How to Reference Lookups ...................................................................................... 10-8
10.4
Defining Validators for Lookups .................................................................................... 10-8
10.4.1
How to Define a List Validator ................................................................................ 10-9
10.4.2
How to Define a Key Exists Validator ................................................................... 10-10
10.5
Annotating Lookup Code Reference Attributes for Set-Enabled Lookups ................... 10-13
10.6
Integrating Lookups Task Flows into Oracle Fusion Functional Setup Manager ......... 10-14
viii
11.5
Defining a Document Sequence Audit Table .................................................................. 11-3
11.6
Enabling Document Sequences in ADF Business Components ...................................... 11-3
11.6.1
Using the Document-Sequence Extension ................................................................ 11-4
11.6.1.1
What Happens with Document Sequences at Design Time .............................. 11-6
11.6.1.2
What Happens with Document Sequences at Runtime ..................................... 11-7
11.7
Managing PL/SQL APIs ................................................................................................ 11-7
11.8
Integrating Document Sequence Task Flows into Oracle Fusion Functional Setup Manager
........................................................................................................................................ 11-9
Part III
ix
14.4
Controlling the State of Main and Regional Area Task Flows ...................................... 14-27
14.4.1
How to Control Main Area Task Flows ................................................................. 14-27
14.4.1.1
closeMainTask History .................................................................................... 14-31
14.4.2
How to Control Regional Area Task Flows ........................................................... 14-32
14.4.3
How to Control the State of the Contextual Area Splitter ...................................... 14-34
14.4.4
Sizing Regional Area Panels .................................................................................. 14-36
14.5
Working with the Global Menu Model ........................................................................ 14-37
14.5.1
How to Implement a Global Menu ........................................................................ 14-37
14.5.1.1
Menu Attributes Added by Oracle Fusion Middleware Extensions for
Applications (Applications Core) .................................................................... 14-38
14.5.1.2
Displaying the Navigator ................................................................................ 14-39
14.5.1.3
Implementing a Global Menu ......................................................................... 14-40
14.5.2
How to Set Up Global Menu Security .................................................................... 14-41
14.5.2.1
Enforcing User Privileges and Restrictions ..................................................... 14-41
14.5.3
How to Create the Navigator ................................................................................. 14-42
14.5.3.1
Rendering the Navigator as Dropdown Buttons ............................................. 14-43
14.6
Using the Settings and Actions Menu .......................................................................... 14-43
14.6.1
How to Use the Personalization Options ............................................................... 14-45
14.6.2
How to Implement End User Preferences .............................................................. 14-46
14.6.2.1
Using the Set Preferences Option .................................................................... 14-46
14.6.2.2
Using the Preferences Work Area Page ........................................................... 14-47
14.6.2.3
Deploying Preferences Pages and Designing General Preferences Content .... 14-48
14.6.2.4
Configuring and Implementing End-User Preferences ................................... 14-48
14.6.2.4.1
How to Use the Preferences Menu Model ................................................ 14-49
14.6.2.4.2
How to Configure User Session and ADF Security .................................. 14-50
14.6.2.4.3
How to Retrieve Preference Values and Check Accessibility Mode by Using an
Expression Language Expression ............................................................. 14-50
14.6.2.4.4
How to Implement the Password Management Page ............................... 14-50
14.6.2.5
Using the Most Common Preferences ............................................................. 14-51
14.6.2.5.1
How to Configure the Language Preference ............................................. 14-51
14.6.2.5.2
How to Configure the Accessibility Preference ........................................ 14-51
14.6.2.5.3
How to Configure the Regional Preferences ............................................. 14-52
14.6.3
How to Use the Administration Options ............................................................... 14-52
14.6.3.1
Securing the Administration Menu ................................................................. 14-53
14.6.4
How to Use the Troubleshooting Options ............................................................. 14-55
14.6.5
How to Set Up a Proxy User (Session Impersonation) ........................................... 14-60
15.2
Implementing Recent Items .......................................................................................... 15-12
15.2.1
How to Choose Labels for Task Flows ................................................................... 15-13
15.2.2
How to Call Sub Flows .......................................................................................... 15-13
15.2.2.1
Sub Flow Registration APIs ............................................................................. 15-13
15.2.2.2
openSubTask API Labels ................................................................................. 15-14
15.2.2.3
Starting from Recent Items .............................................................................. 15-14
15.2.3
How to Enable a Sub Flow to Be Bookmarked in Recent Items ............................. 15-15
15.2.3.1
Implementing the Sub Flow Design Pattern .................................................... 15-16
15.2.4
How to Use Additional Capabilities of the Recent Items openSubTask API ......... 15-21
15.2.5
How to Implement Data Security for Recent Items and Favorites ......................... 15-21
15.2.6
Known Issues ......................................................................................................... 15-22
15.3
Implementing the Watchlist ......................................................................................... 15-22
15.3.1
Watchlist Data Model Effects ................................................................................. 15-23
15.3.2
Watchlist Physical Data Model Entities ................................................................. 15-23
15.3.3
Supported Watchlist Items ..................................................................................... 15-27
15.3.3.1
Asynchronous Items Overview: Expense Reports Saved Search ..................... 15-27
15.3.3.2
Summary of Implementation Tasks ................................................................. 15-28
15.3.4
How to Use the Watchlist ...................................................................................... 15-30
15.3.4.1
Making the Watchlist Link in the UI Shell Global Area Work ......................... 15-30
15.3.4.2
Seed Reference Data (All items) ...................................................................... 15-30
15.3.4.3
Create a Summary View Object (SEEDED_QUERY) ....................................... 15-31
15.3.4.3.1
Summary Tables ....................................................................................... 15-31
15.3.4.4
Create Seeded Saved Searches in MDS (SEEDED_SAVED_SEARCH) ............ 15-31
15.3.4.5
Creating Application Module and View Objects (All except HUMAN_TASK)
......................................................................................................................... 15-32
15.3.4.6
Setting Up Service (All except HUMAN_TASK) ............................................. 15-32
15.3.4.7
Importing All Watchlist-Related Application Modules ................................... 15-32
15.3.4.8
Nesting Watchlist Application Modules ......................................................... 15-32
15.3.4.9
Using the refreshWatchlistCategory Method .................................................. 15-32
15.3.4.10
Importing Watchlist JAR Files into the Saved Search Project (USER_SAVED_
SEARCH) ......................................................................................................... 15-33
15.3.4.11
Promoting Saved Search to the ATK Watchlist (USER_SAVED_SEARCH) .... 15-33
15.3.4.11.1
How to Promote a User-Saved Search to the Watchlist ............................ 15-34
15.3.4.12
Code Task Flows to Accept Parameters (All except HUMAN_TASK) ............ 15-39
15.3.4.12.1
Saved Search ............................................................................................. 15-40
15.3.4.13
Import Watchlist UI JAR File in User Interface Project .................................... 15-41
15.3.4.14
Additional Entries for Standalone Deployment .............................................. 15-41
15.4
Implementing Group Spaces ........................................................................................ 15-41
15.4.1
Assumptions .......................................................................................................... 15-41
15.4.2
How to Implement Group Spaces .......................................................................... 15-41
15.4.3
Overview of Group Spaces Functionality .............................................................. 15-42
15.4.4
How to Pass a Chromeless Template ..................................................................... 15-42
15.5
Implementing Activity Streams and Business Events .................................................. 15-42
15.5.1
Introduction to WebCenter Portal Activities .......................................................... 15-43
15.5.2
How to Publish Business Events to Activities ........................................................ 15-43
15.5.3
How to Publish Activities Using a Programmatic API .......................................... 15-44
15.5.4
How to Implement Activity Streams ..................................................................... 15-47
xi
15.5.4.1
Defining and Publishing Business Events in JDeveloper ................................ 15-47
15.5.4.2
Overriding isActivityPublishingEnabled() to Enable Activity Publishing ...... 15-48
15.5.4.3
Defining Activity Attributes Declaratively ...................................................... 15-49
15.5.5
How to Define Activities ....................................................................................... 15-50
15.5.5.1
Adding the ActivityStream UI Task Flow ....................................................... 15-50
15.5.5.2
Defining Activities in the service-definition.xml File ...................................... 15-51
15.5.6
How to Implement Comments and Likes .............................................................. 15-55
15.5.7
How to Implement Follow for an Object ............................................................... 15-55
15.5.7.1
Defining the Service Category ......................................................................... 15-56
15.5.7.2
Adding ActivityTypes for Follow and Unfollow ............................................ 15-56
15.5.8
How to Render Contextual Actions in Activity Streams ........................................ 15-57
15.6
Implementing the Oracle Fusion Applications Search Results UI ................................ 15-58
15.6.1
How to Disable Oracle Fusion Applications Search .............................................. 15-58
15.6.2
How to Use Basic Search ........................................................................................ 15-58
15.6.2.1
Using the Search Filters ................................................................................... 15-59
15.6.2.2
Search Results ................................................................................................. 15-61
15.6.3
Introduction to the Crawled Objects Project .......................................................... 15-65
15.6.4
How to Implement Tags in Oracle Fusion Applications Search ............................ 15-65
15.6.5
How to Use the Actionable Results API with Oracle Fusion Applications Search 15-69
15.6.5.1
Implementing the URL Action Type ............................................................... 15-71
15.6.5.2
Implementing the Task Action Type ............................................................... 15-71
15.6.5.2.1
How to Implement Preferred Navigation ................................................. 15-73
15.6.5.3
Passing Parameters in Oracle Fusion Applications Search .............................. 15-76
15.6.5.4
Ordering the Other Actions ............................................................................. 15-77
15.6.5.5
Using Click Path and the Saved Search ........................................................... 15-77
15.6.6
How to Integrate Non-Applications Data into Oracle Fusion Applications Search
............................................................................................................................... 15-78
15.6.6.1
Oracle Business Intelligence Integration ......................................................... 15-78
15.6.6.2
Integrating Oracle WebCenter Portal ............................................................. 15-79
15.6.6.3
Ensuring Parity of Users ................................................................................. 15-80
15.7
Implementing Auto-suggest ........................................................................................ 15-81
15.7.1
How to Implement fnd:searchSuggestBehavior .................................................... 15-84
15.7.2
How to Implement a Custom Suggestion Group ................................................... 15-86
15.7.3
How to Implement fnd:searchSuggestBehavior in Global Search ......................... 15-89
xii
16.4.1
Implementation Notes ........................................................................................... 16-12
16.4.1.1
Developer Implementation .............................................................................. 16-13
16.5
Implementing the Third-Party Component Area ......................................................... 16-14
16.5.1
How to Implement the ThirdPartyComponentArea Facet Developer ................... 16-14
16.6
Developing an Activity Guide Client Application with the UI Shell ............................ 16-15
16.7
Implementing Touch Device Support in the UI Shell ................................................... 16-21
16.8
Troubleshooting UI Shell Issues ................................................................................... 16-22
16.8.1
ApplSession Is Not Created ................................................................................... 16-23
16.8.2
Navigator Shows a Little White Box ...................................................................... 16-24
16.8.3
Navigator Shows Unfiltered Entries ...................................................................... 16-25
xiii
17.4.1.1
17.4.1.2
17.4.2
17.4.2.1
17.4.2.2
17.4.2.3
17.4.2.4
How to Add Applications Popups to JSF Pages or Page Fragments ............... 17-51
How to Add Applications Popup Components Using the Wizard ................. 17-52
How to Modify Popup Components and Properties ............................................. 17-57
Accessing the Popup on a JSF Page ................................................................. 17-57
Adding a Data Source to an Existing Popup ................................................... 17-57
Adding User-Interface Content to an Existing Popup ..................................... 17-57
Adding action and actionListener Methods to the Popup Buttons ................. 17-58
19 Implementing Attachments
19.1
Introduction to Attachments .......................................................................................... 19-1
19.2
Using the Attachments Carousel .................................................................................... 19-6
19.3
Creating Attachments .................................................................................................... 19-7
19.3.1
How to Set Up Your Model Project for Attachments ............................................... 19-9
19.3.2
How to Create Attachment View Links ................................................................. 19-10
19.3.3
What Happens When You Create an Attachment View Link ................................ 19-15
19.3.4
How to Delete the Business Object ........................................................................ 19-16
xiv
xv
20.3.5
How to Create a Tree Structure ............................................................................. 20-16
20.3.6
How to Duplicate a Tree Structure ........................................................................ 20-24
20.3.7
How to Edit a Tree Structure ................................................................................. 20-25
20.3.8
How to Delete a Tree Structure .............................................................................. 20-26
20.3.9
How to Set Tree Structure Status ........................................................................... 20-26
20.3.10
How to Audit a Tree Structure .............................................................................. 20-27
20.4
Working with Trees ...................................................................................................... 20-30
20.4.1
How to Search for a Tree ....................................................................................... 20-30
20.4.2
How to Create a Tree ............................................................................................. 20-30
20.4.3
How to Duplicate a Tree ........................................................................................ 20-33
20.4.4
How to Edit a Tree ................................................................................................. 20-34
20.4.5
How to Delete a Tree ............................................................................................. 20-35
20.5
Working with Tree Versions ........................................................................................ 20-35
20.5.1
How to Create a Tree Version ................................................................................ 20-35
20.5.2
How to Add Tree Nodes to a Tree Version ............................................................ 20-39
20.5.2.1
How to Configure the Add Tree Node: Specific Values .................................. 20-40
20.5.2.2
How to Configure the Add Tree Node: Values Within a Range ..................... 20-41
20.5.2.3
How to Configure the Add Tree Node: Referenced Hierarchy ....................... 20-42
20.5.2.4
How to Use Drag-and-Drop to Move Nodes .................................................. 20-43
20.5.2.5
How to Add a Node Using a Custom Search UI ............................................. 20-43
20.5.2.6
How to Edit a Tree Node ................................................................................. 20-44
20.5.2.7
How to Export Tree Nodes .............................................................................. 20-45
20.5.3
How to Create a Record for a Data Source ............................................................ 20-47
20.5.4
How to Duplicate a Tree Version ........................................................................... 20-48
20.5.5
How to Edit a Tree Version ................................................................................... 20-48
20.5.6
How to Perform CRUD Operations on Tree Nodes Using APIs ............................ 20-49
20.5.7
How to Perform Sub-tree Node Operations Using PL/SQL APIs ......................... 20-53
20.5.8
How to Set Tree Version Status ............................................................................. 20-54
20.5.9
How to Audit Trees and Tree Versions ................................................................. 20-55
20.5.10
How to Flatten Rows and Columns ....................................................................... 20-61
20.6
Managing Labels in the Generic Label Data Source ..................................................... 20-63
20.6.1
How to Search for a Label ...................................................................................... 20-63
20.6.2
How to Create a Label ........................................................................................... 20-64
20.6.3
How to Edit a Label ............................................................................................... 20-65
20.6.4
How to Delete a Label ............................................................................................ 20-65
20.7
Using the Applications Hierarchy Component to Develop Applications .................... 20-66
20.7.1
How to Create a Tree Application ......................................................................... 20-67
20.7.2
How to Create a Tree Table Application ................................................................ 20-68
20.8
Integrating Custom Task Flows into the Applications Hierarchy Component ............ 20-70
20.8.1
Registering Custom Task Flows ............................................................................ 20-71
20.8.2
Creating Custom Task Flows ................................................................................. 20-72
20.8.2.1
How to Create a Search Task Flow for the Add Node Operation ................... 20-72
20.8.2.2
How to Create a Create Task Flow .................................................................. 20-74
20.8.2.3
How to Create a Duplicate Task Flow ............................................................. 20-75
20.8.2.4
How to Create an Edit Task Flow .................................................................... 20-77
20.8.2.5
How to Create a Delete Task Flow .................................................................. 20-78
20.9
Using the fnd:hierarchy Property Inspector to Specify Tree Versions .......................... 20-79
xvi
xvii
21.3.1.5
How to Format Percentage Values .................................................................. 21-12
21.3.2
What Happens When You Format Numbers ......................................................... 21-13
21.3.3
What Happens at Runtime: How Numbers Are Formatted .................................. 21-13
21.4
Formatting Date and Timestamp Values ...................................................................... 21-13
21.4.1
How to Format Dates and Timestamp Values ....................................................... 21-13
21.4.1.1
Formatting Dates ............................................................................................. 21-13
21.4.1.2
Formatting Current Dates ............................................................................... 21-15
21.4.1.3
Formatting Timestamp Values ........................................................................ 21-16
21.4.2
What Happens When You Format Dates and Timestamps ................................... 21-18
21.4.3
What Happens at Runtime: How Dates and Timestamps Are Formatted ............. 21-18
21.4.4
Standards and Guidelines for Formatting Dates and Timestamps ........................ 21-18
21.5
Formatting Time Zones ................................................................................................ 21-19
21.5.1
How to Format Time Zones ................................................................................... 21-19
21.5.2
How to Format Invariant Time Zone Values ......................................................... 21-23
21.5.3
What Happens When You Format Time Zones ..................................................... 21-23
21.5.4
What Happens at Runtime: How Time Zones Are Formatted ............................... 21-24
21.5.5
Standards and Guidelines ...................................................................................... 21-24
21.6
Formatting Numbers, Currency and Dates Using Localization Expression Language
Functions ...................................................................................................................... 21-24
21.6.1
How to Format Numbers, Currency and Dates Using Expression Language Functions
21-25
21.6.1.1
Formatting Numbers Using Expression Language Functions ......................... 21-25
21.6.1.2
Formatting Currency Using Expression Language Functions ......................... 21-26
21.6.1.3
Formatting Dates Using Expression Language Functions ............................... 21-26
21.6.2
What Happens When You Format Numbers, Currency and Dates Using Expression
Language Functions ............................................................................................... 21-27
21.6.3
What Happens at Runtime: How Currency, Dates and Numbers and Time Zones are
Formatted Using Expression Language Functions ................................................ 21-27
21.7
Implementing Bi-directional Support .......................................................................... 21-27
21.7.1
How to Implement Bi-directional Support ............................................................ 21-28
21.7.1.1
Making Panels and Columns Provide Bi-directional Support ......................... 21-28
21.7.1.2
Making Images Provide Bi-directional Support .............................................. 21-29
21.8
Supporting Mnemonic Keys ......................................................................................... 21-30
21.8.1
How to Implement Mnemonic Key Support ......................................................... 21-31
21.9
Implementing Localization Formatting in ADF Desktop Integration .......................... 21-32
21.9.1
How to Format Numbers ...................................................................................... 21-33
21.9.1.1
Formatting Numbers ....................................................................................... 21-33
21.9.1.2
What Happens When You Format Numbers .................................................. 21-34
21.9.1.3
What Happens at Runtime: How Numbers Are Formatted ............................ 21-34
21.9.2
How to Format Currency Values ........................................................................... 21-34
21.9.2.1
Formatting Currency Values ........................................................................... 21-34
21.9.2.2
What Happens When You Format Currencies ................................................ 21-35
21.9.2.3
What Happens at Runtime: How Currency Values Are Formatted ................ 21-35
21.9.3
How to Format Dates and Timestamp Values ....................................................... 21-35
21.9.3.1
Formatting Date and Timestamp Values ......................................................... 21-35
21.9.3.2
What Happens When You Format the Date and Timestamp .......................... 21-37
21.9.3.3
What Happens at Runtime: How Date and Timestamp Are Formatted .......... 21-37
21.9.3.4
Honoring Time Zones ..................................................................................... 21-37
xviii
xix
xx
xxi
xxii
xxiii
25.2.5.1
Creating an ADF Library JAR File ................................................................... 25-34
25.2.5.2
Importing Business Components from an ADF Library ................................. 25-35
25.2.6
How to Build a Key Flexfield Maintenance User Interface .................................... 25-35
25.2.6.1
Building a Key Flexfield Code-Combination Maintenance Page ..................... 25-36
25.2.6.2
Ensuring Proper Handling of New Rows ........................................................ 25-36
25.2.7
What Happens at Runtime: Creating New Combinations ..................................... 25-37
25.3
Completing the Consumer Tasks for Key Flexfields in Reference Mode ..................... 25-37
25.3.1
How to Create Key Flexfield View Links ............................................................... 25-38
25.3.2
How to Nest an Instance of the Key Flexfield Application Module in the Product
Application Module ............................................................................................... 25-40
25.3.3
How to Add an Instance of a Key Flexfield View Object to the Product Application
Module .................................................................................................................. 25-40
25.4
Employing Key Flexfield UI Components on a Page ................................................... 25-41
25.4.1
How to Employ a Key Flexfield Component on a Page ......................................... 25-41
25.4.1.1
Adding Key Flexfield UI Components to a Form or a Table ........................... 25-43
25.4.1.2
Ensuring Proper Handling of New Rows ........................................................ 25-45
25.4.1.3
Ensuring Proper Updating of Reference Mode SIN values in an ADF Form or ADF
Applications Table .......................................................................................... 25-46
25.4.1.4
Ensuring Proper Updating of Secondary Mode SIN Values in an ADF Form . 25-46
25.4.1.5
Dynamically Refreshing Segments on a Code-Combination Maintenance Page or
Secondary Usage Segments ............................................................................. 25-46
25.4.1.6
What Happens When You Add a Key Flexfield to a Page ............................... 25-47
25.4.2
How to Incorporate Key Flexfields into a Query Search Form .............................. 25-49
25.4.2.1
Setting Up the Business Component Model Layer .......................................... 25-49
25.4.2.2
Creating the Query Search Form ..................................................................... 25-51
25.4.3
How to Configure Key Flexfield UI Components .................................................. 25-55
25.4.3.1
Configuring Flexfield-Level User Interface Properties .................................... 25-55
25.4.3.2
Configuring Label-Based Segment UI Properties ............................................ 25-58
25.4.3.3
Configuring Secondary Usage UI Properties .................................................. 25-59
xxv
27.4.2.2
How to Test Flexfields From Integrated WebLogic Server ................................ 27-7
27.5
Deploying Flexfields in a Standalone WebLogic Server Environment ........................... 27-9
27.5.1
How to Package a Flexfield Application for Deployment ........................................ 27-9
27.5.1.1
Enabling the Flexfield Packaging Plugin ........................................................... 27-9
27.5.1.2
Generating an EAR File for the Application ...................................................... 27-9
27.5.2
How to Deploy a Flexfield Application ................................................................. 27-10
27.5.2.1
Creating an MDS Partition .............................................................................. 27-11
27.5.2.2
Mapping the EAR File to the MDS Partition ................................................... 27-12
27.5.2.3
Mapping the ApplCore Setup Application to the MDS Partition .................... 27-13
27.5.2.4
Including Product Application Model Libraries in the ApplCore Setup EAR File
........................................................................................................................ 27-14
27.5.2.5
Deploying the Product and Setup Applications to the Server Domains .......... 27-15
27.5.2.6
Priming the MDS Partition with Configured Flexfield Artifacts ..................... 27-15
27.6
Using the WLST Flexfield Commands to Deploy Flexfields ........................................ 27-15
27.6.1
How to Prepare Your Environment to Use the WLST Flexfield Commands ......... 27-16
27.6.2
How to Prepare Your Environment to Use the deployFlexForApp Command ..... 27-16
27.7
Regenerating Flexfield Business Components Programmatically ................................ 27-17
27.8
Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager ......... 27-18
xxvi
28.2.7
How to Automate the ECSF Command Line Administration Utility .................... 28-12
28.3
Setting Up Oracle Enterprise Manager and Discovering ECSF .................................... 28-13
28.3.1
How to Register the ECSF Runtime MBean to the Integrated WebLogic Server .... 28-13
28.3.1.1
Adding the MBean listener to web.xml ........................................................... 28-14
28.3.1.2
Creating the Application EAR File for Deployment ........................................ 28-14
28.3.1.3
Configuring Data Sources in Oracle WebLogic Server .................................... 28-14
28.3.1.4
Deploying the ECSF Application Using the EAR File ..................................... 28-14
28.3.1.5
Starting the Oracle WebLogic Server Instance ................................................. 28-15
28.3.2
How to Install Oracle Enterprise Manager ............................................................. 28-15
28.3.3
How to Discover ECSF in Oracle Enterprise Manager ........................................... 28-15
28.3.4
How to Add Users to the Administrators Group ................................................... 28-16
xxvii
xxviii
xxix
How to Update the Application Deployment Profile with the Target Directory for
Searchable Objects ................................................................................................. 33-32
33.6.3
How to Update the Application to Reference the ECSF Service Shared Library ... 33-33
33.6.4
How to Add the ECSF Runtime Library ................................................................ 33-34
33.6.5
How to Set the System Parameter for Web Service ................................................ 33-34
33.6.5.1
Setting the System Parameter in Java System Properties ................................ 33-34
33.6.5.2
Setting the System Parameter in the ecsf.properties File ................................. 33-34
33.6.6
How to Package and Deploy the Search Application ............................................ 33-34
33.6.6.1
Running the ant Targets from the Command Line .......................................... 33-35
33.6.6.2
Running the ant Targets from Oracle JDeveloper ........................................... 33-35
33.6.7
How to Update the Search Application with New Searchable Objects or Dependencies
............................................................................................................................... 33-35
33.6.8
How to Set Up the ECSF Client Application for Federation .................................. 33-35
33.6.8.1
Adding Encryption Keys to cwallet.sso and default-keystore.jks . 33-36
33.6.8.2
Adding the Keystore to jps-config.xml ............................................................ 33-36
33.6.8.3
Creating the Proxy User .................................................................................. 33-37
33.6.8.4
Updating connections.xml .............................................................................. 33-37
33.6.9
How to Set the SearchContext Scope to GLOBAL ................................................. 33-38
33.6.10
How to Integrate Federation Across Oracle Fusion Applications Product Families
............................................................................................................................... 33-39
33.7
Federating Oracle SES Instances .................................................................................. 33-40
33.8
Raising Change Events Synchronously ........................................................................ 33-41
33.9
Using the External ECSF Web Service for Integration .................................................. 33-41
33.9.1
Web Service Methods ............................................................................................ 33-42
33.9.2
ECSF Web Service WSDL and XSD ....................................................................... 33-42
33.9.3
Web Service Request XSDs and XMLs ................................................................... 33-49
33.9.3.1
SavedSearch Request XSD ............................................................................... 33-49
33.9.3.2
QueryMetaData Request XSD ......................................................................... 33-53
33.9.3.3
engineInstanceRequest Request XSD .............................................................. 33-54
33.9.4
Web Service Response XSDs .................................................................................. 33-55
33.9.4.1
getSavedSearch() ............................................................................................. 33-56
33.9.4.2
getSavedSearches() .......................................................................................... 33-57
33.9.4.3
saveSearch() .................................................................................................... 33-58
33.9.4.4
deleteSearch() .................................................................................................. 33-58
33.9.4.5
getSavedSearchDetails .................................................................................... 33-58
33.9.4.6
search() ............................................................................................................ 33-59
33.9.4.7
getEngineInstances() ....................................................................................... 33-63
33.9.5
How to Invoke the ECSF Web Service ................................................................... 33-65
33.9.5.1
Creating a JAX-WS Web Service Proxy ........................................................... 33-65
33.9.5.2
Modifying the AppModuleSearchServiceSoapHttpPortClient Class .............. 33-66
33.10 Localizing ECSF Artifacts ............................................................................................. 33-71
33.10.1
How to Translate Strings in Groovy Expressions .................................................. 33-72
33.10.1.1
Associating Resource Bundles to View Objects ............................................... 33-72
33.10.1.2
Using the format() Function in Groovy Expressions ....................................... 33-73
33.10.1.3
Associating Translated Labels to Attributes .................................................... 33-73
33.10.1.4
Using the getLabel() function in Groovy Expressions ..................................... 33-74
33.10.2
How to Localize Facet Display Names .................................................................. 33-74
33.10.2.1
Configuring LOVs for Localization Using the VL Table ................................. 33-74
33.6.2
xxx
33.10.2.2
Configuring LOVs for Localization Using the Resource Bundles .................... 33-76
33.10.3
How to Localize Crawl Management Display Names ........................................... 33-77
33.10.4
How to Localize Crawlable Dynamic Content ....................................................... 33-78
33.10.5
How to Localize Crawlable Template Content ...................................................... 33-78
33.10.6
How to Determine Locale ...................................................................................... 33-79
33.10.6.1
Search Page ...................................................................................................... 33-79
33.10.6.2
ECSF Command Line Administration Utility .................................................. 33-79
33.10.6.3
Crawl ............................................................................................................... 33-80
33.10.6.4
Query ............................................................................................................... 33-80
33.11 Using ECSF Diagnostics ............................................................................................... 33-80
33.11.1
Query Tests ............................................................................................................ 33-80
33.11.1.1
Simple Query ................................................................................................... 33-80
33.11.1.2
Searchable Object Metadata ............................................................................. 33-81
33.11.1.3
Searchable Groups ........................................................................................... 33-81
33.11.1.4
Advanced Query (Protected) ........................................................................... 33-82
33.11.2
Crawl Tests ............................................................................................................ 33-82
33.11.2.1
Crawl Searchable Object .................................................................................. 33-82
33.11.2.2
SES Instance ..................................................................................................... 33-83
33.11.2.3
Control Feed .................................................................................................... 33-83
33.11.2.4
Data Feed (Protected) ...................................................................................... 33-84
33.11.3
Environment and Configuration Information ........................................................ 33-84
33.11.3.1
Configuration Parameters ............................................................................... 33-84
33.11.3.2
Environment Information ................................................................................ 33-84
33.11.3.3
Data Source ..................................................................................................... 33-84
33.11.3.4
Application Extension/ApplCore Session Locale (Protected) ......................... 33-85
33.11.4
Security .................................................................................................................. 33-85
33.11.4.1
Security (Protected) ......................................................................................... 33-85
33.11.4.2
Credential Store ............................................................................................... 33-85
33.11.4.3
Security Plugin (Protected) .............................................................................. 33-86
33.12 Troubleshooting ECSF .................................................................................................. 33-86
33.12.1
Problems and Solutions ......................................................................................... 33-86
33.12.1.1
Cannot Remove the ECSF Runtime Server Library ......................................... 33-86
33.12.1.2
Cannot See Data in Data Feeds ........................................................................ 33-87
33.12.1.3
Configuration or Data Feed Execution Thread Is Busy for Longer than the
Configured Warning Timeout ......................................................................... 33-87
33.12.1.4
Class Not Found Errors When Running the ECSF Servlet .............................. 33-87
33.12.1.5
Out of Memory Error when Deploying the ECSF Application to Oracle WebLogic
Server or Running the Application .................................................................. 33-88
33.12.1.6
Blank Oracle ADF/UI Shell Pages ................................................................... 33-88
33.12.1.7
Memory Leak on ThreadLocal Variable (SearchContext) ................................ 33-88
33.12.1.8
How to Check the Space Availability for SES Crawls in the Database ............ 33-89
33.12.1.9
How to Crawl with a Different User ............................................................... 33-89
33.12.1.10
"FND-6601 Search categories are not available" .............................................. 33-90
33.12.1.11
"FND-6603 Search is not currently available" .................................................. 33-90
33.12.1.12
"FND-6606 An application error occurred with this search" ........................... 33-91
33.12.1.13
Query Does Not Return Search Results but No Errors Are Displayed on the UI
......................................................................................................................... 33-91
xxxi
FUSION_RUNTIME.FND_TABLE_OF_VARCHAR2_4000 Exception on
Schedules ........................................................................................................ 33-91
33.12.1.15
Where Can I Find the SES-ESS Crawler Logs? ................................................ 33-92
33.12.1.16
My Crawls Are Failing .................................................................................... 33-92
33.12.1.17
How to Get the Password for the SES Administration Page ........................... 33-92
33.12.2
Diagnosing ECSF Problems ................................................................................... 33-92
33.12.1.14
Part VI
34.1
34.2
34.3
34.4
xxxii
37.1
37.2
37.3
37.4
37.5
37.6
37.7
xxxiii
40.1
40.2
40.3
40.4
40.5
40.6
40.7
40.8
40.8.1
42.7.2
Runtime ................................................................................................................. 42-13
42.8
What You May Need to Know About Invoking an Asynchronous Service from Another
SOA Composite ............................................................................................................ 42-13
xxxv
Obtain the Single Task Object and Set Task Outcome ....................................... 45-5
How to Use the Single Server Task Query Service API ........................................... 45-5
Import Libraries into the Java Project ................................................................ 45-6
Import Code Packages into the Java Project ...................................................... 45-6
Declare and Obtain Task Query Service Object References ............................... 45-6
Manage Query and Task Outcome States ......................................................... 45-7
How to Use the Federated Server Task Query Service API ..................................... 45-7
Import Libraries into the Java Project ................................................................ 45-7
Import Code Packages into the Java Project ...................................................... 45-7
Create a List of Servers for a Parallel Federated Query ..................................... 45-7
Declare Task and Query Service References and Create the Workflow Client
Service Object .................................................................................................... 45-8
45.4.4.5
Obtain the Workflow Service Context ............................................................... 45-8
45.4.4.6
Implement Exception Handling for Federated Queries .................................... 45-8
45.4.4.7
Manage Query and Task Outcome States ......................................................... 45-9
45.4.5
How to Query and Traverse Federated and Non-federated Query Result Sets ....... 45-9
45.4.5.1
Determine Query Service Search Criteria .......................................................... 45-9
45.4.5.2
Construct the Predicate for queryTasks() ........................................................ 45-11
45.4.5.3
Arrange the Order of Results Returned by the queryTasks() Method ............. 45-12
45.4.5.4
Construct the List of Display Columns for the queryTasks() Method ............. 45-12
45.4.5.5
Construct a List of OptionalInfo Items to be Returned from queryTasks() ..... 45-12
45.4.5.6
Invoke queryTasks() with the Attribute Lists .................................................. 45-13
45.4.5.7
Iterate through the Result Set .......................................................................... 45-13
45.4.5.8
Programmatically Set the Task Outcome ........................................................ 45-14
45.5
Other Approaches ........................................................................................................ 45-15
45.6
Securing the Design Pattern ......................................................................................... 45-15
45.7
Verifying the Deployment ............................................................................................ 45-15
45.7.1
Deploying the Human Task ................................................................................... 45-15
45.7.2
Deploying Programmatic Task Functionality ........................................................ 45-15
45.7.3
Invoking Programmatic Task Functionality .......................................................... 45-16
45.8
Troubleshooting the Use Case ...................................................................................... 45-16
45.8.1
Troubleshooting Task Data .................................................................................... 45-16
45.8.2
Troubleshooting Java Code ................................................................................... 45-16
45.9
What You May Need to Know About Implementing Email Notification for an Oracle ADF
Task Flow for a Human Task ....................................................................................... 45-16
45.4.2.5
45.4.3
45.4.3.1
45.4.3.2
45.4.3.3
45.4.3.4
45.4.4
45.4.4.1
45.4.4.2
45.4.4.3
45.4.4.4
xxxvi
46.4.3.4
How to Modify <PLACE APPLICATION SPECIFIC CONTENT HERE> ......... 46-9
46.4.3.5
How to Implement Links ................................................................................. 46-10
46.4.3.6
How to Modify Comments and Attachments ................................................. 46-10
46.4.3.7
How to Modify Related Links ......................................................................... 46-12
46.4.3.8
How to Modify History ................................................................................... 46-12
46.4.4
Implementing a Task Detail with Contextual Area ................................................ 46-12
46.4.5
Implementing Email Notification .......................................................................... 46-13
46.4.5.1
Before You Begin ............................................................................................. 46-13
46.4.5.2
Determining the Implementation Approach ................................................... 46-13
46.4.5.3
Using an If Component ................................................................................... 46-14
46.4.5.4
Using a Separate View for Online and Email Versions ................................... 46-15
46.4.5.5
Fine-Tuning the Emailable Page ...................................................................... 46-16
46.4.6
Displaying Localized Translated Data ................................................................... 46-16
46.4.7
Displaying Rows in the Approval Task ................................................................. 46-17
46.4.8
Configuring a Deployment Profile ......................................................................... 46-17
46.5
Securing the Design Pattern ......................................................................................... 46-20
46.6
Verifying the Deployment ............................................................................................ 46-20
46.7
Troubleshooting the Use Case ...................................................................................... 46-22
46.7.1
Specify oracle.soa.workflow.wc in weblogic-application.xml ................................ 46-22
46.7.2
Set the FRAME_BUSTING Attribute in web.xml ................................................... 46-23
46.7.3
Migrate from an Earlier Version of the Drop Handler Template ........................... 46-23
46.7.4
Override the EL for the Create Button ................................................................... 46-24
Part VII
Implementing Security
xxxvii
48.1.1.1
Oracle Platform Security Services (OPSS) Security Framework ........................ 48-3
48.1.1.2
Oracle Web Services Manager ........................................................................... 48-4
48.1.1.3
Oracle ADF Security .......................................................................................... 48-5
48.1.1.4
Application User Sessions ................................................................................. 48-5
48.1.1.5
Oracle Fusion Data Security .............................................................................. 48-6
48.1.1.6
Oracle Virtual Private Database ........................................................................ 48-6
48.1.1.7
Oracle Data Integrator ....................................................................................... 48-6
48.1.2
Authentication ......................................................................................................... 48-6
48.1.2.1
Oracle Identity Management Repository .......................................................... 48-7
48.1.2.1.1
Users ........................................................................................................... 48-7
48.1.2.1.2
Roles ........................................................................................................... 48-7
48.1.2.1.3
Segregation of Duties .................................................................................. 48-7
48.1.2.1.4
File-Based Identity Store ............................................................................. 48-7
48.1.2.1.5
File-Based Policy Store ................................................................................ 48-8
48.1.2.1.6
ODI ............................................................................................................. 48-8
48.1.2.2
Identity Propagation ......................................................................................... 48-8
48.1.2.3
Application User Session Propagation ............................................................ 48-10
48.1.3
Authorization ........................................................................................................ 48-10
48.1.3.1
OPSS Application Security Repository ............................................................ 48-10
48.1.3.2
Oracle Fusion Data Security Repository .......................................................... 48-11
48.2
Authentication Techniques and Best Practices ............................................................. 48-11
48.2.1
APIs ....................................................................................................................... 48-11
48.2.2
Expression Language ............................................................................................. 48-12
48.2.3
Non-browser Based Login ..................................................................................... 48-12
48.3
Authorization Techniques and Best Practices .............................................................. 48-12
48.3.1
Function Security ................................................................................................... 48-12
48.3.1.1
Resource Entitlements and Permissions .......................................................... 48-13
48.3.1.2
Expression Language ...................................................................................... 48-13
48.3.2
Data Security ......................................................................................................... 48-13
48.3.2.1
APIs and Expression Language ....................................................................... 48-14
48.3.2.2
Oracle Virtual Private Database ...................................................................... 48-14
48.3.2.3
Personally Identifiable Information ................................................................ 48-14
48.3.2.4
Data Role Templates ....................................................................................... 48-14
xxxviii
49.3.1.5
49.3.2
49.3.2.1
49.3.2.2
49.3.2.3
xxxix
50.8.3
50.8.3.1
50.8.3.2
50.8.3.3
50.8.4
50.8.5
50.8.6
How to Configure the Object Instance Task Flow to Display in a Dialog .............. 50-42
Creating the Task Flow Executable in the Region Page Definition FIle ........... 50-43
Initializing the Object-Instance Task Flow Using a Managed Bean ................. 50-46
Registering the Managed Bean with Your Application's Task Flow ............... 50-47
How to Grant the End User Access to the Data Security Task Flows .................... 50-48
How to Grant the Application Access to the Application Policy Store .................. 50-49
How to Map the Application to an Existing Application Stripe ............................ 50-49
xl
53.2.3
How to Authorize the Service .................................................................................. 53-4
53.3
Securing the Portlet Client .............................................................................................. 53-7
53.4
Registering the Key Store and Writing to the Credential Store ...................................... 53-7
53.4.1
How to Register the Key Store and Write to the Credential Store ............................ 53-7
53.4.2
What Happens When You Register the Key Store and Write to the Credential Store
............................................................................................................................... 53-10
53.5
Maintaining Application Session Context Across Web Service Requests ..................... 53-10
xli
56 Defining Profiles
56.1
56.2
56.3
56.3.1
56.3.2
56.3.3
56.4
56.4.1
56.4.2
56.5
56.5.1
57 Initializing Oracle Fusion Application Data Using the Seed Data Loader
57.1
Introduction to the Seed Data Loader ............................................................................ 57-1
57.2
Using the Seed Data Loader in JDeveloper .................................................................... 57-2
57.2.1
Introduction to the Seed Data Framework ............................................................... 57-2
57.2.2
How to Set Up the Seed Data Environment ............................................................. 57-5
57.2.3
How to Use the Seed Data Extract Manager .......................................................... 57-13
57.2.4
How to Use Seed Data Extract Processing ............................................................. 57-16
57.2.4.1
Understanding Extract Taxonomy Partition Selection Dialogs ....................... 57-16
57.2.4.2
Using the Extract Seed Data Command Line Interface ................................... 57-20
57.2.5
How to Use the Seed Data Upload Manager ......................................................... 57-23
57.2.5.1
Uploading Seed Data ...................................................................................... 57-24
57.2.5.1.1
How to Upload Seed Data Using the Command Line Interface ............... 57-26
57.2.5.1.2
How to Invoke Seed Loader Modes .......................................................... 57-27
57.2.6
How to Share Application Modules ...................................................................... 57-29
57.2.7
How to Update Seed Data ..................................................................................... 57-31
57.2.7.1
Using Incremental Updates ............................................................................. 57-31
57.2.7.2
Implementing Java Database Connectivity-based National Language Support
Updates ........................................................................................................... 57-32
57.3
Translating Seed Data .................................................................................................. 57-33
57.3.1
How to Extract Translation Data ........................................................................... 57-33
57.3.1.1
Treating Seed Data Base XML and Language XLIFF as a Single Entity .......... 57-33
57.3.2
How to Process Seed Data Translations ................................................................. 57-33
57.3.3
How to Load Translation Seed Data ...................................................................... 57-33
57.3.4
Oracle Fusion Middleware Extensions for Applications Translation Support ....... 57-34
xlii
58.2.5
Application User Defined Properties ....................................................................... 58-5
58.2.5.1
User Defined Properties for Tables .................................................................... 58-5
58.2.5.2
User Defined Properties for Columns ............................................................... 58-9
58.2.5.3
User Defined Properties for Indexes ................................................................ 58-11
58.2.5.4
User Defined Properties for Constraints .......................................................... 58-12
58.2.5.5
User Defined Properties for Views .................................................................. 58-13
58.2.5.6
User Defined Properties for Sequence ............................................................. 58-14
58.2.5.7
User Defined Properties for Materialized View .............................................. 58-15
58.2.5.8
User Defined Properties for Materialized View Log ....................................... 58-16
58.2.5.9
User Defined Properties for Trigger ................................................................ 58-17
58.2.6
How to Create an Offline Database Object ............................................................ 58-17
58.2.7
How to Edit an Offline Database Object ................................................................ 58-18
58.2.8
How to Import an Offline Database Object ............................................................ 58-18
58.2.9
How to Deploy the Offline Database Objects ......................................................... 58-20
58.2.9.1
Deploying in SXML Persistence Format .......................................................... 58-20
58.2.9.1.1
How to Use the Database Object Deployment Wizard in JDeveloper ....... 58-20
58.2.9.1.2
How to Use the Database Object Deployment Command Line Interface . 58-25
58.2.9.2
Setting the CLASSPATH Variable ................................................................... 58-26
58.2.9.3
Using Bootstrap Mode ..................................................................................... 58-27
58.2.9.4
Deployment FAQ ............................................................................................ 58-27
58.2.9.5
Cleaning Database Objects .............................................................................. 58-28
58.2.9.5.1
Making a Database Object Obsolete .......................................................... 58-28
58.2.9.5.2
How to Use the Force Mode Option in Schema Deployment ................... 58-29
58.2.9.5.3
How to Use fnd_cleanup_pkg and fnd_drop_obsolete_objects ................ 58-29
58.2.9.5.4
Frequently Asked Questions ..................................................................... 58-31
58.3
Using Schema Separation to Provide Grants ................................................................ 58-32
59 Improving Performance
59.1
Introduction to Improving the Performance of Applications ......................................... 59-1
59.2
ADF Business Components Guidelines .......................................................................... 59-1
59.2.1
Working with Entity Objects .................................................................................... 59-2
59.2.1.1
Enable Batch Updates for your Entity Objects ................................................... 59-2
59.2.1.2
Children Entity Objects in Composite Entity Associations Should not set the
Foreign Key Attribute Values of the Parent ....................................................... 59-2
59.2.1.3
Avoid Using List Validator Against Large Lists ................................................ 59-2
59.2.1.4
Avoid Repeated Calls to the same Association Accessor .................................. 59-3
59.2.1.5
Close Unused RowSets ...................................................................................... 59-3
59.2.1.6
Use "Retain Association Accessor RowSet" when Appropriate ......................... 59-3
59.2.1.7
Mark the Change Indicator Column .................................................................. 59-4
59.2.2
Working with View Objects ..................................................................................... 59-4
59.2.2.1
Tune the View Object SQL Statement ................................................................ 59-4
59.2.2.2
Select the Correct Usage for View Objects ......................................................... 59-5
59.2.2.3
Set Appropriate Fetch Size and Max Fetch Size ................................................. 59-5
59.2.2.4
Use Bind Variables ............................................................................................ 59-6
59.2.2.5
Include at Least One Required or Selectively Required View Criteria Item ...... 59-6
59.2.2.6
Use Forward-Only Mode when Possible ........................................................... 59-6
59.2.2.7
Avoid Calling getRowCount ............................................................................. 59-7
xliii
Avoid Entity Object Fault-in by Selecting Necessary Attributes Up-Front ....... 59-7
Reduce the Number of View Object Key Attributes to a Minimum .................. 59-7
Use Range Paging when Jumping to Different Row Ranges ............................. 59-8
Use setListenToEntityEvents(false) for Non-UI Scenarios ................................ 59-8
Use Appropriate Getter or Setter on View Row ................................................ 59-9
Use Appropriate Indexes with Case-Insensitive View Criteria Items ............... 59-9
Avoid View Object Leaks .................................................................................. 59-9
Provide a "Smart" Filter when Using LOV Combobox ...................................... 59-9
Use Small ListRangeSize for LOVs .................................................................... 59-9
Avoid Reference Entity Objects when not Needed ........................................... 59-9
Do Not Use the "All at Once" Fetch Mode in View Objects ............................. 59-10
Do Not Use the "Query List Automatically" List of Value Setting .................. 59-10
Avoid the "CONTAINS" or "ENDSWITH" Operator for Required or Selectively
Required View Criteria Items .......................................................................... 59-10
59.2.3
Working with Application Modules ...................................................................... 59-10
59.2.3.1
Enable Lazy Delivery ...................................................................................... 59-10
59.2.3.2
Make Application Code Passivation-Safe ........................................................ 59-10
59.2.3.3
Avoid Passivating Read-Only View Objects ................................................... 59-12
59.2.3.4
Avoid Passivating Certain Transient Attributes of a View Object .................. 59-13
59.2.3.5
Maintain Application Session User Tables ...................................................... 59-13
59.2.3.6
Tune the Application Module Release Level ................................................... 59-15
59.2.3.7
Do Not Leave Uncommitted Database Updates Across Requests ................... 59-17
59.2.3.8
Release Dynamically Created Root Application Modules .............................. 59-17
59.2.3.9
Do Not Destroy the Application Module when Calling Configuration.releaseRoot
ApplicationModule. ........................................................................................ 59-17
59.2.4
Working with Services ........................................................................................... 59-17
59.2.4.1
Set the Find Criteria to Fetch Only Attributes that are Needed ....................... 59-18
59.2.4.2
Expose Service for Frequently Used Logical Entities ...................................... 59-18
59.2.4.3
Use Correct ChangeOperation when Calling a Service ................................... 59-18
59.2.4.4
Set Only Changed Columns on Service Data Objects for Update ................... 59-19
59.3
ADF ViewController Layer Guidelines ........................................................................ 59-19
59.3.1
Working with Various ADF ViewController Components .................................... 59-19
59.3.1.1
Minimize the Number of Application Module Data Controls ......................... 59-19
59.3.1.2
Use the Visible and Rendered Attributes ........................................................ 59-19
59.3.1.3
Remove Unused Items from Page Bindings .................................................... 59-19
59.3.1.4
Disable Column Stretching .............................................................................. 59-19
59.3.1.5
Use Appropriate Values for Refresh and RefreshCondition ........................... 59-19
59.3.1.6
Disable Estimated Row Count if Necessary .................................................... 59-20
59.3.1.7
Use HTTPSession Hash Table in Moderation ................................................. 59-21
59.3.1.8
Use Short Component IDs ............................................................................... 59-21
59.3.1.9
Follow UI Standards when Using Search ........................................................ 59-21
59.3.1.10
Do not set Client Component Property to True ............................................... 59-21
59.3.1.11
Set Immediate Property to True when Appropriate ........................................ 59-22
59.3.1.12
Use Appropriate ContentDelivery Mode for a Table or a Tree Table .............. 59-22
59.3.1.13
Set the Appropriate Fetch Size for a Table ...................................................... 59-22
59.3.1.14
Avoid Frozen Columns and Header Columns if Possible ............................... 59-22
59.3.1.15
Avoid Unnecessary Regions ............................................................................ 59-22
59.3.1.16
Set the Data Control Scope to "Shared" ........................................................... 59-22
59.2.2.8
59.2.2.9
59.2.2.10
59.2.2.11
59.2.2.12
59.2.2.13
59.2.2.14
59.2.2.15
59.2.2.16
59.2.2.17
59.2.2.18
59.2.2.19
59.2.2.20
xliv
59.3.1.17
Select the No Save Point Option on a Task Flow when Appropriate .............. 59-23
59.3.1.18
Use Click-To-Edit Tables when Appropriate ................................................... 59-23
59.3.1.19
Avoid Unnecessary Task Flow Activation for Regions Under Popups ........... 59-23
59.3.1.20
Delay Creation of Popup Child Components .................................................. 59-24
59.3.1.21
Avoid Unnecessary Task Flow Activation for Regions Under Switchers ........ 59-24
59.3.1.22
Avoid Unnecessary Root Application Module Creation from UI-layer Code . 59-24
59.3.1.23
Avoid Unnecessary Savepoints on Task Flow Entry ....................................... 59-25
59.3.1.24
Cache Return Values in Backing Bean Getters ................................................ 59-25
59.3.1.25
Do Not Maintain References to UI Components in Managed Beans ............... 59-25
59.3.1.26
Set childCreation Property to Delay Child Component Creation .................... 59-26
59.3.1.27
Delay Activation of Taskflow Regions That are not Always Rendered ........... 59-26
59.3.2
Enable ADF Rich Client Geometry Management ................................................... 59-26
59.3.3
Use Page Templates ............................................................................................... 59-26
59.3.4
Use ADF Rich Client Partial Page Rendering (PPR) .............................................. 59-26
59.4
SOA Guidelines for Human Workflow and Approval Management Extensions ......... 59-26
59.5
Oracle Fusion Middleware Extensions for Applications Guidelines ............................ 59-26
59.5.1
Use Profile.get to Get Profile Option Values .......................................................... 59-27
59.5.2
Release any Application Modules Returned from getInstance Calls ..................... 59-27
59.5.3
Avoid Unnecessary Activation of Attachments Taskflow ..................................... 59-27
59.5.4
Use Static APIs on Message Get Message Text ...................................................... 59-27
59.5.5
Set the Data Control Scope to Isolated for Page Level Item Nodes ........................ 59-28
59.6
General Java Guidelines ............................................................................................... 59-28
59.6.1
Working with Strings and StringBuilder ............................................................... 59-28
59.6.1.1
Use StringBuilder Rather than the String Concatenation Operator (+) ........... 59-28
59.6.1.2
Check the Log Level Before Making a Logging Call ........................................ 59-29
59.6.1.3
Use Proper Logging APIs for Debug Logging ................................................. 59-30
59.6.1.4
Lazy Instantiation ............................................................................................ 59-30
59.6.2
Configure Collections ............................................................................................ 59-30
59.6.3
Manage Synchronization ....................................................................................... 59-30
59.6.4
Work with Other Java Features .............................................................................. 59-30
59.6.4.1
Avoid Autoboxing ........................................................................................... 59-31
59.6.4.2
Do not use Exceptions for Code Path Execution .............................................. 59-31
59.6.4.3
Reuse Pattern Object for Regular Expression Matches .................................... 59-31
59.6.4.4
Avoid Repeated Calls to the same APIs that have Non-Trivial Costs ............. 59-31
59.6.4.5
Close Unused JDBC Statements to Avoid Memory Leaks ............................... 59-31
59.6.4.6
Use registerOutParameter to Specify Bind Types and Precisions .................... 59-33
59.6.4.7
Avoid JDBC Connection Leaks ........................................................................ 59-33
59.7
Caching Data ................................................................................................................ 59-33
59.7.1
Identifying Data to Cache ...................................................................................... 59-34
59.7.2
How to Add Data to Cache .................................................................................... 59-34
59.7.3
How to Cache Multi-Language Support Data ....................................................... 59-35
59.7.3.1
Creating ADF Business Components objects for shared MLS data ................. 59-35
59.7.3.1.1
How to create objects if only the data from the base table must be shared
.................................................................................................................. 59-35
59.7.3.1.2
How to create objects if only the data from the _TL table must be shared 59-35
59.7.3.1.3
How to create objects if both the data from the base table and the _TL table
must be shared .......................................................................................... 59-36
xlv
Creating ADF Business Components Objects that Join to MLS tables ............. 59-36
How to create objects if only the data from the base table is required ...... 59-36
How to create objects if only data from the _TL table is required ............. 59-36
How to create objects if data from both the base table and the _TL table is
required .................................................................................................... 59-37
59.7.4
How to Consume Cached Data .............................................................................. 59-37
59.7.4.1
Consuming Shared Data Using a View Accessor ............................................ 59-37
59.7.4.2
Creating a shared application module programmatically ............................... 59-38
59.7.5
What Happens at Runtime: When Another Service Accesses the Shared Application
Module Cache ........................................................................................................ 59-38
59.8
Profiling and Tracing Oracle Fusion Applications ....................................................... 59-38
59.8.1
How to Profile Oracle Fusion Applications with JDeveloper Profiler ................... 59-38
59.9
Set up a Debug Breakpoint ........................................................................................... 59-39
59.7.3.2
59.7.3.2.1
59.7.3.2.2
59.7.3.2.3
60.5.1.9
Missing ADF Component at Runtime in Oracle WebLogic Server .................. 60-12
60.5.1.10
Odd ADF Component Errors .......................................................................... 60-13
60.5.1.11
Oracle WebLogic Server is Not Responding .................................................... 60-13
60.5.1.12
Missing Base Class ........................................................................................... 60-14
60.5.1.13
Unavailable FND Components ....................................................................... 60-14
60.5.1.14
JavaServer Pages Compilation Errors .............................................................. 60-14
60.5.1.15
ApplicationDB Errors While Running the Integrated WebLogic Server ......... 60-14
60.5.1.16
Metadata Services Runtime Exception ............................................................ 60-15
60.5.1.17
Application Cannot Fetch Data from Oracle Fusion Applications Database ... 60-15
60.5.1.18
"The task cannot be processed further" Message Appears .............................. 60-15
60.5.1.19
TimedOut Exception Occurs ........................................................................... 60-16
60.6
Testing and Troubleshooting Oracle SOA Suite ........................................................... 60-16
xlvii
61.5.4
Using Multi-Valued Dimension Attributes ............................................................ 61-14
61.5.5
Using Junk Dimensions and Mini Dimensions ...................................................... 61-15
61.5.6
Using Secured and Unsecured Dimension View Objects ....................................... 61-15
61.6
Designing Date Dimensions ......................................................................................... 61-15
61.6.1
Using the Gregorian Calendar ............................................................................... 61-15
61.6.2
Using the Fiscal Calendar ...................................................................................... 61-16
61.6.3
Using the Projects Calendar ................................................................................... 61-16
61.6.4
Using Timestamp Columns ................................................................................... 61-16
61.6.5
Using Role-Playing Date Dimensions .................................................................... 61-16
61.7
Designing Lookups as Dimensions .............................................................................. 61-16
61.7.1
Securing Data on Lookups ..................................................................................... 61-17
61.8
Designing and Securing Tree Data ............................................................................... 61-17
61.8.1
Designing a Column-Flattened View Object for Oracle Business Intelligence ....... 61-17
61.8.1.1
How to Generate a BICVO Automatically Using Tree Management .............. 61-20
61.8.2
Customizing the FND Table Structure and Indexes .............................................. 61-22
61.8.3
Using Declarative SQL Mode to Design View Objects for Oracle Business Intelligence
Applications ........................................................................................................... 61-22
61.8.3.1
Using Single Data Source View Object Design Pattern .................................. 61-22
61.8.3.2
Using Multiple Data Source View Objects Design Pattern ............................. 61-23
61.8.3.3
Setting the Declarative-Mode BICVO Properties ............................................ 61-25
61.8.4
Guidelines for ATG-Registration and BICVO Generation ..................................... 61-25
61.8.5
Guidelines for Hierarchy Depth and Conformance ............................................... 61-26
61.8.5.1
Resolving Problems ......................................................................................... 61-28
61.8.6
Securing ADF Business Components View Objects for Trees ................................ 61-28
61.8.6.1
Security Implementation ................................................................................. 61-29
61.9
Supporting Flexfields for Oracle Business Intelligence ................................................ 61-30
61.10 Supporting SetID .......................................................................................................... 61-30
61.10.1
How to Expose the SetID Attribute for Set-Enabled Lookups ............................... 61-30
61.10.2
How to Expose the SetID Attribute for Set-Enabled Reference Tables .................. 61-31
61.11 Supporting Multi-Currency ......................................................................................... 61-31
62.1
63.2.4
How to Add Composer Technology Scope to Your Project ..................................... 63-6
63.2.5
How to Enable the User Customization of the UI Shell Template ........................... 63-7
63.2.6
How to Create a Database Connection at the IDE Level .......................................... 63-8
63.3
Enabling Runtime Customization of Pages and Components ........................................ 63-9
63.3.1
How to Enable Pages for Runtime Customization ................................................. 63-11
63.3.1.1
Ensuring Customizable Pages Have Page Definitions .................................... 63-12
63.3.1.2
Making a JSPX Document Editable at Runtime ............................................... 63-12
63.3.1.3
Setting Up a Resource Catalog ........................................................................ 63-12
63.3.1.4
Using the Default Catalog Definition File for Testing ..................................... 63-12
63.3.2
How to Enable End-User Personalizations for a Page ........................................... 63-13
63.3.3
How to Restrict Customization of a Page, Page Fragment, or Component ........... 63-13
63.3.4
How to Authorize the Runtime Customization of Pages and Task Flows ............. 63-14
63.3.5
How to Persist Implicit Runtime Customizations .................................................. 63-15
xlix
64.9.1
How to Implement a Perl Scheduled Job ............................................................... 64-23
64.9.2
What Happens When You Implement a Perl Scheduled Job ................................. 64-24
64.10 Implementing a C Scheduled Job ................................................................................. 64-26
64.10.1
How to Define Metadata for a C Scheduled Job .................................................... 64-26
64.10.2
How to Implement a C Scheduled Job ................................................................... 64-26
64.10.3
Scheduled C Job API .............................................................................................. 64-26
64.10.4
How to Test a C Scheduled Job .............................................................................. 64-28
64.10.5
What Happens When You Implement a C Scheduled Job ..................................... 64-29
64.10.6
What Happens at Runtime: How a C Scheduled Job Is Implemented ................... 64-32
64.11 Implementing a Host Script Scheduled Job .................................................................. 64-32
64.12 Implementing a Java Scheduled Job ............................................................................. 64-33
64.12.1
How to Define Metadata for a Scheduled Java Job ................................................ 64-33
64.12.2
How to Use the Java Runtime API ......................................................................... 64-33
64.12.3
How to Cancel a Scheduled Java Job ..................................................................... 64-33
64.12.4
What Happens at Runtime: How a Java Scheduled Job Is Implemented ............... 64-34
64.13 Elevating Access Privileges for a Scheduled Job .......................................................... 64-34
64.13.1
How to Elevate Access Privileges for a Scheduled Job .......................................... 64-35
64.13.2
How Access Privileges Are Elevated for a Scheduled Job ..................................... 64-36
64.13.3
What Happens When Access Privileges Are Elevated for a Scheduled Job ........... 64-37
64.14 Creating an Oracle ADF User Interface for Submitting Job Requests .......................... 64-37
64.14.1
How to Create an Oracle ADF User Interface for Submitting Job Requests ........... 64-37
64.14.2
How to Add a Custom Task Flow to an Oracle ADF User Interface for Submitting Job
Requests ................................................................................................................. 64-44
64.14.3
How to Enable Support for Context-Sensitive Parameters in an Oracle ADF User
Interface for Submitting Job Requests .................................................................... 64-45
64.14.4
How to Save and Schedule a Job Request Using an Oracle ADF UI ...................... 64-46
64.14.5
How to Submit a Job Using a Saved Schedule in an Oracle ADF UI ..................... 64-47
64.14.6
How to Notify Users of the Status of Executed Jobs .............................................. 64-48
64.14.7
What Happens When You Create an Oracle ADF User Interface for Submitting Job
Requests ................................................................................................................. 64-48
64.14.8
What Happens at Runtime: How an Oracle ADF User Interface for Submitting Job
Requests Is Created ................................................................................................ 64-48
64.15 Submitting Job Requests Using the Request Submission API ...................................... 64-49
64.16 Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled
Job ................................................................................................................................ 64-49
64.16.1
How to Define Oracle BI Publisher Postprocessing for a Scheduled Job ............... 64-49
64.16.2
How to Define Oracle BI Publisher Postprocessing Actions for a Scheduled PL/SQL
Job .......................................................................................................................... 64-53
64.16.3
Invoking Postprocessing Actions Programmatically ............................................. 64-54
64.16.4
What Happens When You Define Oracle BI Publisher Postprocessing Actions for a
Scheduled Job ........................................................................................................ 64-57
64.16.5
What Happens at Runtime: How Oracle BI Publisher Postprocessing Actions are
Defined for a Scheduled Job .................................................................................. 64-57
64.17 Monitoring Scheduled Job Requests Using an Oracle ADF UI ..................................... 64-57
64.17.1
How to Monitor Scheduled Job Requests .............................................................. 64-58
64.17.2
How to Embed a Table of Search Results as a Region on a Page ........................... 64-59
64.17.3
How to Log Scheduled Job Requests in an Oracle ADF UI .................................... 64-60
64.17.4
How to Troubleshoot an Oracle ADF UI Used to Monitor Scheduled Job Requests
............................................................................................................................... 64-61
l
Using a Task Flow Template for Submitting Scheduled Requests Through an Oracle ADF
UI .................................................................................................................................. 64-63
64.18.1
How to Use a Task Flow Template for Submitting Scheduled Requests through an
Oracle ADF UI ....................................................................................................... 64-63
64.18.2
How to Extend the Task Flow Template for Submitting Scheduled Requests through
an Oracle ADF UI ................................................................................................... 64-64
64.18.3
What Happens When you Use a Task Flow Template for Submitting Scheduled
Requests through an Oracle ADF UI ...................................................................... 64-65
64.18.4
What Happens at Runtime: How a Task Flow Template Is Used to Submit Scheduled
Requests through an Oracle ADF UI ...................................................................... 64-65
64.19 Securing Oracle ADF UIs ............................................................................................. 64-66
64.20 Integrating Scheduled Job Logging with Oracle Fusion Applications .......................... 64-66
64.21 Logging Scheduled Jobs and Writing to Output Files .................................................. 64-67
64.21.1
Using the Request Log ........................................................................................... 64-67
64.21.2
Using the Output File ............................................................................................ 64-67
64.21.3
Debugging and Error Logging ............................................................................... 64-68
64.18
li
Part IX Appendices
A Working with the Application Taxonomy
A.1
Introduction to the Oracle Fusion Application Taxonomy ...............................................A-1
A.1.1
Characteristics of the Level Categories ......................................................................A-2
A.1.2
How to Manage the Lifecycle ....................................................................................A-2
A.1.2.1
Creating Patches and Patch Sets ..........................................................................A-2
A.1.2.2
System Administration ........................................................................................A-2
A.1.2.3
Diagnostics and Maintenance .............................................................................A-3
A.1.3
Benefits of a Logical Hierarchy ..................................................................................A-3
A.1.4
Delivery Hierarchy ....................................................................................................A-3
A.1.5
How to Integrate Taxonomy Task Flows into Oracle Fusion Functional Setup Manager
...................................................................................................................................A-4
A.2
Working with Objects and Methods in the Application Taxonomy .................................A-4
A.2.1
Particular Table Columns and Data ...........................................................................A-5
A.2.2
Denormalized Taxonomy Table .................................................................................A-5
lii
A.2.3
Available Public Business Objects ..............................................................................A-6
A.2.3.1
Accessing the Entity and View Objects ...............................................................A-8
A.2.4
How to Use Exposed Service Methods ....................................................................A-10
A.2.5
How to Traverse the Taxonomy Hierarchy ..............................................................A-11
A.3
Understanding Taxonomy MBeans ................................................................................A-11
liii
liv
Preface
Welcome to the Developer's Guide! This guide describes the Oracle Middleware
Extensions for Applications for developing Oracle Fusion Applications using the
Oracle Fusion Middleware components. This guide includes guidelines on how to set
up your development environment and build, test, and deploy Oracle Fusion
Applications. It includes specific feature details needed by developers when using the
Oracle Middleware Extensions to create applications.
Audience
This document is intended for Oracle Fusion Applications Developers and assumes
familiarity with:
Oracle JDeveloper
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For
information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are
hearing impaired.
Related Documents
For more information, see the following documents in the Oracle 11g Fusion
Middleware documentation set:
lv
Oracle Fusion Middleware Mobile Browser Developer's Guide for Oracle Application
Development Framework
Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application
Development Framework
Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence Enterprise
Edition
Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business
Intelligence Enterprise Edition
Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence Publisher
Oracle Fusion Middleware Report Designer's Guide for Oracle Business Intelligence
Publisher
Oracle Fusion Middleware Modeling and Implementation Guide for Oracle Business
Process Management
Oracle Fusion Middleware Business Process Composer User's Guide for Oracle Business
Process Management
Oracle Fusion Middleware Developer's Guide for Oracle Data Integrator
Oracle Fusion Middleware Connectivity and Knowledge Modules Guide for Oracle Data
Integrator
Oracle Fusion Middleware Knowledge Module Developer's Guide for Oracle Data
Integrator
Oracle WebCenter Content Developer's Guide for Imaging
Oracle Fusion Middleware Application Developer's Guide for Oracle Identity
Management
Oracle Fusion Middleware Language Reference Guide for Oracle Business Rules
Oracle Fusion Middleware User's Guide for Oracle Business Activity Monitoring
lvi
Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application
Development Framework
Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle
JDeveloper
Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces
Conventions
The following text conventions are used in this document:
Convention
Meaning
boldface
italic
monospace
lvii
lviii
lix
A section describing the Attachments Carousel component has been added. See
Section 19.2, "Using the Attachments Carousel."
A section describing the properties that set the default behavior of the
Attachments Carousel component has been added. See Section 19.6, "Configuring
the Attachments Carousel UI."
Web Service APIs for Trees. See Section 20.13.2, "How to Use TreeService."
Run with Flexfield dialog, which enables you to test a flexfield from Oracle
JDeveloper. See Section 27.4.1, "Testing Flexfields from Oracle JDeveloper."
Flexfield Registration Metadata wizard, which you can use to register and define a
descriptive flexfield. See Section 23.2.2.1, "Using the Flexfield Registration
Metadata Wizard To Register and Define Descriptive Flexfields."
Ability to select usages in the Flexfield Business Component wizard. See
Section 23.3.1, "How to Create Descriptive Flexfield Business Components."
Flexfield Business Component wizard support for extensible flexfields. See
Section 24.8.1, "How to Create Business Components For an Extensible Flexfield's
Usage."
Drag and drop components for adding extensible flexfield task flows. See
Section 24.9, "Employing an Extensible Flexfield on a User Interface Page."
Ability to make a UI Shell page customizable at runtime. See Section 63.2.5, "How
to Enable the User Customization of the UI Shell Template."
Support in the UI Shell for tablet devices. See Section 16.7, "Implementing Touch
Device Support in the UI Shell."
Adding support for Oracle Social Network to an Oracle Fusion application. See
Chapter 66, "Implementing Oracle Social Network Integration."
lx
Column names "Last Updated By" and "Last Updated Date" have been replaced by
"Attached By" and "Attached Date". See Chapter 19, "Implementing Attachments."
lxi
lxii
Part I
Part I
1
Getting Started with Oracle Fusion
Applications
This chapter describes how to design and build your Oracle Fusion Applications using
Oracle standards and guidelines. It includes an overview of Oracle Fusion
technologies and using Oracle Application Development Framework (ADF) functional
patterns.
This chapter includes the following sections:
Section 1.2, "Using Oracle ADF Functional Patterns and Best Practices"
Model technologies
Backend technologies
Orchestration technologies
Security
Customization-related technologies
Metadata services
UI Technologies
Technologies that are used to create user interfaces fall into this category. The
technologies that must be used in Oracle Fusion to create these user interfaces are:
1-1
ADF Mobile:
This technology is used to create interfaces that can be accessed through browsers
in mobile devices.
For more information about ADF Mobile, see the Oracle Fusion Middleware Mobile
Browser Developer's Guide for Oracle Application Development Framework.
Model Technologies
Technologies that are used to represent the business logic and the data on which the
business logic is based fall into this category. The UI technologies discussed previously
can be based on any model technology such as Enterprise JavaBeans (EJB), Oracle
Toplink, and so on. In Oracle Fusion, ADF Business Components is the model
technology that is used in all applications.
Backend Technologies
These technologies are the set of storage technologies that are used to store the
transactional and relational data. The primary technologies used in Oracle Fusion to
store and retrieve data are:
Oracle Database: This is used to store and retrieve all transactional and reference
data.
For more information see the Oracle Database Administrator's Guide.
Orchestration Technologies
These are the technologies that are used in the service-oriented architecture (SOA)
world. The primary purpose of these technologies is to assemble various services
together to provide comprehensive functionality.
In Oracle Fusion, many product applications provide their functionality in the form of
web services. OracleAS BPEL Process Manager is used to assemble these web services
together to provide end-to-end functionality.
For more information about SOA, see the Oracle Fusion Middleware Developer's Guide for
Oracle SOA Suite.
Security
Security is an integral part of all of the technologies previously mentioned. The
technology used to provide security for Oracle Fusion Applications is Oracle Platform
Security Services (OPSS).
For more information about OPSS, see the Oracle Fusion Middleware Oracle Platform
Security Services (OPSS) & Oracle Authorization Policy Manager (OAPM) Frequently Asked
Questions.
Customization-Related Technologies
Customization-related technologies give customers the tools they need to customize
the artifacts that developers have created. For example, the customer requires more
information on the Invoices Entry UI that the developer created. They want to
customize the UI by adding this extra information. To perform this type of
customization, Metadata Services (MDS) technology is used.
Another level of customization, which is used to customize the UI pages at runtime, is
called Design Time at Runtime (DTRT) customization. This type of customization is
performed using the WebCenter technologies. (This uses Oracle Metadata Services
(MDS) internally.)
Additional Technologies
In addition to the technologies previously discussed, there are many others that Oracle
Fusion web application developers may encounter. These include:
Oracle Enterprise Crawl and Search Framework (ECSF): ECSF helps expose
application context information on business objects to enable full-text transactional
search.
For more information about Oracle Enterprise Crawl and Search Framework, see
Chapter 28, "Getting Started with Oracle Enterprise Crawl and Search
Framework."
Oracle Business Rules (OBR): Oracle Business Rules enable dynamic decisions at
runtime allowing you to automate policies, computations, and reasoning while
separating rule logic from underlying application code. This allows more agile
rule maintenance and empowers business analysts with the ability to modify rule
logic without programmer assistance and without interrupting business processes.
For more information about Oracle Business Rules, see the Oracle Fusion
Middleware User's Guide for Oracle Business Rules.
1-3
For more information about Oracle Data Integrator, see the Oracle Fusion
Middleware Developer's Guide for Oracle Data Integrator.
Unsaved Changes
2
Setting Up Your Development Environment
This chapter describes how to configure and test your development environment. It
includes the steps for setting up your JDeveloper environment and Oracle Application
Development Framework (Oracle ADF) installation, running and deploying
applications on Integrated WebLogic Server, and the basic steps for setting up your
Oracle SOA Suite development environment.
This chapter includes these sections:
Section 2.4, "Configuring Oracle SOA Suite and Oracle Enterprise Manager Fusion
Middleware Control"
Section 2.8, "Using Best Practices for Setting Up the Development Environment"
Note:
2-1
the application and begin the process of configuring the functional (application
specific) components.
On-site, the administrator uses eDelivery or the DVD media to kick-start the
provisioning processes to create the test environment and the production environment.
These environments are completely isolated from one another and set up in an
identical manner. There is no reuse of, for example, the database from the production
environment in the test environment, or reuse of the Identity Store across the
environments.
These environments need to be extremely stable and should not be affected by
development projects. Typical development projects include creating new
customizations for existing Oracle Fusion applications, developing new in-house
Oracle Fusion applications, and extending Oracle Fusion applications with additional
functionality. These development projects will typically involve a team of developers
that needs to reuse certain parts, but still needs the isolation to run, test, and debug
without affecting other team members.
As a developer, you will work with one development environment that has two parts:
Shared environment
This fully-provisioned Oracle Fusion Applications environment includes the
database and LDAP. It also can host the instance of WebLogic Server if you require
SOA for your customization work. The shared environment usually is designated
as the Test environment.
Personal environment
This is the JDeveloper instance and an instance of Integrated WebLogic Server that
can run on your local desktop or laptop. You still would connect to the database
and LDAP instances on the shared environment.
The Personal environment also can have a standalone MW_HOME and WebLogic
Server domain, such as:
standalone: Only the AdminServer where you can run and deploy ADF
applications.
The shared environment plus the personal environment form the complete
development environment.
Database
The shared environment can be accessed from the personal environment (see
Section 2.1.2, "Personal Environment") so developers can reach the installation
directory that normally is called MW_HOME.
The exploded EAR directory in Middleware home can be opened from JDeveloper
and a workspace can be created. The exploded EARs in Middleware home have
the connections.xml and adf-config.xml files set up correctly to point to the
correct database and other deployed applications in the shared environment.
The LDAP and OPSS credentials in the personal environment point to the Identity
Store and the Policy Store in the shared environment.
WebLogic Server domains run in the shared environment and Oracle Fusion
applications are deployed to those domains.
The shared environment is a completely-provisioned Oracle Fusion Applications
instance.
2-3
Installing JDeveloper
Using JDeveloper and the Oracle Fusion Domain wizard, you can create the fusion_
apps_wls.properties file and a credential store. You will enter the host, port, and
other details for the database and Identity Store from the shared environment.
Eventually, the wizard will do the following:
Create DefaultDomain.
Extend DefaultDomain with WebLogic Server templates so that the shared
libraries are added to the CLASSPATH and the system properties are set.
Configure DefaultDomain with datasources and the Identity Store that are
available in the shared environment.
Note:
If you are using your own workstation, you probably have a process called SCIM
(Smart Common Input Method) running. SCIM is an input method platform used for
multilingual work.
This process may prevent you from entering a password in the Oracle Fusion Domain
wizard or anywhere a JPasswordField occurs. If it does interfere with your work, you can
remove SCIM from your system by executing this command.
sudo yum remove scim
If you do not want to remove it completely, you can just kill the processes by executing
the following command. However, if you just kill the processes instead of removing
SCIM, you must kill them each time you reboot your system.
ps -ef | grep -i scim
Note:
If you have not already done so, download and install the 64-bit JDK. To avoid the
possibility of script errors, do not install to a directory location containing spaces,
such as Program Files.
When installing JDeveloper, you will select the 64-bit JDK location you just
installed.
If a 32-bit JDK was already installed and used, you must delete the old %MW_HOME%
installation and the system directory in %JDEV_USER_HOME% before reinstalling
JDeveloper and the Oracle Fusion Applications extensions updates.
If you are using Windows XP and encounter issues running Integrated Weblogic
Server, you will need to change to the 64-bit version of Windows 7.
Install the Studio edition of JDeveloper from the top-level directory of the Oracle
JDeveloper 11g and Oracle Application Development Framework 11g (11.1.1.7.1)
disk.
For Windows, you can use the jdevstudio11117install.exe installer. For Linux, you
can use the jdevstudio11117install.bin installer. If you decide to use the generic
jdevstudio11117install.jar installer, you must first install JDK 6 Update 24 from the
Oracle Technical Network and then install JDeveloper using the generic installer.
2-5
The installation will let you specify the directory into which to install JDeveloper.
To avoid possible errors when the installation scripts run, do not include any
spaces in the path. This installation directory is referred to as MW_HOME.
When you have started JDeveloper, you will need to install the extension bundles
from the fusion_apps_extensions directory on the Oracle Fusion Applications
Companion 11g (11.1.1.7.1) disk. See Section 2.2.1.4, "Adding Customization
Extension Bundles to the jdev.conf File" and Section 2.2.1.5, "Setting Up the
JDeveloper-based Development Environment."
For more installation information, see the Oracle Fusion Middleware Installation Guide for
Oracle JDeveloper.
where -Dide.extension.extra.search.path
/path/to/customization/bundles/directory1:/path/to/customization/bundles/d
irectory2 is the fully-qualified path or paths to the directory or directories in which
the JAR files containing the product-specific customization classes are located. Paths
already exist as part of the provisioned environment.
Check your adf-config.xml file to see if you are including any customization
classes other than the ones described in "Personalizations Are Also Handled by the
Customization Engine in MDS" in the Oracle Fusion Applications Extensibility Guide
for Developers and EnterpriseCC, which is deprecated. Those are your
product-specific customization classes.
Example 21 shows customization class entries in the adf-config.xml file.
In Example 21, these two customization classes are outside the list:
<customization-class name="oracle.apps.hcm.common.core.HcmCountryCC"/>
<customization-class name="oracle.apps.hcm.common.core.HcmOrganizationCC"/>
If you do have such product specific customization classes, you must modify your
jdev.conf file to include the JAR files containing such customization classes.
These JAR files have an Ext* prefix and are found under the application's APP_
INF/lib directory.
To find the path to such JAR files, contact your system administrator who can use
these steps to locate APP_INF/lib/Ext*.jar:
Look under APP-INF/lib under the exploded EAR for all JAR files that start
with Ext.
Find the JAR files that contain the product specific customization classes.
These classes can be found in the adf-config file. If the product-specific
customization class cannot be found in any of the JAR files under APP_
INF/lib/Ext*.jar, look at all JAR files under the EarContents.
If you have not already done so, install the 64-bit version of the JDK. See
Section 2.2.1.3, "Installing JDeveloper.".
2.
From a command prompt, run python -V to see if you have Python 2.7.x on your
machine. If you do not, install Python version 2.7.x. To avoid errors, do not install
Python version 3.x.
3.
Note:
csh commands:
setenv PATH /path/to/python/bin:$PATH
setenv HOME /path/to/user_dir (Important: If this variable is not set, the
FADevConfigure.py script, which is called while creating an Oracle Fusion
domain in JDeveloper, will fail.)
setenv MW_HOME /path/to/JDeveloper/installation/directory
setenv JAVA_HOME $MW_HOME/jdk160_24
setenv PATH $JAVA_HOME/bin:$PATH
setenv JDEV_USER_HOME /path/to/a/directory
(Optional) setenv FADEV_VERBOSE true
setenv USER_MEM_ARGS "-Xms256m -Xmx1024m -XX:MaxPermSize=512m
-XX:CompileThreshold=8000"
bash commands:
export PATH=/path/to/python/bin:$PATH
export HOME=/path/to/user_dir (Important: If this variable is not set, the
FADevConfigure.py script, which is called while creating an Oracle Fusion
domain in JDeveloper, will fail.)
export MW_HOME=/path/to/JDeveloper/installation/directory
export JAVA_HOME=$MW_HOME/jdk160_24
export PATH=$JAVA_HOME/bin:$PATH
export JDEV_USER_HOME=/path/to/a/directory
(Optional) export FADEV_VERBOSE=true
export USER_MEM_ARGS="-Xms256m -Xmx1024m -XX:MaxPermSize=512m
2-7
-XX:CompileThreshold=8000"
5.
Open the jdev.conf file in a text editor and add this line:
AddVMOption -Djdev.wlst.env.vars=HOME,JDEV_USER_HOME
VMOptions in jdev.conf
Name
Value
Comments
-Dide.extension.extra.search.path
/x/y/z
-DURLChooser.forceUseList
true
Optional.
-DURLChooser.disableCompletionPopup
true
Optional.
-DUNIX_WEB_BROWSER
/usr/bin/firefox
-Djbo.SecondaryADFLibVisible
true
-Ddeployment.jario.writepolicy
recreate
-Doracle.webcenter.portlet.enableApplicationStriping true
-Doracle.webcenter.portlet.dt.excludeExportSet
true
-Dadflib.project.open.refresh
false
Value
Comments
-Djdev.wlst.env.vars
-XX:MaxPermSize
512M
-Xmx1024M
-Xms256M
-XX:+DisableExplicitGC
6.
Start JDeveloper.
Linux
jdev &
Windows
jdeveloper.exe
If you need more details about the JDeveloper startup, you can use the verbose
command line argument, such as:
jdev -verbose
Because you will need to select a different role later, you should make sure you
select the Always prompt for role selection on startup option.
The JDeveloper environment can be tailored based on the role you select. The
modified environment removes unneeded items from JDeveloper, including
menus, preferences, New Gallery, and even individual fields on dialogs. The
JDeveloper role you select determines which technologies and options are
available to you as you work in JDeveloper.
2-9
JDeveloper Roles
Role
Description
Default Role
This role allows you to access all of JDeveloper's features. The other roles provide
important shaping features that are not included in the Default Role. Some of these
will be available once the Oracle Fusion Applications Extensions have been added to
the IDE.
Oracle Fusion
Applications
Administrator
Customization
This is the main customization role for Oracle Fusion Applications customers.
Important: You must use this Role for customizing SOA Composites.
Oracle Fusion
Applications Developer
This is for Oracle Fusion Applications developers to use to build new applications.
Database Edition
This gives you access to just the core database development tools.
Java EE Edition
Java Edition
Customization Developer
Oracle Fusion
Applications
Customization
Click OK. As JDeveloper loads, the Migrate User Settings prompt may display. If
it does and you are not sure whether to migrate settings, you should click No.
7.
b.
c.
If the Proxy Setup dialog displays, enter the applicable information for your
situation, as shown in Figure 22.
Ignore any error messages that might be displayed when you click the Test
Proxy button.
d.
e.
f.
Click Add to display the Update Center dialog, shown in Figure 24.
g.
Enter a name for the new Update Center, such as Oracle Fusion Applications
Update Center.
h.
i.
Click Open.
j.
Click OK.
k.
l.
Click Next to display the Updates dialog, shown in Figure 27. Note that,
initially, no updates will be selected.
Click Next to display the Download dialog and start the download, as shown
in Figure 28.
When the download finishes, the Summary dialog, similar to that shown in
Figure 29, displays automatically.
o.
Click Finish. If you are using JDeveloper on a Linux system, the Confirm Exit
prompt shown in Figure 210 displays.
p.
8.
Restart JDeveloper, selecting either the Oracle Fusion Applications Developer role or
the Oracle Fusion Applications Administrator Customization role, as shown in
Figure 211. The restart results in installing the extension bundles that were
downloaded.
When JDeveloper is up, the environment should have all the components in the correct
locations. You should be able to create new, or customize existing, Oracle Fusion
applications.
The developers have to provide the connect string and other details of the owsm_
mds schema available in the central IDM or LDAP while creating the properties
file. This requires that an administrator provide the IDM database details. These
are the host, port, userid, password, and SID. Figure 213 shows how the wizard's
Database dialog will be completed.
The administrator will use the Oracle Fusion Applications Repository Creation
Utility to create the MDS schema, described in Section 2.3.1.1, "Creating the
OWSM_MDS Schema," in the database in the shared environment. The schema
name must have a prefix of owsm. This will create a schema named OWSM_MDS.
Developers, then, will not need to do anything else to use the schema.
Note:
The properties that can be captured in the wizard are shown in Table 23. The
properties are defined under section headers that are surrounded by [square brackets],
for example:
[domain]
domainType=adminall
Table 23
Property Name
Standalone/
Integrated
Required
Default
Comments
domainType
Standalone
Yes
standalone
domainName
Standalone
Yes
domainDir
Standalone
Yes
fusion_domain
Standalone/
Integrated
Required
installerLocation
Standalone
Yes
listenPort
Standalone
Yes
soaPort
Standalone
Yes, only
when
domainType
is
adminsoa/ad
minall.
Default
Comments
Location of the Oracle Fusion
Applications installer files. These
usually are located on a central server,
rather than on each developer's system.
Ask your administrator for the
location.
Default based on
Standalone or
Integrated.
Default is 7011
for Standalone
WebLogic
Server.
essPort
Standalone
Yes, only
when
domainType
is adminess.
wlName
Both
Yes
weblogic
wlPassword
Both
Yes
NA
ldapHost
Both
Yes
ldapPort
Both
Yes
Example: 3060
ldapUser
Both
Yes
Example: cn=wlsproxyuser
ldapPass
Both
Yes
Example: welcome1
Both
Yes
Example:
cn=users,dc=us,dc=yourcompany,dc=c
om
ldapGroupDN
Both
Yes
Example:
cn=groups,dc=us,dc=yourcompany,dc=
com
ldapSSLEnabled
Both
No
false
true or false
Standalone/
Integrated
Required
opssHost
Standalone
No
Default
Comments
Optional separate OPSS store. This is a
string value similar to:
opsshostname.yourcompany.com.
For Integrated WebLogic Server, the
DefaultDomain uses the XML-based
Policy Store (such as
system-jazn-data.xml). For
Standalone WebLogic Server, if
undefined, the standalone domain
defaults to the XML-based Policy Store
(such as system-jazn-data.xml).
For information and directions on how
to migrate the OPSS policy store using
the migrateSecurityStore.py OPSS
script, see:
opssPort
Standalone
No
Example: 3061
opssUser
Standalone
No
Example: cn=wlsproxyuser
opssPass
Standalone
No
opssSSLEnabled
Standalone
No
jpsRootContext
Standalone
No
false
true or false
Text field
Example: cn=FADevPolicies
biHostPort
Standalone
No
familyName
Both
Yes
Standalone/
Integrated
Required
Both
Yes
Default
Comments
JDBC connect string.
Note: This is split into sub-fields:
fusionDbUser
fusionDbPassword
fusionDbHost
fusionDbPort
fusionDbSid
activityDb
apmDb
AppMasterDb
essMdsDb
fusionAq
fusionEdn
fusionMds
oraessDb
orasdpmDb
owsmMdsDb
portletDb
soadatasrcDb
soaMdsDb
wcDb
Both
No
apmDbUser - connect
string
Both
No
Both
No
No
Standalone/
Integrated
Both
Required
Yes, but the
database
connection is
the same as
for fusionDb.
Default
Comments
Note: CRM will be replaced with the
familyName that is passed in.
You can connect to the fusionDB
database as crm_fusion_soainfra.
Your system administrator will provide
the connection details and schema
password to be used.
No
Both
No
Both
No
Both
No
Both
No
Both
No
wcDbUser - connect
string
No
Both
Click Yes to launch the wizard and display the Usage page, as shown in Figure 216.
Figure 216 Selecting Domain Usage
Standalone Server
Selecting this option only creates or updates the fusion_apps_wls.properties
and cwallet.sso files. See Section 2.2.2.2, "Completing the Oracle Fusion Domain
Wizard for Standalone Server" for the dialogs that are specific to creating the
fusion_apps_wls.properties file for a Standalone WebLogic Server domain.
Creating a Standalone WebLogic Server domain must be done from the command
line using the fusion_apps_wls.properties file as input. See Section 2.3.3, "How
to Set Up the Personal Environment for Standalone WebLogic Server."
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
Further wizard pages depend on the selected Usage. The flow for the Default
Integrated Server selection is covered first. The flow for the Standalone Server
selection is covered in Section 2.2.2.2, "Completing the Oracle Fusion Domain Wizard
for Standalone Server."
When you select the Default Integrated Server Usage option and click Next, the
Domain dialog, shown in Figure 217, displays.
Figure 217 Configuring the Domain
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
Setting Up Your Development Environment 2-23
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
Notes:
Fusion Database
Enter the host, port, and the SID information using a colon (:) delimiter, such as
a.your.company.com:1234:xyzzyon. You probably will need to get this from an
administrator if the fusion_apps_wls.properties file was not prepared for you.
OWSM_MDS schema in the transaction database, you may not need to enter any
data here. For more information about the owsm_mds schema, see Section 2.3.1.1,
"Creating the OWSM_MDS Schema."
You can change the default values of almost all the credentials, if necessary.
User Name
This field corresponds to the Fusion Database User field.
Password
This field corresponds to the Fusion Database Password field.
Connect String
This field corresponds to the Fusion Database field.
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
LDAP Server
This field cannot be edited directly. Click the edit icon to display the Edit LDAP
Server dialog shown in Figure 220.
Host
Enter the name of your LDAP host, such as ldap_server.your_company.com.
Port
Enter the port number, such as 1066.
Principal
This is the internal LDAP user name by which you connect to LDAP, such as
cn=wlsproxyuser.
Password
Enter the password used by the Principal. The password will be encrypted
and stored in the cwallet.sso file, and not in the fusion_apps_
wls.properties file.
SSL Enabled
This value defaults to LDAP (not checked). Select this check box if you want to
use LDAPS.
User Base DN
Enter the User DN based your LDAP. A sample User DN resembles
cn=users,dc=us,dc=your_company,dc=com.
The DN (Distinguished Name) is the LDAP attribute that uniquely defines an
object. Each DN must have a different name and location from all other objects
in Active Directory.
The components include cn=common name, ou=organizational unit, and
dc=domain content. DC often is listed with two entries, dc=cp and dc=com.
Group Base DN
Enter the Group DN based your LDAP. A sample Group DN resembles
cn=groups,dc=us,dc=your_company,dc=com.
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
Note:
2.2.2.2 Completing the Oracle Fusion Domain Wizard for Standalone Server
When you select the Standalone Server Usage option and click Next, the Domain
dialog, shown in Figure 222, displays.
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
If an administrator has not created the fusion_apps_
wls.properties file for you, with this information, you will need to
get most of this information from an administrator.
Note:
Domain Type
This is the type of domain you wish to create. It can be:
adminessadf: Admin server for Oracle ADF and Oracle Enterprise Scheduler
Service (ESS) managed server.
Domain Name
The name of your domain. If you have more than one domain, you need to change
this value and the domainDir value.
Installer Location
This is the location of the Oracle Fusion Applications installer files, usually on a
central server.
Domain Location
The location in the file system in which the domain will be created.
If it is not specified, it will be created in the default location, which is $MW_
HOME/user_projects/<domain_name>.
This can be changed by setting the domainDir property in the fusion_apps_
wls.properties file. If you have more than one domain, you need to change this
value. See the description of domainName.
Listen Port
Listen Port is the adminserver listen-port you want to use.
SOA Port
This field, which displays only if the Domain Type is adminall or adminsoa, is the
port number for your Oracle SOA Suite managed server (soa_server1) if you are
using Oracle SOA Suite. If you are not using Oracle SOA Suite, you can leave this
blank.
BI Host Port
This is the host:port where the BI Publisher server is running. The format for the
value for this field is hostname:port, such as my.domain.com:9999. You may need
to get this value from your administrator.
The password requires at least one numeral.There is no default, and you must
supply the password. Note that the password is not stored in the fusion_apps_
wls.properties file. It is encrypted and stored in the cwallet.sso file.
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
Notes:
Fusion Database
Enter the host, port, and the SID information using a colon (:) delimiter, such as
a.your.company.com:1234:xyzzyon. You probably will need to get this from an
administrator if the fusion_apps_wls.properties file was not prepared for you.
OWSM_MDS schema in the transaction database, you may not need to enter any
data here. For more information about the owsm_mds schema, see Section 2.3.1.1,
"Creating the OWSM_MDS Schema."
You can change the default values of almost all the credentials, if necessary.
User Name
This field corresponds to the Fusion Database User field.
Password
This field corresponds to the Fusion Database Password field.
Connect String
This field corresponds to the Fusion Database field.
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
If the fusion_apps_wls.properties file already exists and is in place, the fields will
show the values that are in the file.
LDAP Server
This field cannot be edited directly. Click the edit icon to display the Edit LDAP
Server dialog shown in Figure 225.
Host
Enter the name of your LDAP host, such as ldap_server.your_company.com.
Port
Enter the port number, such as 1066.
Principal
This is the internal LDAP user name by which you connect to LDAP, such as
cn=wlsproxyuser.
Password
Enter the password used by the Principal. The password will be encrypted
and stored in the cwallet.sso file, and not in the fusion_apps_
wls.properties file.
SSL Enabled
This value defaults to LDAP (not checked). Select this check box if you want to
use LDAPS.
User Base DN
Enter the User DN based your LDAP. A sample User DN resembles
cn=users,dc=us,dc=your_company,dc=com.
The DN (Distinguished Name) is the LDAP attribute that uniquely defines an
object. Each DN must have a different name and location from all other objects
in Active Directory.
The components include cn=common name, ou=organizational unit, and
dc=domain content. DC often is listed with two entries, dc=cp and dc=com.
Group Base DN
Enter the Group DN based your LDAP. A sample Group DN resembles
cn=groups,dc=us,dc=your_company,dc=com.
OPSS Server
Defining the Oracle Platform Security Services (OPSS) Server is optional. Define
this if its policy store is in a different location than your LDAP policy store. If
OPSS-related properties are not specified, the domain is configured to use the
XML-based Policy Store, such as system-jazn-data.xml.
For information and directions on how to migrate the OPSS policy store using the
migrateSecurityStore.py OPSS script, see:
"Migrating the OPSS Security Store" and "Migrating with the Script
migrateSecurityStore" in the Oracle Fusion Middleware Application Security
Guide.
"Extracting Data from an OID Store to a File" in the Oracle Fusion Applications
Administrator's Guide.
Host
Enter the name of your LDAP host, such as ldap_server.your_company.com.
Port
Enter the port number, such as 1066.
Principal
This is the internal LDAP user name by which you connect to LDAP, such as
cn=wlsproxyuser1.
Password
Enter the password used by the Principal. The password will be encrypted
and stored in the cwallet.sso file, and not in the fusion_apps_
wls.properties file.
SSL Enabled
This value defaults to not enabled. Select this check box if you want to enable
SSL.
Messages
A message is displayed in this field if any errors occur in the definition. These
errors must be corrected before you continue.
Right-click and run a page from a project. If the server is not running, it will be
started.
From the JDeveloper main menu, select Run > Start Server Instance, as shown in
Figure 228.
If you select the connection option, the application will be undeployed and the server
will remain running.
If you select the IntegratedWebLogicServer option, the deployed application will be
undeployed and the server shut down. Wait for the application to be undeployed and
the server to stop.
If the shutdown of Integrated WebLogic Server did not respond or shut down the
server, click the red shutdown button again to kill the process, as shown in
Figure 230.
Figure 230 Forcing Shutdown of Integrated WebLogic Server
If you still do not see the Process Exited message when you terminate Integrated
WebLogic Server, you will have to manually kill the process.
Manually killing the process
1. From a terminal window, execute this command.
/usr/sbin/lsof -i -P | grep 7101
Note:
2.
Kill the process. For instance, if the process is 15846, you would execute this
command:
kill -9 15846
To configure the datasource, you need to know the schema password. If the
administrator allows all developers to know the schema password for this MDS
schema, then a new MDS schema does not need to be created.
If the schema password is locked down, then follow the steps in this section to
create a new MDS schema for OWSM use. See Section 2.3.1.1, "Creating the
OWSM_MDS Schema."
If you have a local database, you probably will want to create the schema in the
local database.
Copy the appropriate ZIP file to your system from the installers/apps_rcu directory.
When you get the ZIP file to your machine, follow these steps:
Linux system
%
%
%
%
%
%
mkdir fa_rcu
cd fa_rcu
cp /from_zip_file_location/rcuHome_fusionapps_linux.zip .
unzip rcuHome_fusionapps_linux.zip
cd bin
./rcu
Windows system
md fa_rcu
cd fa_rcu
copy \from_zip_file_location\rcuHome_fusionapps_win.zip .
unzip rcuHome_fusionapps_win.zip
\path_to_rcu_utility\rcu
The Oracle Fusion Applications Repository Creation Utility starts and displays the
Create Repository dialog, shown in Figure 231.
Select Create and click Next to display the Database Connection Details dialog, shown
in Figure 232.
Enter your database connection details and click Next to display the Checking Global
Prerequisites dialog, shown in Figure 233.
Figure 233 Checking Global Prerequisites
Select Use same passwords for all schemas and enter the password for the OWSM_
MDS schema in the Password and Confirm Password fields.
Click Next to display the Map Tablespaces dialog, shown in Figure 237.
Click Close.
The OWSM_MDS schema now can be used to configure the mds_owsm datasource in
the domain.
Note:
Drop the Repository, as shown in Example 23. Enter the SYS password when
prompted.
If the -silent switch is omitted, a wizard will be launched. It will ask you to
enter the same values as shown in Example 22.
3.
Recreate the Repository, as shown in Example 24. Enter the SYS password when
prompted.
You will need to supply passwords for the different users. You
should make the username and the password for that user the same,
such as jmaus/jmaus. You will have to remember all the passwords.
You will need them when you configure the DataSources.
Note:
2.3.3 How to Set Up the Personal Environment for Standalone WebLogic Server
Following the steps in this section will give you a portable working environment
without needing access to the full environment until you are ready to deploy and unit
test.
While the JDeveloper-based environment with Integrated WebLogic Server is useful in
creating and validating customizations to the Oracle ADF artifacts, it cannot be used to
validate SOA customizations. Anything that relies upon SOA infrastructure for
development (such as BPM and ESS) will need the standalone environment in the
following situations:
To create this environment, you run Python scripts that are part of the
JDeveloper-based environment and the repository of installer files that are used to
create the shared environment. You first will have to create the JDeveloper-based
environment, create or update the fusion_apps_wls.properties file, and then execute
the scripts that are packaged with the fa_dev_bundle.zip extension bundle to create
the standalone environment. One of the inputs to the Python script is the location of
the repository that contains the installer files. You can use the Oracle Fusion Domain
wizard from the JDeveloper-based environment to update the fusion_apps_
wls.properties file such that it can be used in the standalone environment. So, the
same properties file can be used to create both the JDeveloper-based environment and
the standalone environment.
When the Python scripts are executed, they automatically do the following:
Typically in this environment, you have to deploy the exploded EAR directory of the
application from the Middleware home of the shared environment using the WebLogic
Server Console. Consequently, the adf-config.xml descriptor contains an MDS
metadata store that points to the database in the shared environment and the
customizations are picked up from the MDS repository. If you have created
customizations on the filesystem using the JDeveloper-based environment, you should
import those customizations to the MDS schema in the database that is running as part
of the shared environment to test and validate them. When you import the
customizations to the repository and database in the shared environment, it will affect
all the developers who are using the shared environment. You will be able to test and
validate the customizations by exercising all the applications that have a touch-point
with the customized application, to ensure that things outside the application are
working as expected.
Because Standalone WebLogic Server for SOA points to a separate SOAINFRA MDS
schema, the customizations need to be exported and imported into the shared
environment when they are successfully tested by developers.
See "Managing the Metadata Repository" in the Oracle Fusion Middleware
Administrator's Guide.
Even though the Standalone WebLogic Server domain that is created as part of this
environment is used to deploy the application from the same APPL_TOP and is
configured to point to the same data sources, the Identity Store, and the Policy Store,
as the domains that are part of the shared environment, you have the flexibility in
setting up the domain that is part of the standalone environment in a way that it can
work on a laptop or desktop without requiring excess resources. The domains that are
created in the shared environment by the provisioning processes have one
AdminServer and three ManagedServers. But, the domain in the standalone
environment has just one AdminServer and one ManagedServer. You can decide
whether to target SOA or ESS or various technologies at the ManagedServer based on
the project.
This install also allows Oracle SOA Suite developers to create their domains without
extra installs or steps.
2.3.3.1.1 How to Create a Special SOAINFRA Schema If you are creating a SOA
customization, a special SOAINFRA schema that is in the database in the shared
environment may need to be created so your work does not interfere with the normal
database.
Important: You must use the Oracle Fusion Applications Administrator Customization
role for customizing SOA Composites.
Because the existing composites reference Web Service Description Language (WSDL)
and schemas in MDS, when new SOAINFRA and MDS_SOA schemas are created for
the standalone environment, all the WSDLs and schemas needed by the composites to
be customized need to be exported from the shared MDS_SOA and imported into the
new standalone MDS_SOA schema.
See "Managing the Metadata Repository" in the Oracle Fusion Middleware
Administrator's Guide.
2.3.3.1.2 How to Set Up the Environment for Standalone WebLogic Server Follow these steps
to create a Standalone WebLogic Server environment. These steps assume that you
already have downloaded and installed JDeveloper and the Fusion Apps
Development Environment extension bundle.
1.
If you have not already done so, download and install the 64-bit JDK, preferably
not to a directory location containing spaces, such as \Program Files.
When installing JDeveloper, you will select the 64-bit JDK location you just
installed.
If a 32-bit JDK already was installed and used, you must delete the old %MW_HOME%
installation and the system directory in %JDEV_USER_HOME% before reinstalling
JDeveloper and the Oracle Fusion Applications extensions updates.
If you are using Windows XP and encounter issues running Integrated Weblogic
Server, you will need to change to the 64-bit version of Windows 7.
2.
You will need installer files from the provisioned environment. The site
administrator should make the installer files available. When the system
administrator downloaded the Oracle Fusion Applications DVDs and unzipped
them, the installer files were placed in the installers directory that now contains
numerous sub-directories. A directory listing looks similar to Figure 241.
If you are not able to access a provisioned environment on a server, you will need
to copy these directories (defined in the FADevInstallMwHome.py script file) and
their contents from the installation disk to the installerLocation described in
Table 23. (If you do not have the disk, you will need to download the entire 60GB
Oracle Fusion Applications package from eDelivery.)
atgpf
biappsshiphome
odi
soa
wc
weblogic
jdk
This subset of the entire installation package is approximately 20GB in size, with
biappsshiphome using approximately 10GB.
Important: The installers directory is platform-specific. So if your
production environment is Linux and you want to install Standalone
WebLogic Server on a Windows machine, you will need to get the
subset of installers from a Windows Oracle Fusion Applications
download.
3.
Update the properties file that was created for Integrated WebLogic Server so that
it can be used to create Standalone WebLogic Server:
Select the Standalone Server option on the wizard's Usage dialog. Selecting
this option creates or updates the fusion_apps_wls.properties and
cwallet.sso files.
On the Domain dialog, set Installer Location to the directory that the
administrator has provided. See Step 2.
Set Domain Location appropriately, such as /path_to_
domain/FAStandaloneDomain. Make sure that the directory name you enter
does not exist.
4.
MW_HOME /path_to/FAStandalone_MW_HOME
JDEV_MW_HOME /path/to/JDeveloper/install_directory
ANT_HOME $JDEV_MW_HOME/jdeveloper/ant
JAVA_HOME /path/to/JDK/installation/directory
bash commands:
export
export
export
export
MW_HOME=/path_to/FAStandalone_MW_HOME.
JDEV_MW_HOME=/path/to/JDeveloper/install_directory
ANT_HOME=$JDEV_MW_HOME/jdeveloper/ant
JAVA_HOME=/path/to/installed/JDK
MW_HOME=\path_to\FAStandalone_MW_HOME
JDEV_MW_HOME=\path\to\JDeveloper\install_directory
ANT_HOME=%JDEV_MW_HOME%\jdeveloper\ant
JAVA_HOME=C:\JDK_install_directory
mkdir /path_to/FAStandaloneWork
chmod +x $JDEV_MW_HOME/jdeveloper/fadev/bin/*.py
options are:
: MW_HOME (standalone - will be created if it does not exist)
: Installer location (the provisioning repository)
: Working/staging directory. Used for response files, unzip installers
Defaults to the current directory
-r : reinstall MW_HOME
-v : verbose
5.
setenv
setenv
setenv
setenv
setenv
ORACLE_HOME $MW_HOME/atgpf
ATGPF_ORACLE_HOME $ORACLE_HOME
JHOME $MW_HOME/jdk6 [Note: Must be a 64-bit JDK.]
INV_LOC $ORACLE_HOME/oraInst.loc
PATH $ORACLE_HOME/OPatch:$PATH
Windows system
c:\>
c:\>
c:\>
c:\>
set
set
set
set
ORACLE_HOME=%MW_HOME%\atgpf
ATGPF_ORACLE_HOME=%ORACLE_HOME%
JHOME=%MW_HOME%\jdk6 [Note: Must be a 64-bit JDK.]
PATH=%ORACLE_HOME%\OPatch;%PATH%
Create, extend and configure the Standalone WebLogic Server domain by running
the FADevCreateDomain.py script. Note that the options have been placed on
separate lines for clarity. When you run the script, all must be on the same line.
$JDEV_MW_HOME/jdeveloper/fadev/bin/FADevCreateDomain.py
-m $MW_HOME
-p $JDEV_MW_
HOME/jdeveloper/system11.1.1.7.xx.yy.zz/o.jdevimpl.rescat2/fusion_apps_
wls.properties
-i /path/to/installer_files
-w /path_to/FAStandaloneWork -v
FADevCreateDomain.py options
If you execute FADevCreateDomain.py -help, the help shown in Example 26 will be
displayed.
Example 26 FADevCreateDomain.py Options
-p : property file
-m : MW_HOME (standalone - will be created if does not exist)
-i : installer location (Provisioning repository)
overrides installerLocation in the properties file
-w : working/staging directory for log and other temp files
-v : verbose
-w: Set the working/staging directory for log and other temporary files.
2.3.3.1.3 How to Fix Domain Creation Errors These three causes of a domain creation error
are easily corrected:
'oracle.appltest.diagfwk.executor':14,
'oracle.appstrace.model':2,
'oracle.appstrace.webapp':2,
'oracle.bi.adf.model.slib':15,
#
#
#
#
ess-soa-adf
WORKAROUND
WORKAROUND
ess-soa-adf-admin
2.3.3.1.4
Once started, it can be accessed from a web browser, using a URL similar to:
http://1.23.45.678:7011/console
2.3.3.1.5 How to Manage the Standalone WebLogic Server Lifecycle There will be times
when you want to change the properties in fusion_apps_wls.properties, or point to
a different Identity Store, or you may want to delete the domain and start from scratch.
To do these, you will have to stop the running server, remove the domain directory,
edit the properties file using the wizard, and recreate the domain. Follow these steps to
accomplish the tasks. Remember to change any example directory names to the names
you have used.
If you had started the ManagedServer, you should kill it, too.
Configuring Oracle SOA Suite and Oracle Enterprise Manager Fusion Middleware Control
Manually launch the Oracle Fusion Domain wizard. See Section 2.2.2, "How to
Use the Oracle Fusion Domain Wizard."
Right-click the Integrated Servers node and select the Configure Fusion
Domain... option.
Select the Standalone Server option from the first wizard dialog.
2.4 Configuring Oracle SOA Suite and Oracle Enterprise Manager Fusion
Middleware Control
This section discusses configuration options for the Oracle Service Oriented
Architecture Suite and Oracle Enterprise Manager Fusion Middleware Control servers.
Note:
Set up your environment to use the Oracle SOA Suite and Java Apps Logger.
2.
cd soa-infra-wls
#add library reference
unzip -o ../soa-infra-wls.ear META-INF/weblogic-application.xml
mv META-INF/weblogic-application.xml META-INF/weblogic-application.xml.orig
sed '/<\/weblogic-application>/i<library-ref>\n
<library-name>oracle.applcore.model</library-name>\n</library-ref>\n<library-ref>\
n <library-name>Diagnostics-Engine</library-name>\n</library-ref>'
META-INF/weblogic-application.xml.orig > META-INF/weblogic-application.xml
rm META-INF/weblogic-application.xml.orig
zip -f ../soa-infra-wls.ear META-INF/weblogic-application.xml
#add resource reference
unzip -o ../soa-infra-wls.ear ejb_ob_engine_wls.jar
unzip -o ejb_ob_engine_wls.jar META-INF/ejb-jar.xml
mv META-INF/ejb-jar.xml META-INF/ejb-jar.xml.orig
sed '/<ejb-name>BPELEngineBean<\/ejb-name>/a\ <resource-ref>\n
<res-ref-name>jdbc/ApplicationDBDS</res-ref-name>\n
<res-type>javax.sql.DataSource</res-type>\n <res-auth>Container</res-auth>\n
</resource-ref>' META-INF/ejb-jar.xml.orig > META-INF/ejb-jar.xml
zip -f ejb_ob_engine_wls.jar META-INF/ejb-jar.xml
zip -f ../soa-infra-wls.ear META-INF/weblogic-application.xml
popd
4.
connections that HCM needs, and all of the connections from the Financials
workspace. If the defaults are retained, all of HCM's projects contain connection
information from Financials plus HCM. If CRM picks up any of those HCM Oracle
ADF libraries, it merges the connection information into the CRM workspace; which
now contains all of Financials plus HCM plus CRM.
Cleanup
Developers should audit the current deployment profiles for all of Oracle Fusion
applications to make sure they are not including all of the connection information.
Developers need to make sure their deployment profiles only include the connections
that are truly needed directly by that project.
Developers also need to remove any unnecessary connections from the
connections.xml files from each workspace. The connections.xml file should be a
superset of all of these connections and not include unnecessary connections.
Essbase
Portlet producers
In the Edit ADF Library JAR Deployment Profile Properties dialog, choose to include
Connection Name Only, as shown in Figure 242
Figure 242 Editing a Deployment Profile
Important:
domainType=adminessadf
domainName=fusion_domain
listenPort=7011
soaPort=7012
wlName=weblogic
wlPassword=password
...
[wlsconfig]
fusionDbHost=host.example.com
fusionDbPort=1522
fusionDbSid=fusiondbsid
...
# leave oraessDbHost, oraessDbPort, oraessDbSid blank if using fusion database
oraessDbHost=
oraessDbPort=
oraessDbSid=
oraessDbUser=oraess_dbuser
oraessDbPassword=password
#
essMdsDbHost=
essMdsDbPort=
essMdsDbSid=
essMdsDbUser=fusion_mds_ess
essMdsDbPassword=password
After provisioning the runtime, you should create the supporting database schema
before starting the managed servers which is covered in Section 2.6.2, "How to Create
Supporting Database Schema."
Note:
Example 212
cd $MW_HOME/rcu/rcu/integration/ess/sql
sqlplus sys/manager as sysdba;
@createuser_ess_oracle.sql oraess_d8b2 oraess_d8b2 SYSTEM TEMP;
connect oraess_d8b2/oraess_d8b2
@createschema_ess_oracle.sql oraess_d8b2
3.
Click Next to access the Name Your ADF-Model Project dialog. See Figure 244.
The system automatically will create data model and user
interface projects for you. The default names for these projects that
JDeveloper provides are Model and ViewController
Note:
You can enter a new name for your data model project or you can keep the default
name Model.
Note:
4.
Click Next to access the Configure Java Settings for the ADF-Model dialog.
This dialog displays the Java settings for your data model project. See Figure 245.
5.
Click Next to access the Name Your ADF ViewController Project dialog.
You can enter a new name for your user interface project or you can keep the
default name ViewController. See Figure 246.
Figure 246 Naming Your Oracle ADF User Interface Project
Click Next to access the Configure Java Settings for the ViewC... dialog.
This dialog displays the Java settings for your user interface project. See
Figure 247.
Figure 247 Configuring Java Settings for the Oracle ADF User Interface Project
Add the Applications Core, Applications Core (Attachments Model), Topology Manager,
Functional Setup Model, BC4J Service Runtime, and Java EE 1.5 libraries to the data
model project. See Section 3.3, "Adding Necessary Libraries to Your Data Model
Project."
8.
Add the Applications Core (ViewController) tag library to the user interface project.
See Section 3.4, "Adding the Applications Core Tag Library to Your User Interface
Project."
9.
Select Run/Debug/Profile.
Click OK.
Click OK.
Applications Core library is attached to the model project. However, you will need
to adjust the values that are defined in the connection to reflect the database you
want to use. See Section 3.6, "Creating or Updating a Database Connection." For
this example, enter these connection details:
Connection Type: Choose Oracle (JDBC)
Username / Password: Enter the username and password for your team's Fusion_
Runtime database schema.
Deploy Password: Select this option.
Host Name: Enter the host name, such as my.host.com
JDBC Port: Enter the port number for your database.
SID: Enter the database name, such as mydb.
11. Choose Application Navigator > Model. Right-click and choose New from the
Filter Types: Select only Tables to narrow your search for schema objects.
b.
Filter Name: Enter a filter, such as %LOOK% to narrow your search to tables.
c.
Note:
d.
Choose the required object, such as FND_LOOKUPS and click > to shuttle it
over to the Selected column.
e.
14. Choose the required entity object located in the Available column and click > to
15. Click Finish to create your updateable view object and to close the Business
Objects wizard.
16. Ensure that your application module configuration is using JDBC data source.
This is required for your application module to run on the WebLogic Server.
To update your application module configuration:
a.
b.
c.
17. Validate your model with the Business Component Tester to make sure that the
ApplicationDBDS data source has been configured for the Integrated WebLogic
Server environment.
In the Navigator tree, right-click the application module and select Run, as shown
in Figure 251.
If your installation is set up correctly, a dialog similar to that shown in Figure 252
displays. If an error message displays, you will need to re-check that the previous
steps have been performed correctly.
Figure 252 Application Module in Business Component Browser
18. Choose Application Navigator > ViewController. Right-click and select New
Click OK.
21. Go to the Data Controls panel and drag the collection onto the open Setup.jspx
22. Select to create Forms > ADF read-only from the context menu that displays. See
Figure 255.
Figure 255 Context Menu
23. Remove some of the rows that are displayed in the opened dialog so that your
page only lists a few fields. Select the Include Navigation Controls checkbox and
click OK. See Figure 256.
24. Click the Run button located on the toolbar to run your page.
Make sure the URL uses the full host name. For instance, if the
displayed URL is
http://127.0.0.1:7101/ApplCoreCRMDemo/faces/Region6UIShellPa
ge, you should edit it manually so it appears similar to
http://myhost.name.com:7101/ApplCoreCRMDemo/faces/Region6UIS
hellPage.
Note:
When your page is displayed, you can use the buttons that appear at the bottom of
your page to view next and previous employees.
jdev: The default non-verbose mode limits the amount of information displayed to
the console. This helps you focus on the important information being displayed.
jdev -v: The verbose mode displays all the information to your console. Although
this information is not useful for everyday workflow, when something goes
wrong, more information can help you debug your problem.
Increase the minimum / maximum heap size for JDeveloper (and other Java
parameters)
This is specifically about increasing the heap size for JDeveloper, since JDeveloper
itself is a Java executable and runs in its own Java Virtual Machine (JVM). This will not
affect Integrated WebLogic Server; for that you set USER_MEM_ARGS, since it's a
separate process and therefore a separate JVM.
To change the values for minimum and maximum Java heap, modify the
corresponding parameters in $jdev_install/ide/bin/ide.conf.
Other parameters can be set in $jdev_install/jdev/bin/jdev.conf.
Do not set Xms or Xmx in the jdev.conf file because it will just result in duplicating
the parameter on the command line because it already is set in the ide.conf file. You
can add any other parameter than is not already passed on the command line in this
file, using the same format as the existing parameters.
Enable the JDeveloper Java heap meter
You can enable the JDeveloper heap monitor (that is, the heap, permgen, and dustbin
icon that forces garbage collection on the status bar of the main jdev window). Add
this line to the $jdev_install/jdev/bin/jdev.conf file.
AddVMOption -DMainWindow.MemoryMonitorOn=true
The heap monitor shows the current size of the heap; not necessarily the maximum
size. The heap is created at the specified minimum size. When additional space is
required, and if garbage collection cannot free up enough space, the heap size is
increased. If the heap reaches its maximum and there still is not enough space after
garbage collection, an OutOfMemoryException is thrown.
There is a new library file per project in the project directory. This file will only
exist if the project has unresolved deployment dependencies required by the
directly-imported Oracle ADF JAR files in the project.
The file should be added to the project source-controlled file set.
The file should be included in all transactions where it was updated during the
design time.
If a runtime exception, such as No Def Found or No Class Def Found occurs, the
project menu command to refresh the Oracle ADF Library Dependencies is
necessary to update the file. This could happen because of updated lower-level
dependency changes outside of the design time session.
Remember that overriding the Java memory arguments is a balancing act, and if you
set them too high for your machine resources, either JDeveloper or WebLogic Server
may fail to start, may hang, or may fail with a resource-related exception. For example,
setting XX:MaxPermSize=1024m may be too high. If you experience problems after
increasing the permanent generation size, try unsetting $USER_MEM_ARGS to see if
it could be the cause. Session servers and workstations may respond differently.
Example exceptions
java.lang.OutOfMemoryError: PermGen space
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(ClassLoader.java:621)
at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:124)
at
weblogic.utils.classloaders.GenericClassLoader.defineClass(GenericClassLoader.java
:344)
Truncated. see log file for complete stacktrace
If you have another instance of WebLogic Server running, and the port is already in
use, JDeveloper will use another port. Also, you may have changed the port in
fusion_apps_wls.properties.
This command lists the Java processes with the full command line, which should help
you to identify the WebLogic Server process.
$ ps -elf | grep java | grep <userid>
1.
Run the wlst.sh command from the current working directory and answer the
prompts.
wls:/offline> connect()
Connecting to
t3://localhost:7101 with userid weblogic ...
2.
Run these WLST commands (exactly as they are here) to create credentials within
the domain's credential store.
wls:/DefaultDomain/serverConfig> updateCred(map="oracle.wsm.security",
key="keystore-csf-key", user="owsm", password="password", desc="Keystore key")
wls:/DefaultDomain/serverConfig> updateCred(map="oracle.wsm.security",
key="enc-csf-key", user="orakey", password="password", desc="Encryption key")
wls:/DefaultDomain/serverConfig> updateCred(map="oracle.wsm.security",
key="sign-csf-key", user="orakey", password="password", desc="Signing key")
wls:/DefaultDomain/serverConfig> updateCred(map="oracle.wsm.security",
key="basic.credentials",user="weblogic",password="password",desc="User
credentials key")
wls:/fusion_domain/serverConfig> createCred(map="oracle.wsm.security", key="
FUSION_APPS_AMX_APPID-KEY ", user="FUSION_APPS_AMX_APPID", password="password",
desc="User credentials key")
userID
assignmentID
Note:
The sample Identity Service Configuration XML code shown in Example 213 specifies
a service extension, HCMIdentityServiceExtention, for JpsProvider. It then specifies
the providers in the service extension.
Note: Within each provider, the attribute classname points to a Java
implementation of the service provider. The parameter wsdlURL points
to the URL of the concrete Web Service Description Language (WSDL)
for the provider's web service. You should replace this value with the
actual URL.
Example 213
<serviceExtensions>
<serviceExtension name="HCMIdentityServiceExtension">
<serviceProvider type="supervisoryHierarchyProvider"
classname="oracle.bpel.services.identity.hierarchy.providers.hcm.HCMHierarchyProvider">
<initializationParameter name="wsdlUrl" value="HierarchyProviderService?WSDL"/>
<!-- Optional parameters. Depicts how the defaults could be overridden to specify
different values -->
<initializationParameter name="policyFile" value="file://hcm-client-policy.xml"/> <!-using different owsm policy, see below for sample policy file -->
<initializationParameter name="csf-key-name" value="hcm-csf-key-other"/> <!-- using
different name for the csf-key-->
<initializationParameter name="http-read-timeout" value="6000"/> <!-- Use this value to
specify HTTP read timeout in miliseconds, default is 5000 milisec-->
<!-- securityPolicyName controls the local policy attachment to use. This value is used
along with csf-key-name to use elevated privileges See Bug 10368000 for more information-->
<initializationParameter name="securityPolicyName" value="oracle/wss10_saml_token_client_
policy"/>
</serviceProvider>
<serviceProvider type="positionHierarchyProvider"
classname="oracle.bpel.services.identity.hierarchy.providers.hcm.HCMPositionHierarchyProvider">
<initializationParameter name="wsdlUrl"
value="http://<host>/HierarchyProviderService?WSDL"/>
</serviceProvider>
<serviceProvider type="positionLookupProvider"
classname="oracle.bpel.services.identity.position.provider.hcm.PositionLookupServiceProvider">
<initializationParameter name="wsdlUrl"
value="http://f<host>/positionLookupService?WSDL"/>
</serviceProvider>
<serviceProvider type="positionDisplayNameProvider"
classname="oracle.bpel.services.identity.position.provider.hcm.PositionDisplayNameProvider">
<initializationParameter name="wsdlUrl"
value="http://<host>/HierarchyProviderService?WSDL"/>
</serviceProvider>
<serviceProvider type="jobLevelHierarchyProvider"
classname="oracle.bpel.services.identity.hierarchy.providers.hcm.HCMHierarchyProvider">
<initializationParameter name="wsdlUrl"
value="http://<host>/HierarchyProviderService?WSDL"/>
</serviceProvider>
</serviceExtension>
</serviceExtensions>
</ISConfiguration>
3
Setting Up Your JDeveloper Application
Workspace and Projects
This chapter describes how to set up your JDeveloper application workspace and
projects, add libraries to projects, integrate Oracle Fusion Middleware extensions,
create a database connection, implement Oracle Enterprise Crawl and Search (ECSF),
and deploy Oracle SOA Suite.
Whenever you create new projects, you must first create an application using the
Fusion Web Application (Oracle ADF) template. The system will then automatically
create the data model and user interface projects for you. The default names that
JDeveloper provides for these projects are Model and ViewController.
After your projects have been created, you must manually add the Applications Core
library to the data model project and the Applications Core Tag library to the user
interface project.
This chapter discusses:
Section 3.4, "Adding the Applications Core Tag Library to Your User Interface
Project"
Section 3.5, "Integrating Oracle Fusion Middleware Extensions for Applications
(Applications Core) Setup UIs"
Section 3.6, "Creating or Updating a Database Connection"
Section 3.7, "Adding the Search Navigation Tab to the Overview Editor for Oracle
Enterprise Crawl and Search Framework (ECSF)"
1.
2.
Choose the Libraries and Classpath category. Click Add Library to open the Add
Library dialog.
3.
Adding the Applications Core Tag Library to Your User Interface Project
4.
3.4 Adding the Applications Core Tag Library to Your User Interface
Project
Use these directions to add the Applications Core Tag Library to the user interface
project. The default name provided by JDeveloper for this project is ViewController.
To add the Applications Core Tag library to the user interface project:
1. Choose Application Navigator > ViewController project. Right-click and choose
Project Properties from the menu.
2.
Choose the JSP Tag Libraries category. Go to the Distributed libraries folder and
click Add to open the Add Library dialog.
3.
Select the Applications Core (ViewController) 11.1.1.0.0 tag library from the list of
available libraries. Click OK to save your selection and close the Add Library
dialog.
The Applications Core (ViewController) 11.1.1.0.0 is now displayed under the
Distributed libraries folder on the JSP Tag Libraries dialog, as shown in
Figure 32.
Integrating Oracle Fusion Middleware Extensions for Applications (Applications Core) Setup UIs
4.
5.
Note:
6.
Click OK to save your changes and close the Project Properties dialog.
3.5.1 What You May Need to Know About Setup UIs in Oracle Fusion Functional Setup
Manager
Every Oracle Fusion application registers ADF task flows with the Functional Setup
Manager, which provides a single, unified user interface that allows implementers and
administrators to configure all applications by creating set up data.
Integrating Oracle Fusion Middleware Extensions for Applications (Applications Core) Setup UIs
For example, a Human Resources application can register setup activities such as
"Create Employees" and "Manage Employee Tree Structure." See the Oracle Fusion
Functional Setup Manager User's Guide.
To make these task flows available to developers, implementers or administrators, a
developer integrates the desired Applications Core setup UI task flows with
Functional Setup Manager. For information about specific task flows, see:
Section 7.11, "Integrating Messages Task Flows into Oracle Fusion Functional
Setup Manager"
Section 8.3, "Integrating SetID Task Flows into Oracle Fusion Functional Setup
Manager"
Section 10.6, "Integrating Lookups Task Flows into Oracle Fusion Functional Setup
Manager"
Section 11.8, "Integrating Document Sequence Task Flows into Oracle Fusion
Functional Setup Manager"
Section 19.9, "Integrating Attachments Task Flows into Oracle Fusion Functional
Setup Manager"
Section 27.8, "Integrating Flexfield Task Flows into Oracle Fusion Functional Setup
Manager"
Section 56.2, "Integrating Profiles Task Flows into Oracle Fusion Functional Setup
Manager"
The most common use of setup UIs is through Oracle Fusion Functional Setup
Manager tasks. This is true even for product-specific tasks that invoke the task flows
with parameters that restrict the results to a single object or set of objects.
Scenario 1 is a generic setup task that invokes a setup task flow running in the
Applications Core Setup Java EE application. For example, you want to give your
product administrator roles access to the generic Manage Descriptive Flexfields
setup task.
Scenario 2 is a product team-specific setup task that invokes a setup task flow
running in the Applications Core Setup Java EE application and passes in
product-specific parameters to restrict the objects to only those relevant to this
specific task. For example, you want to give your product administrator roles
access to a Manage GL Descriptive Flexfields setup task that launches the Manage
Descriptive Flexfields setup UI for descriptive flexfields belonging to the GL
module only.
Scenario 3 is a product team-specific setup task that invokes a setup task flow
running in the product team's own Java EE application. This scenario is for
approved exceptions only. For example, you plan to embed the setup UI within
another UI in your own product team's Java EE application. For instance, the
Manage Item Categories UI in Product Information Management (PIM) embeds
the Manage Extensible Flexfields setup UI.
Follow the instructions in Table 31 that are relevant to your scenario to integrate
Applications Core setup UIs into Functional Setup Manager.
Table 31
Step
Product teams should set the value of the Enterprise Application field (in
the Application Design Repository) to the appropriate Java EE application
for any of their product-specific Functional Setup Manager tasks that use
Applications Core setup task flows. Typically, this should be set to the
Applications Core Setup Java EE application.
Ensure product team roles inherit the appropriate Applications Core duty X
role. The duty roles support securing the setup tasks so only authorized
users have access.
For any of the duty roles and their associated privileges that your
application inherits, include permissions for those privileges in your
application's jazn-data.xml file. Permissions make it possible to grant
authorized users access to your setup tasks.
Add or update the following connection details for the ApplicationDB connection
name as shown in Figure 33.
Connection Name: The value for the connection name must be ApplicationDB.
Connection Type: Choose Oracle (JDBC).
Username and Password: Enter the database username and password.
Deploy Password: Select this checkbox.
Host Name: This is the default host name if the database is on the same machine
as JDeveloper. If the database is on another machine, type the name (or IP address)
of the computer where the database is located.
JDBC Port: This is the default value for the port used to access the database. If you
do not know this value, check with your database administrator.
SID: This is the default value for the SID that is used to connect to the database. If
you do not know this value, check with your database administrator.
3.
Click Test Connection. (Database listener Port). If the database is available and the
connection details are correct, the message Success! is displayed. If not, review and
correct the information that you entered.
4.
Click OK. The connection now appears below the Application Resources
Connections folder as shown in Figure 34.
Adding the Search Navigation Tab to the Overview Editor for Oracle Enterprise Crawl and Search Framework (ECSF)
3.7 Adding the Search Navigation Tab to the Overview Editor for Oracle
Enterprise Crawl and Search Framework (ECSF)
ECSF provides developers a set of tools and a framework to quickly and efficiently
integrate Oracle Secure Enterprise Search (SES) into enterprise applications to expose
business objects for full text search.
For more information about ECSF, see Part V, "Using Oracle Enterprise Crawl and
Search Framework"
Developers use ECSF to integrate search functionality in Oracle Fusion applications by
defining searchable objects and searchable attributes. Defining searchable objects and
searchable attributes enables the corresponding view objects and view object attributes
for search, and creates the necessary metadata for ECSF. However, before you can
define searchable objects and searchable attributes, you must add the Search
navigation tab to the overview editor in JDeveloper.
For more information about defining searchable objects, see Chapter 29, "Creating
Searchable Objects."
3.7.1 How to Add the Search Navigation Tab to the Overview Editor
To add the Search navigation tab to the overview editor in JDeveloper, download the
JDeveloper extension for ECSF.
To download the JDeveloper extension for ECSF:
1.
Launch JDeveloper.
If you have trouble initializing Java Virtual Machine (JVM),
launch JDeveloper by entering jdeveloper.exe -J-Xmx125m at a
command prompt.
Note:
2.
3.
4.
In the Source tab, select the Search Update Centers radio button, then select the
Internal Automatic Updates checkbox.
5.
Click Next, then select the ECSF Design Time Extension checkbox.
6.
7.
3.7.2 What Happens When You Add the Search Navigation Tab to the Overview Editor
When the Search navigation tab is added, the oracle.ecsf.dt.jar file appears in the
oracle_home/jdev/extensions directory and the following files appear in the oracle_
home/ecsf/lib directory:
ecsfSchema.sql
ecsfSysView.sql
search_admin_wsclient.jar
ecsf.jar
ecsf-dt_bundle.zip
search_client.jar
ecsfSeedData.sql
The Search navigation tab appears in the overview editor of JDeveloper, as shown in
Figure 293.
Use the Search navigation tab to configure the search-related properties.
For more information, see Chapter 29, "Creating Searchable Objects."
This bundle is specified in the adf-config.xml file and is created at runtime. For
Oracle Fusion applications, there are two important points:
Oracle Enterprise Scheduler Service projects for containing Job, Job Set,
Incompatibility and Schedule Metadata as well as source files for any Java Job
implementation.
ADF data model projects for containing Parameter view object business
components.
Note:
2.
3.
In the File Groups Properties, click New to create a new file group.
4.
5.
6.
After completing these steps, the SuperEss project will be complete. Follow
Section 3.10.2, "How to Build the EAR/MAR Profiles" to build the EAR/MAR
deployment profiles. An EAR (Enterprise Archive) is a Java EE archive file that is used
in deploying applications on a Java EE application server. Framework applications are
deployed using both a generic EAR file, which contains the application and the
respective runtime customization, and a targeted EAR file, which contains only the
application for deployment to the application server. A MAR (Metadata Archive) is a
compressed archive of selected metadata used to deploy metadata content to the MDS
Repository.
Note:
3-11
section describes what must be done to properly build Oracle Enterprise Scheduler
Service workspaces to support project-level MARs.
3.10.2.1.1 How to Enable Your Application Workspace for Project-level MAR Deployment In
contrast to standard MAR deployment, in which a single .mar file is created as a
metadata aggregate from contributors defined from one or more projects in the
application workspace, this approach focuses on the creation of a JAR-based
deployment profile in each project where the target file is named with a .mar
extension. The resultant .mar files are then deployed into the application workspace's
jlib folder, which is added to the top-level directory of the EAR by the EAR
deployment profile.
Follow these steps to implement the project-level MAR deployment.
1.
b.
Open the Application Properties, select the Deployment panel, choose your
application's EAR deployment profile and click Edit.
These steps will need to be repeated if you have multiple EAR deployments
for development or test purposes.
c.
Select File Groups and click New to create a new file group. Leave the type as
Packaging and name this group MAR Group.
d.
e.
Select the Contributors heading beneath the new MAR Group file group and
click Add.
f.
Browse to find the application workspace-level jlib directory and click OK.
g.
In the Filters heading beneath the MAR Group, remove all the filters and add
these two rules so they display in this order:
Include *.mar
Exclude *.*
2.
Select the Oracle Enterprise Scheduler Service metadata containing project and
open the project properties.
b.
c.
If necessary, select the JAR File archive type and provide a meaningful profile
name, such as <ProjectName>_MAR.
d.
In the JAR Options panel, change the JAR File destination to point to the
application workspace-level jlib directory, and change the file's .jar extension
to .mar.
e.
Select File Groups > Project Output > Contributors and de-select Project
Output Directory and Project Dependencies.
f.
Click Add to add a new contributor and browse to and select the essmeta
project-level directory.
g.
Select File Groups > Project Output > Filters and confirm the addition of the
relevant Oracle Enterprise Scheduler Service metadata files.
3.
h.
Click OK.
i.
b.
Select the Deployment panel and choose the EAR deployment profile for your
application.
c.
In the MAR Group file group, select Filters and ensure that all of your project
level MAR archives are selected.
d.
e.
Click OK.
f.
g.
Check the boxes for each of the new JAR-based MAR profiles.
h.
Click OK.
i.
2.
Click New to create a new deployment, choose EAR File as the profile type, and
provide a unique name.
3.
In the Application Assembly, choose the SuperESS EJB-JAR profile and nothing
else.
4.
Select the File Groups menu entry and click New, giving the name APP-INF/lib
and assigning the target directory to ess workspace root path/jlib.
5.
Under the APP-INF/lib File Group's contributors, add the directory that holds all
of the Job-supporting Implementation classes (not data model projects with ADF
Business Components for parameter view objects or parameter task flows).
6.
Select the File Groups menu entry and click New, giving the name MAR Group
and leave the target directory empty. Under the MAR Group's contributors, add
the directory that holds all the project level mar files (such as Ess/jlib).
7.
Click OK.
Note that the EAR profile should contain only the SuperEss EJB JAR, the MAR, and
the JAR files for the Job implementation classes. The Oracle Enterprise Scheduler
Service hosting application's EAR file must not contain JARs, descriptors or other
artifacts for UI, data model or services functionality. Should your application contain
3-13
projects with servlet or UI task flows for development testing, they must be bundled
into a separate, UI-specific, set of EAR/MAR deployment profiles.
Click Deploy > <ear profile name> from the Application menu.
2.
3.
If no application servers are defined, or the one to which you wish to deploy is not
defined, click Add an Application Server. Otherwise, select the server. Do not click
Next yet.
4.
De-select the Deploy to all server instances in the domain option, because certain
libraries needed for deployment of the Oracle Enterprise Scheduler Service
hosting application will not be targeted to all the managed servers, and
deployment will fail.
5.
Click Next.
6.
7.
JDeveloper will build the EJB JAR and the MAR, and bundle those archives, along
with the JAR files, in the APP-INF/lib contributor location. This packaged archive will
be sent to the managed server for deployment. During deployment, the Oracle
Enterprise Scheduler Service hosting application will register itself through the
ESSAPP base application using the ESSAppEndpoint descriptor in your ejb-jar.xml
file.
When deployment is finished, jobs can be submitted programmatically or through the
Oracle Enterprise Scheduler Service UI submission task flows. These methods are
documented in the Oracle Fusion Middleware Developer's Guide for Oracle Enterprise
Scheduler.
Choose the Project Source Paths category to display the Project Source Paths
dialog.
3.
In the Default Package field, enter the name of your default package, as shown in
Figure 36.
Many objects are generated automatically and are stored in the default package.
4.
Choose the ADFm Sources category from the Project Source Paths hierarchy to
display the Project Source Paths: ADFm Sources dialog, as shown in Figure 37.
3-15
The location for all the ADF Metadata sources is the location that is entered in the
ADFm Source Directory field. You should not have to change the default location.
5.
Choose the Web Application category from the Project Source Paths hierarchy to
display the Project Source Paths: Web Application dialog, as shown in Figure 38.
The location for all the HTML content is the location that is entered in the HTML
Root Directory field. You should not have to change the default location.
6.
Choose the ADF Model category to display the ADF Model dialog, as shown in
Figure 39.
The location of the page definition files is based on a combination of the PageDef
sub-package value, the default package location, and the ADFm Sources directory.
7.
8.
3-17
9.
Choose ADF Library Jar File from the Archive Type list.
Enter the Name as Adf<projName> in accordance with the Package Structure and
Naming Standards.
10. Click OK to save the new deployment profile and close the Create Deployment
Profile dialog.
Note:
dialog.
11. Choose the JSP Tag Libraries category to display the JSP Tag Libraries dialog, as
Verify that you have the following tag libraries listed under the Distributed
libraries folder:
Note:
12. Choose the Libraries and Classpath category to display the Libraries and
3-19
Verify that the libraries listed in Figure 312 have been attached to your user
interface project. As with tag libraries, you may have to add additional libraries.
Important: The Applications Core library must be included to make the page's
design tab visual, instead of showing nesting boxes of XML elements. To add the
Applications Core library:
Verify that the Applications Core library now is included in the Libraries and
Classpath list, as shown in Figure 314.
13. Choose the Resource Bundle category to display the Resource Bundle dialog, as
Note:
14. Choose the Technology Scope category to display the Technology Scope dialog, as
3-21
Verify that the technology scopes that are selected in Figure 316 are selected for
your project.
This selection is limited to what is available, by default, in the
New Gallery. To see other types of objects, choose All technologies from
the New Gallery.
Note:
Note:
Create a Web Archive (WAR) deployment profile. This file is used in deploying
applications on a Java EE application server. WAR files encapsulate in a single
module all of the components necessary to run an application. WAR files typically
contain an application's servlet, JSP, and JSF JSP components. To create the WAR
deployment profile, see "How to Create Deployment Profiles" in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
When you have defined the WAR, create an EAR deployment profile that includes
the WAR profile, for the application. To create an EAR deployment profile, see
"Creating an Application-Level EAR Deployment Profile" in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Create, if necessary, and prepare the standalone application server for deployment.
To run ADF applications, you must install the standalone application server with
the ADF runtime. You can include the ADF runtime during a new application
server installation or you can install the ADF runtime into an existing application
server installation. See "How to Install the ADF Runtime to the Application Server
Installation" and "How to Create and Extend Oracle WebLogic Server Domains" in
the Oracle Fusion Middleware Administrator's Guide for Oracle Application
Development Framework.
Deploy the application using one of these methods:
3-23
Part II
Part II
This part of the Developer's Guide discusses business services and service-oriented
development, defaulting and derivation logic, creating validation rules, and using
messages in Oracle Fusion Applications. It provides information about the Oracle
Fusion Middleware Extensions for Applications base classes and describes how to
share reference data across organizations by using set IDs to partition the data into
different sets of values. Also included is how to implement lookups and simple
lookups.
The Getting Started with Business Services chapter provides overviews of ADF Business
Components, services, validators, list of values (LOVs), and data types. It also
discusses migrating PL/SQL to Java, batch processing, and extensibility and
reusability.
Service-oriented development is based on the concept of services. It is the realization
of business functionality via software that customers can use to compose new business
applications by using existing services in the context of new or modified business
processes. The Developing Services chapter describes how to design the service
interface, how to develop and invoke services. It also provides information about
service versioning.
Defaulting logic means assigning attribute values when a row or entity object is first
created or refreshed and is achieved either declaratively in the attribute's default field
or programmatically by adding code to the EOImpl file. Derivation logic means
assigning attribute values when some other attributes have changed. Derivation is
achieved either declaratively in the transient attribute's default field or by using a
validator, or programmatically by adding code to the EOImpl file. This chapter
provides the information you need to determine whether to implement defaulting or
derivation logic.
The Message Dictionary and Messages Resource Bundles are used to store messages for
display from your application without hard-coding them into your forms and
programs. By using the Message Dictionary and resource bundles you can define
standard messages that you can use in all your applications, provide a consistent look
and feel for messages within and across all your applications, define flexible messages
that can include context-sensitive variable text, and change or translate the text of your
messages without regenerating or recompiling your application code. The Defining and
Using Message Dictionary Messages chapter provides an overview of Message
Dictionary messages and discusses how to use them in Oracle Fusion Applications.
Using Fusion Middleware Extensions for Oracle Applications Base Classes provide
additional features that are not part of the standard ADF Business Components core
entity objects, view objects, and application modules. The Middleware extensions
support Oracle Applications features such as TL (translatable) table, WHO column,
PL/SQL entity, FND services, Unique ID, and document sequencing. In JDeveloper,
selecting the Oracle Fusion Applications Developer role automatically sets the
Middleware extensions for Oracle Applications base classes as the default classes for
ADF Business Components objects. The base classes become available when you add
the Applications Core library. This chapter describes the Oracle Fusion Middleware
extensions for Oracle Applications base classes that extend the features of standard
ADF Business Components classes.
SetIDs enable different organizations within a single company to use different sets of
reference data to serve the same purpose. For example, the job codes for one country
might be different from the job codes for another country. Each organization can
maintain its job code data in the same table, using a set of values that is specific to that
organization. You use set IDs to partition the table into different sets of values so that
each organization can identify and access its own data. In addition to tables, other
sources of reference data such as lookup types and views can also be partitioned and
shared using set IDs. These are all generically referred to as reference entities. This
chapter describes how to share reference data across organizations by using set IDs to
partition the data, implement shared reference entities, extract and expose set ID
metadata, and implement shared lookups.
Lookups in applications are used to represent a set of codes and their translated
meanings. For example, a product team might store the values 'Y' and 'N' in a column
in a table, but when displaying those values they would want to display "Yes" or "No"
(or their translated equivalents) instead. Each set of related codes is identified as a
lookup type. There are many different examples of these across Oracle applications.
A document sequence uniquely numbers documents generated by an Oracle Fusion
Applications product. Using Oracle Fusion Applications, you initiate a transaction by
entering data through a form and generating a document, for example, an invoice. A
document sequence generates an audit trail that identifies the application that created
the transaction, for example, Oracle Receivables, and the original document that was
generated, for example, invoice number 1234.
Implementing Audit Reports describes how to track the history of the changes that have
been made to data in Oracle Fusion Applications. Audit Trail includes information
such as who has accessed an item, what operation was performed on it, when it was
performed, and how the value was changed.
This part contains the following chapters:
4
Getting Started with Business Services
4-1
All logic existing in one entity object Java class not required.
It's valid for the entity object to call utility classes for code modularity
purposes.
Note:
If a business rule can be defined declaratively, you should always use the declarative
approach. For example, if an attribute has a constant default value, then you should
specify it in the Entity Object wizard rather than coding it. You should also first
consider using declarative validators for your validation logic, which is explained in
Section 4.2, "Understanding Validators".
The life cycle of an entity object begins with being created as a new entity object or
fetched from the database as an unmodified entity object. The entity object can then be
modified or removed. Only new, modified, or removed entity objects are in the
transaction pending change list and are posted to the database when the transaction is
committed.
For more information about the key events in the entity objects life cycle and where
you can add entity object business logic programmatically, see the Introduction to
Programmatic Business Rules section in the "Implementing Validation and Business
Rules Programmatically" chapter in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
Service view object: Represents an outfacing business object and contains only the
attributes in the business object. For example, it contains the foreign key ID
attribute such as SupplierID, but it does not contain foreign key reference
attributes such as SupplierName.
UI view object: This view object may contain addition UI flags and calculated
attributes that are used for a particular UI. In addition, the UI view object may join
to other tables for additional foreign key attribute references.
Understanding Validators
Note:
UI application modules may contain additional view objects and context values
that are only required for a particular UI, but not needed by a business service.
Application modules that define public services are versioned, but internal UI
application modules are not.
UI application modules and service application modules share the underlying entity
objects as shown in Figure 41. A UI application module can also call a service.
Figure 41 UI Application Module and Service Application Module
4-3
Note:
You have a complicated query and the WHERE clause cannot be implemented using
view criteria.
Your query includes derived attributes that cannot be implemented as calculated
attributes based on a SQL expression.
If you are unable to use declarative SQL mode, you should try and use normal SQL
mode, which gives you full control over the WHERE clause. Only use expert mode if
other modes do not work. However, you should still base the view object on an entity
object when the query supports it.
Non-expert mode view objects are metadata based and more declarative instead of
SQL based. The declarative approach gives you benefits such as:
The runtime query optimization feature is enabled only when you use declarative
SQL mode. ADF Business Components makes runtime changes to the SQL based
on usage such as column pruning to improve performance.
Declarative SQL optimization means you can consider creating view objects that
can be reused in multiple UIs without impacting runtime performance.
For more information about how to set the SQL mode, see the Working with View
Objects in Declarative SQL Mode section of the "Defining SQL Queries Using View
Objects" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
4-5
Entity object based view objects are not supported for the SQL statement you are
using, for example:
Union
Select Distinct
Group By
Your data doesn't come from the database. For example, the data comes from
external files.
Even if you have to use expert mode view object, you should still base your view
object on top of entity objects because:
The attributes from the entity object are still declaratively defined so that you can
partially benefit from the declarative approach.
Multiple view objects based on the same entity object can automatically see
updates made by any one of them.
Updated reference information is reflected when foreign key attribute values are
changed.
Metadata, (UI hints, associations, and other attributes), are automatically
propagated up to the view objects from entity objects.
New row management, such as view link consistency, only works with an entity
object-based view object.
findByKey doesn't work for view objects with no entity usage unless you turn on
the key management at the view object level (and this will add significant
resources and CPU time). The findByKey method is a frequently invoked by any
operation that involves setting the current row, such as clicking a row on an ADF
Faces rich client table:
findByKey does not find the matching view row in the view object cache if the
key management is not enabled.
findByKey adds the row fetched from the database into view object cache even
if the view object already has the same row in cache if the key management is
not enabled.
Updatable view objects must be based on entity objects so that view objects can
coordinate with the underlying entity objects to perform DML.
5
Developing Services
Business-driven
Coarse-grained
Process-centric
Stateless invocation
Loosely coupled
Distributed
Standards-based
In Oracle Fusion, applications use both ADF Business Components services and
service-oriented architecture (SOA) services. ADF Business Components services
should be created to manage business objects and SOA services are for orchestration
and business processes. SOA services use business object services to encapsulate
business processes as illustrated in Figure 51:
Developing Services
5-1
This chapter focuses on business object services that are implemented using ADF
Business Components services.
In Oracle Fusion, you make business objects and related business logic available via
user interfaces (UIs) and services. A single general-purpose service can satisfy
multiple use cases such as:
XML-based reporting
Primary key attributes, including the system generated surrogate keys when
defined.
Attributes that are of business value to the consumer. This will include most
attributes of the physical tables.
Find Operation:
List<AttrCtrlHints>
Custom Operations
Custom service operations encapsulate complex business rules and may coordinate
execution of two or more data-centric operations within one atomic transaction.
Developing Services
5-3
create
merge
update
delete requisition
copy requisition
get requisition
cancel
create
merge
update (change)
acknowledge
close
Typically, you should include all the standard operations, although the delete operation
should only be included if supported by the business object.
For example:
There is a requirement to return a person's name based on personId. To satisfy that
requirement, you might want to create an operation such as:
public String getPersonName(Long personId)
However, it is likely that this service will soon be adopted by more consumers, which
will require other attributes of a person. In this example, it makes sense to return the
person object instead of just the name into the first specification of the service
interface, such as:
public Person getPerson(Long personId)
Developing Services
5-5
Developing Services
5-7
Developing Services
exception while another returns an empty collection, the consumers perceive the
services as unstable and unpredictable. The reported exception should contain as
much information as possible so that the consumers can pinpoint the problem easily.
All service operations are delegated to the underlying ADF Business Components
objects and their methods. As a service provider, you just need to implement your
validation logic and business rules in your server side objects, define appropriate error
messages declaratively, or throw appropriate JboExceptions programmatically.
Oracle ADF has one generic exception or fault to handle all ADF Business
Components exceptions. Whenever an exception is thrown from the underlying ADF
Business Components object for one of the service standard or custom methods, the
exception is thrown as a Service Exception, which contains all of the information
available from the original thrown exception. This also includes support for bundled
exceptions.
Developing Services
For more information see "Implementing Business Services with Application Modules"
in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Note:
The SDO attribute name is derived from the view object attribute name, and you
cannot override it.
Attribute Type Consistency
In general, the SDO attribute type is defaulted from the view object attribute, and you
can just use the default value. However, there are several exceptions.
Boolean type
A SDO attribute in boolean domain (only have true/false value) must be of
Boolean type.
Oracle ADF provides a feature that maps between the view object attribute String
type and the SDO attribute Boolean type. This feature will allow you to continue
using String in the view object attribute, but use Boolean in SDO.
To expose a Boolean domain view object attribute of String type as Boolean type in
SDO, do the following:
1.
2.
If needed, create a property set. This property set is used to indicate how
Oracle ADF should convert between String and Boolean. Oracle ADF provides
property sets for Y/N or T/F or 1/0. If the possible values are not Y/N or T/F
or 1/0, then you will need to create a property set. Navigate to the New
Object Gallery, and select Property Sets under ADF Business Components.
Developing Services
5-9
Developing Services
3.
Navigate to the Source view and add the following element as a child of the
Domain element:
<Domain>
<Properties>
<SchemaBasedProperties>
<BooleanValueMapping>
<ValueMapping JavaStringValue="true" StorageValue="A"/>
<ValueMapping JavaStringValue="false" StorageValue="I"/>
</BooleanValueMapping>
</SchemaBasedProperties>
</Properties>
</Domain>
This example assumes that the possible values are "A" and "I", where "A"
means true and "I" means false. You should replace these values with your
own.
4.
Specify the property set for the attribute. If the view object attribute is
entity-object based, then go to the entity object. Otherwise, go to the view
object. Navigate to the Source view and, in the corresponding Attribute or
ViewAttribute section, add the TypeValueMapPropertySet attribute. For
example:
<Attribute
Name="Flag"
TypeValueMapPropertySet="oracle.jbo.valuemaps.BooleanYNPropertySet">
</Attribute>
Navigate to View Object wizard > Java > Generate Service Data Object
Class and generate or regenerate the SDO.
AmountType
An SDO attribute storing a price or amount could use the AmountType datatype.
Examples are 100 USD or 35.3 RMB. A number and a currency code are always
present in this type of attribute. AmountType is a complex type and defined as:
<xsd:complexType name="AmountType">
<xsd:simpleContent>
<xsd:extension base="xsd:decimal">
<xsd:attribute name="currencyCode" type="xsd:normalizedString"
use="optional"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
Developing Services
To use the AmountType, two attributes in view objects must be present: One for
the number/amount itself, and the other for the currency code. To use the
AmountType, do the following:
1.
Navigate to View Object wizard >Attributes and select the specified Price or
Amount attribute. Then, click Edit.
2.
3.
4.
Keep the currency code in the SDO payload. In another words, always expose
the currency code attribute in SDO, and don't disable "SDO Property". This
will allow the consumer to change the currency code even if the price/amount
is not present.
During runtime, if the payload contains conflicting currency codes, then an
exception will be thrown from Oracle ADF. For example, an exception will be
thrown if the service payload is something like the following:
<SalePrice currencyCode="USD">100</SalePrice>
<ListPrice currencyCode="RMB">100</SalePrice>
Instead, both SalePrice and ListPrice should contain same value for the
currentCode attribute:
<SalePrice currencyCode="USD">100</SalePrice>
<ListPrice currencyCode="USD">100</SalePrice>
Or the currencyCode is specified in one element and omitted from the other:
<SalePrice currencyCode="USD">100</SalePrice>
<ListPrice>100</SalePrice>
MeasureType
An SDO attribute storing a quantity could use the MeasureType data type.
Examples of quantities are: 10 meters or 105.3 pounds. Two things are always
associated with a quantity: A number and a unit of measure. MeasureType is a
complex type and defined as the following:
<xsd:complexType name="MeasureType">
<xsd:simpleContent>
<xsd:extension base="xsd:decimal">
<xsd:attribute name="unitCode" type="xsd:normalizedString"
use="optional"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
Developing Services
In a view object, there are two attributes related to this one quantity: The number
attribute and the unit of measure attribute. To define the attribute as MeasureType,
do the following:
1.
Navigate to View Object wizard >Attributes and select the specified Quantity
attribute. Then, click Edit.
2.
3.
4.
Keep the unit of measure attribute in the SDO. In another words, always
expose the unit of measure attribute in SDO, and don't disable "SDO
Property". This will allow consumers to change the unit of measure even if the
quantity itself is not present.
When there is an entity association and the association has the destination accessor
generated, then you should add the custom property in the association. When an
association doesn't exist such as flexfield or the association doesn't have the
destination accessor generated, then you must add the same property to the view link.
Developing Services
Note:
For the purchase order header, line, and shipment example, if your service includes
the processPurchaseOrders API that takes a list of purchase order headers, then you
must enable Support Warnings in the purchase order header view object. If your service
also includes the processLines API that takes a list of purchase order lines, then you
also need to enable Support Warnings in the line view object. For the other detail level
service data objects, you should take a more proactive approach and define your
business object as supporting informational messages if you think you will need this
feature in the future.
Developing Services
1.
2.
3.
4.
Define an LOV on the foreign alternate key (Dname) using the above view
accessor, and configure the LOV to populate the foreign key ID (DeptId) as the
derived attribute.
Scenario 2
Single attribute Foreign Key and multiple attribute Alternate Key (Example: PersonVO
has OrganizationId as foreign key id, and OrganizationName+BusinessGroupName as
the composite alternate key).
Each alternate key attribute needs to have an LOV defined, and each LOV should have
all the alternate key attributes as the driving attribute and the foreign key ID as the
derived attribute.
1.
2.
3.
4.
5.
Modify PersonVO.xml to make the LOVs driven by all the foreign alternate key
attributes. For example:
<ListBinding
Name="LOV_OrganizationName"
ListVOName="OrganizationVA"
ListRangeSize="-1"
NullValueFlag="none"
NullValueId="LOV_OrganizationName_LOVUIHints_NullValueId"
MRUCount="0">
<AttrArray Name="AttrNames">
<Item Value="OrganizationName"/>
<Item Value="BusinessGroupName"/>
</AttrArray>
<AttrArray Name="DerivedAttrNames">
<Item Value="OrganizationId"/>
</AttrArray>
<AttrArray Name="ListAttrNames">
<Item Value="OrganizationName"/>
<Item Value="BusinessGroupName"/>
<Item Value="OrganizationId"/>
</AttrArray>
Scenario 3
Single attribute Foreign Key and multiple attribute Alternate Key and one of the
alternate key attribute is another foreign key (Example: PersonVO has BirthOfCountry
as foreign key id, and BirthOfCity as another foreign key ID. BirthOfCity has
BirthOfCountry+CityName as a composite alternate key).
Developing Services
The first foreign key (BirthOfCountry) must be resolved first, either based on #1 or #2.
Then the second alternate key should filter by the first alternate).
1.
2.
3.
Define an LOV view object based on CityEO. Define a view criteria to filter by
CountryId.
4.
5.
6.
7.
Scenario 4
Composite foreign key.
Each foreign key ID will be dealt with individually. For example, the foreign key id is
OrgId+SourceId, then orgId and SourceId should be resolved based on solution in #1
or #2 or #3 separately. Then a validator must be defined to make sure combination of
OrgId and SourceId is valid. This has the assumption that each individual attribute are
a primary key itself.
Developing Services
Table 51
Operation without
Informational Messages
(Support Warnings Flag is
off)
Operation with
Informational Messages
(Support Warnings Flag is
on)
List<Person>
processPerson(String op,
List<Person> persons,
ProcessControl ctrl)
PersonResult
processPerson(String op,
List<Person> persons,
ProcessControl ctrl)
Person
createPerson(Person
person)
PersonResult
createPerson(Person
person)
void
terminateEmployee(BigDec
imal empId)
ServiceMessage
terminateEmployee(BigDec
imal empId)
String
getApplicationName(BigDe
cimal applicationId)
StringResult
getApplicationName(BigDe
cimal applicationId)
Comments
If the Support Warnings design time flag is off, no informational messages are returned
(the first column in the above table). If the flag is on (the second column in the above
table), then:
Note:
Find Operation
When you include the standard operations in a service interface, you can enable the
generic find operation, or select a view criteria and expose a find operation that uses
the view criteria.
Oracle ADF has a default list of operators (such as =, contains, and so on) that can be
used in the find operation. You can enable more custom operators or disable an
operator in the default list.
Developing Services
2.
3.
4.
5.
5.3.5.1 Authentication
An authentication policy determines how the caller proves its identity. A simple case
could be user name and a password in clear text, which is simple but not very secure.
Or a token can be generated by an identity provider and then passed to the service
provider.
See Chapter 52, "Securing Web Services Use Cases" for information about the different
authentication policies supported. Once a security policy is chosen, you need to add it
as an annotation in your xxxServiceImpl class. For example:
@SecurityPolicy( { "oracle/wss11_saml_or_username_token_with_message_protection_
service_policy"})
@CallbackSecurityPolicy("oracle/wss11_saml_token_with_message_protection_client_
policy")
5.3.5.2 Authorization
Authorization determines who can invoke a service operation. To enable
authorization, do the following:
Developing Services 5-17
Developing Services
1.
Note:
2.
Developing Services
c.
<interceptors>
<interceptor>
<interceptor-class>oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-c
lass>
<env-entry>
<env-entry-name>application.name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value><application_name></env-entry-value>
<injection-target>
<injection-target-class>oracle.security.jps.ee.ejb.JpsInterceptor</injectio
n-target-class>
<injection-target-name>application_name</injection-target-name>
</injection-target>
</env-entry>
</interceptor>
</interceptors>
<assembly-descriptor>
Developing Services 5-19
Developing Services
<interceptor-binding>
<ejb-name>*</ejb-name>
<interceptor-class>oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-c
lass>
</interceptor-binding>
</assembly-descriptor>
</ejb-jar>
Click the Configuration tab of Application Module wizard, then choose the
configuration with type "SI", as shown in Figure 55.
Developing Services
2.
3.
Developing Services
This profile is a compound profile and includes two child profiles: Common (JAR File)
and MiddleTier (EJB Jar File). The Common includes the service interface This .jar file
will be required by the consumer when the consumer uses ServiceFactory to invoke
the service. (See Section 5.4.1.1, "Using Service Factory" for more information.) The
MiddleTier .jar file contains the service implementation.MiddleTier profile has a
dependency on the common profile.
Include the MideleTier profile in your application's ear profile (Ear Deployment
Profile >Application Assembly) so that the service will be included in the application
ear file. Do not include the Common profile in the ear profile's Application Assembly.
The Common profile will be included via profile dependency.
Do not include connections.xml in the common .jar file.
There cannot be more than one connections.xml in one application,
otherwise whatever shows up first in the classpath will be picked up,
and this one might not be the right one. To prevent that, the service
interface common profile cannot include connections.xml.
Note:
Developing Services
However, you do not need to repeat the tests that have been done in ADF Business
Components testing:
Data security is defined at the business components object layer, so you do not
need to repeat the data security testing at service layer.
You need to test each service method, but you do not need to test all permutations
of inbound parameters. Therefore, you probably just need to test a success case
and a couple of typical failure cases for each of your service methods.
The following is a list of items that you should validate during the service testing (both
the synchronous and asynchronous versions).
Invoking Services
Successful cases: Verify the response. You might also want to do a query after
a post to check the data is indeed committed.
Failure cases: Verify the fault comes back, and with the expected content.
HTTP Analyzer
You can access HTTP Analyzer within Oracle JDeveloper by navigating to Tools >
HTTP Analyzer, and then clicking on "Create New Request". You then can follow
the UI to invoke a service. Similarly, it doesn't really handle service secured with
oracle/wss11_saml_or_username_token_with_message_protection_service_policy.
The invoked method takes a simple payload, such as a single document or a fixed
number of documents, (including parent and children), and the payload is still
small.
The invoked method is expected to be finished in real time and takes no longer
than a few seconds.
The consumer should consider invoking the method asynchronously if one of the
following conditions is met:
Invoking Services
The method takes a flexible number of documents, such as a list of service data
objects.
The method may be long-running.
It is easier to write a service client using service factory than using JAX-WS.
The consumer side doesn't need to generate or maintain the source control of the
proxy code.
If the service is co-located, the service invocation is more performant because it
does not invoke XML serialization and de-serialization.
2.
Invoking Services
<StringRefAddr addrType="serviceSchemaName">
<Contents>WorkerService.xsd</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaLocation">
<Contents>oracle/apps/sample/dtsvc/</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiFactoryInitial">
<Contents>weblogic.jndi.WLInitialContextFactory</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiProviderURL">
<Contents>t3://localhost:7202</Contents>
</StringRefAddr>
</RefAddresses>
</Reference>
Property Name
Property Value
Example
Reference/name
{http://xmlns.oracle.com/apps/sample/dt
svc/}WorkerService
oracle.apps.sample.dtsvc.WorkerService
WorkerService.xsd
oracle/apps/sample/dtsvc/
Invoking Services
Property Value
Example
jndiProviderUrl
Invoking Services
<RefAddresses>
<XmlRefAddr addrType="WebServiceConnection">
<Contents>
<wsconnection
description="http://rws65094fwks:7202/MySampleSvc/HrService?WSDL"
service="{http://xmlns.oracle.com/apps/sample/hrService/}HrService">
<model
name="{http://xmlns.oracle.com/apps/sample/hrService/}HrService"
xmlns="http://oracle.com/ws/model">
<service
name="{http://xmlns.oracle.com/apps/sample/hrService/}HrService">
<port name="HrServiceSoapHttpPort"
binding="{http://xmlns.oracle.com/apps/sample/hrService/}HrServiceSoapHttp"
portType="http://xmlns.oracle.com/apps/sample/hrService/}HrService">
<policy-references xmlns="http://oracle.com/adf">
<policy-reference category="security"
uri="oracle/wss11_saml_token_with_message_protection_client_policy" enabled="true"
id="oracle/wss11_saml_token_with_message_protection_client_policy" xmlns=""/>
</policy-references>
<soap
addressUrl="http://rws65094fwks:7202/MySampleSvc/HrService"
xmlns="http://schemas.xmlsoap.org/wsdl/soap/"/>
</port>
</service>
</model>
</wsconnection>
</Contents>
</XmlRefAddr>
</RefAddresses>
</Reference>
The second connection is a standard web service connection. To generate the web
service connection entry in connections.xml, do the following:
a.
Create a web service proxy. (See "Creating a Web Service Proxy Class to
Programmatically Access the Service" in Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework, for more
information.)
b.
Create a web service connection. (See "How to Create a New Web Service
Connection" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework for more information.)
c.
Note:
Invoking Services
The following are the client-side policies that you can use to invoke a service
protected by message protection policy:
wss_username_token_over_ssl_client_policy
wss_saml_token_bearer_over_ssl_client_policy
wss11_username_token_with_message_protection_client_policy
wss11_saml_token_with_message_protection_client_policy
wss_http_token_over_ssl_client_policy
Identity switch is required. If the service must be invoked with a different user
(usually using appid), then you need to specify LPA:
<port >
<call-properties xmlns="http://oracle.com/adf">
<call-property id="csf-key" xmlns="">
<name>csf-key</name>
<value>system1-key</value>
</call-property>
</call-properties>
<policy-references xmlns="http://oracle.com/adf">
<policy-reference category="security" uri="oracle/wss_username_token_
client_policy" enabled="true" id="oracle oracle/wss_username_token_client_
policy" xmlns=""/>
Invoking Services
</policy-references>
</port>
Replace system1-key with the csf-key holding the application identity user
name and password required by the user case. The actual application
identities and their corresponding csf-keys are centrally provided.
If the service is protected by message protection policy, then use
oracle/wss11_username_token_with_message_protection_client_policy.
4.
SDOs based on polymorphic view objects don't have Java classes generated. To
create these SDOs, use the generic DataObject class:
import commonj.sdo.DataObject;
DataObject emp = datafactory.create("http://xmlns.oracle.com/apps/fooService/",
"Bar");
emp.set("Empno", new Long(8080));
emp.set("Ename", "Oliver");
emp.set("Job", "MANAGER");
Note:
5.
Partial Attribute
By default, the find operation returns all the attributes including all details.
When you only need some attributes, you should set the partial attributes on
the FindCriteria parameter of the find method. Do this in the following
situations:
SDO contains LOB, which can be very expensive to retrieve and transfer.
SDO contains details that are not needed, such as translations. Querying
detail is also expensive.
Invoking Services
The following example shows how to set the partial attributes to include only
Dname, Loc from Dept, and exclude Empno from Emp:
FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
List l = new ArrayList();
l.add("Dname");
l.add("Loc");
l.add("Emp");
fc.setFindAttribute(l);
List cfcl = new ArrayList();
ChildFindCriteria cfc =
(ChildFindCriteria)datafactory.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
List cl = new ArrayList();
cl.add("Empno");
cfc.setFindAttribute(cl);
cfc.setExcludeAttribute(true);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult res = svc.findDept(fc, null);
The following example shows how to set the partial attributes to exclude
PurchaseOrderLine from PurchaseOrder:
FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
List l = new ArrayList();
fc.setExcludeAttribute(true);
l.add("PurchaseOrderLine");
fc.setFindAttribute(l);
PchaseOrderResult res = svc.findPurchaseOrder(fc, null);
Filter
The find API allows you to specify the WHERE clause of your query. The WHERE
clause can be set on any level of the SDO. The following example shows how
to retrieve only the departments with a department number greater than 10
and child employees whose names start with "A":
FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
//create the view criteria item
List value = new ArrayList();
value.add(new Integer(10));
ViewCriteriaItem vci =
(ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
vci.setValue(value);
vci.setAttribute("Deptno");
List<ViewCriteriaItem> items = new ArrayList(1);
items.add(vci);
//create view criteria row
ViewCriteriaRow vcr = (ViewCriteriaRow)
datafactory.create(ViewCriteriaRow.class);
vcr.setItem(items);
//create the view criteria
List group = new ArrayList();
group.add(vcr);
ViewCriteria vc = (ViewCriteria)datafactory.create(ViewCriteria.class);
vc.setGroup(group);
//set filter
fc.setFilter(vc);
List cfcl = new ArrayList();
Invoking Services
You also can query the parents with the children that satisfy certain criteria.
For example, use the following to retrieve the departments with employees
whose salary is greater than $10,000:
//create the view criteria item on the employees
List nvalue = new ArrayList();
nvalue.add(new BigDecimal(10000));
ViewCriteriaItem nvci =
(ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
nvci.setValue(nvalue);
nvci.setAttribute("Salary");
nvci.setOperation(">");
List<ViewCriteriaItem> nitems = new ArrayList(1);
nitems.add(nvci);
//create view criteria row
ViewCriteriaRow nvcr = (ViewCriteriaRow)
datafactory.create(ViewCriteriaRow.class);
nvcr.setItem(nitems);
//create the nested view criteria
List ngroup = new ArrayList();
ngroup.add(nvcr);
ViewCriteria nvc = (ViewCriteria)datafactory.create(ViewCriteria.class);
nvc.setGroup(ngroup);
//create the view criteria item on the department
ViewCriteriaItem vci =
(ViewCriteriaItem)datafactory.create(ViewCriteriaItem.class);
vci.setAttribute("Emp");
vci.setNested(nvc);
List<ViewCriteriaItem> items = new ArrayList(1);
items.add(vci);
//create view criteria row
ViewCriteriaRow vcr = (ViewCriteriaRow)
Invoking Services
datafactory.create(ViewCriteriaRow.class);
vcr.setItem(items);
//create view criteria on department
ViewCriteria vc = (ViewCriteria)datafactory.create(ViewCriteria.class);
List group = new ArrayList();
group.add(vcr);
vc.setGroup(group);
//set filter
FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
fc.setFilter(vc);
DeptResult dres = svc.findDept(fc, null);
Paging
If you know that your query might return a large amount of data, you should
make multiple service invocations, and use FetchSize and FetchIndex to
control the amount of the data that you want to retrieve.
The following example shows how to retrieve only the second employee and
the employee's department:
FindCriteria fc = (FindCriteria)datafactory.create(FindCriteria.class);
List cfcl = new ArrayList();
ChildFindCriteria cfc =
(ChildFindCriteria)datafactory.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
cfc.setFetchStart(1);
cfc.setFetchSize(1);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult dres = svc.findDept(fc, null);
6.
Return mode
Use ReturnMode on ProcessControl to specify whether you want to return a
list of SDOs with all attributes, or with primary key attributes, or return
nothing in processXXX method. You should only return the primary key or
nothing, unless you need the full SDO returned for further processing
Partial failure
For bulk load, it often makes more sense to commit as many records as
possible, and report the problematic data. By default, either all SDOs go
through or none goes through in processXXX method. However, you can call
setPartialFailureAllowed on ProcessControl and pass that
ProcessControl to the processXXX method. This will turn on the partial
failure feature.
7.
Handle exceptions.
Developing Services 5-33
Invoking Services
The ServiceErrorMessage can contain one or more child error messages, and each
child can contain its own children. Basically it is a tree hierarchy. You could
consider ServiceErrorMessage as a counterpart of the JboException at the service
layer.
The ServiceErrorMessage has a few subclasses including
ServiceAttrValErrorMessage, ServiceRowValErrorMessage, and
ServiceDMLErrorMessage Their counterparts in ADF Business Components are
AttrValException, RowValException, and DMLException. Note that
ServiceException is an Exception, but all other classes above including
ServiceMessage, ServiceErrorMessage, ServiceAttrValErrorMessage,
ServiceRowValErrorMessage, and ServiceDMLErrorMessage are not exceptions.
As the consumer of a service, if you call a service and need to take different actions
based on the exceptions, you might need to walk through the message tree
structure.
The following is a simple example that walks through the message and converts to
JboException:
public static RuntimeException convertServiceException(ServiceException ex) {
return convertToRuntimeException(ex.getFaultInfo());
}
public static RuntimeException convertToRuntimeException(ServiceMessage
svcMsg) {
RuntimeException ret = null;
String msgStr = svcMsg.getMessage();
List d = svcMsg.getDetail();
Throwable[] details = null;
if(d != null && !d.isEmpty()) {
details = new Throwable[d.size()];
for(int i=0; i<d.size(); i++)
{
Object obj = d.get(i);
if(obj instanceof ServiceMessage)
details[i] =
(convertToRuntimeException((ServiceMessage)obj));
else if(obj instanceof Throwable)
details[i] = (Throwable)obj;
else
details[i] = new Throwable(obj.toString());
}
}
if(svcMsg instanceof ServiceErrorMessage) {
JboException ex = new JboException(msgStr);
Invoking Services
ex.setExceptions(details);
ret = ex;
}
else {
JboWarning w = new JboWarning(msgStr);
w.setDetails(details);
ret = w;
}
return ret;
}
8.
As the service consumer, you should retrieve the informational message from the
return and perform appropriate actions such as converting it to JboException and
displaying it in the UI. An example might be:
ProcessControl pc = (ProcessControl)datafactory.create(ProcessControl.class);
pc.setPartialFailureAllowed(true);
EmployeeResult res = svc.processEmployee("Create", list, pc);
if(res != null) {
List msgs = res.getMessage();
if(svcMsgs != null && !svcMsgs.isEmpty()) {
Exception[] exceptions = new Exception[svcMsgs.size()];
for(int i=0; i<exceptions.length; i++)
exceptions[i] = convertToRuntimeException(svcMsgs.get(i));
JboException ex = new JboException(....., exceptions); //create a bundled
exception with the service errors as detail
}
throw ex;
}
For more information about invoking a service using service factory, see Chapter 43,
"Synchronously Invoking an ADF Business Components Service from an Oracle ADF
Application."
Invoking Services
For more information about working with data from a remote ADF Business
Components service, see Chapter 41, "Working with Data from a Remote ADF
Business Components Service."
Important:
For the proxy code, it is recommended to have proxy in the package structure,
such as oracle.apps.<lbaTop>.<lbaCore>.<xyzService>.proxy. It is
recommended to generate the type in the "type" subpackage.
Invoking Services
If the caller is ADF UI: The UI must raise an event, which is received by a
mediator. The mediator invokes a BPEL process that invokes the asynchronous
service and then invokes a second service after receiving the callback. The second
service is responsible for notifying the UI side that the process has completed and
then the UI uses the Active Data Service to refresh the UI.
For information about how to enable the UI for dynamic update via Active Data
Service, see Chapter 44, "Implementing an Asynchronous Service Initiation with
Dynamic UI Update."
The caller must raise an event, which is received by a mediator. The mediator
invokes a BPEL process, which invokes the asynchronous service. A callback is
received from the asynchronous service.
Invoking Services
6
Defining Defaulting and Derivation Logic
This chapter describes how to define your defaulting and derivation logic, how to use
Groovy (a Java-like scripting language), and how to use Oracle Application
Development Framework (Oracle ADF) validators and convertor hints instead of
using messages.
This chapter includes the following sections:
6-1
When implementing defaulting or derivation logic, you should also consider the
following factors:
Oracle ADF handles the propagation of the foreign key ID if there is an association
between two entities. This is where the association is defined from the parent
entity object to the child entity object, and when the detail entity object is created
from the association accessor of the parent entity object. For example:
Row parentRow = ....RowIterator ri =
(RowIterator)parentRow.getAttribute("<childEOAccessorName>");
Row childRow = r1.createRow();
Similarly, if there is a view link between two view objects, the framework also
handles the foreign key propagation when the child view row is created via the
view link accessor of the parent view row.
List of Values (LOVs) also perform derivation. However, this is at the view object
level and you should not place business logic (including derivation) at this level.
A LOV should only be used on the user interface (UI) to show a list of valid values
or as a service to derive the foreign key ID based on the foreign alternate key.
Validation - Use a Groovy script that returns true or false for declarative validation.
Validation Error Messages - Use Groovy expressions to substitute the tokens in
the error message.
Bind Variables - Define the value for a bind variable using a Groovy script
expression.
View Accessor Bind Variable Values - Supply bind variable values in a view
accessor using Groovy script.
Attributes - Base a transient attribute on a Groovy script. (Currently no UI
support).
Attribute Default Values - Define a default value expression on an attribute using
Groovy script. (Currently no UI support).
Variables - Define a variable on an entity whose value is computed using Groovy
script. (Currently no UI support).
6-3
ADFContext (adf.context)
Error handler that lets the validator generate exceptions or warnings (adf.error)
All other names come from the context in which the script is applied:
You also need to call the method using the "object" keyword, such as
adf.object.createUnqualifiedRowSet(). The "object" keyword is equivalent to
the "this" keyword in Java. Without it, in transient expressions, the method is
assumed to exist on the script object itself, which it does not.
All Java methods, language constructs, and Groovy language constructs are
available in the script.
Aggregates are implemented by calling sum(expr), count(expr), or avg(expr) on
a RowSet object where expr can be any Groovy expression that returns a numeric
value or number domain.
The defaultRowSet reserved keyword has been removed. The method
EntityImpl.createUnqualifiedRowSet() replaces
Use the return keyword as you would in Java to return a value. That is, unless it is
a single-line expression where the return is assumed to be the result of the
expression itself. For example, "Sal + Comm" or "Sal > 0".
Do not use {} to surround the entire script because Groovy interprets { to be the
beginning of a Closure object.
Any object that implements oracle.jbo.Row, oracle.jbo.RowSet, or
oracle.jbo.ExprValueSupplier is wrapped into a Groovy Expando object. This is
to extend the properties available for those objects to beyond the bean properties
and also as a way to avoid introspection for most used names.
and
source.structureDef.name+" of type "+sourceFullName
6-5
Example 65 is an example of accessing the Entity state relative to the database and
relative to the last post operation.
Use adf.object.entityState or adf.object.postState.
To get the old value of an attribute (this works in the context of a transient Entity
Object attribute):
Example 65 Getting the Old Value of a Transient Entity Object Attribute
index = object.getStructureDef().getAttributeIndexOf("Salary");
6-6 Developer's Guide
6-7
{
totSal = 0;
empCount =0;
fullVO = structureDef.getApplicationModule().createViewObject("_AvgSal",
testp.kava.VO7.si33mt.EmpAllView");
empCount = 0;
while (fullVO.hasNext())
{
row = fullVO.next();
sal = row.EmpSal; totalSal = totSal + sal; empCount = empCount + 1;
}
fullVO.remove();
if (empCount > 0)
{
return (int)(totalSal / empCount);
}
else
{
return 0;
}
}
}
}
}
<Attribute
Name="EmpComm"
ColumnName="COMM"
Type="oracle.jbo.domain.Number"
ColumnType="NUMBER"
SQLType="NUMERIC"
TableName="EMP" >
<TransientExpression><![CDATA[
if (EmpSal == null)
{
return null;
}
if (EmpDeptNum == null)
{
return 0;
}
if (EmpDeptNum > 40)
{
retune 500;
}
]]></TransientExpression>
Example 611
<ViewAttribute
Name="Total"
IsUpdateable="false"
AttrLoad="Each"
IsSelected="false"
IsPersistent="false"
PrecisionRule="false"
Type="java.lang.String"
ColumnType="VARCHAR2"
AliasName="View_ATTR"
SQLType="VARCHAR">
<TransientExpression>
<![CDATA[
if (Sal != null && Comm != null)
{
return Sal + Comm;
}
else
{
return Sal;
}
]]>
</TransientExpression>
If you want to define a string literal instead of a Groovy expression, select Literal as
the Value Type and enter the value as "My Literal Value".
6-9
To access the Expression Editor, click the Edit button located next to the Value text
box.
Recalculate Expression is used to determine whether the
expression must be recalculated as changes are made during run-time.
The Recalculate option is hidden for persistent attributes. This is
because Persistent attribute values are always updateable by the user
and therefore, the expression of the attribute should only act as a
default expression so recalculation is not necessary. For non-persistent
attributes, the user can choose to always recalculate, never recalculate,
or decide if recalculation is needed based on the evaluation of the
recalculate expression.
Note:
To ensure that the user has supplied the correct sort of value or a value in a valid
range, input fields can be validated using an Oracle ADF validator. Values may be
Hints to display to the user details of what sort of value they need to enter.
For an individual component, you can explain the error to a user in terms relating to
that specific input component by overriding the hints or by adding or overriding a
detailed error message.
How to override an Oracle ADF validator or converter message with new text
You may not see any messages when you follow these steps to select the Application
Messages resource bundle:
1.
2.
3.
4.
5.
In this case, you may need to override the default message from the validator. To do
so, follow the procedure in "Displaying Hints and Error Messages for Validation and
Conversion" in the Oracle Fusion Middleware Web User Interface Developer's Guide for
Oracle Application Development Framework.
7
Defining and Using Message Dictionary
Messages
Section 7.10, "Formatting Message Dictionary Messages for Display in Oracle ADF
Applications"
Section 7.11, "Integrating Messages Task Flows into Oracle Fusion Functional
Setup Manager"
7-1
messages for Oracle Enterprise Scheduler (ESS) Java programs and test output
messages for Java Diagnostic Testing Framework tests.
The Error, Warning, Information, and UI String message types are described in detail
in Section 7.2, "Understanding Message Types."
Because the messages are stored in Application Object Library
FND_MESSAGE_% tables, these types of messages are sometimes
referred to as FND messages.
Note:
By using the messages in the Message Dictionary, you can define standard messages
that you can use in all your applications, provide consistency for messages within and
across all your applications, define flexible messages, and change or translate the text
of your messages without regenerating or recompiling your application code.
Note: Non-message strings, such as labels, report headings, and
message fragments are typically stored in Oracle Application
Development Framework (ADF) resource bundles. However, because
Oracle ADF resource bundles only can be accessed by Java programs,
you can store these types of strings in the Message Dictionary if C or
PL/SQL programs need to access them.
Non-error and non-warning text and messages that are accessed by C or PL/SQL
code or are used by Oracle Enterprise Scheduler (ESS) statuses or log files. Because
C and PL/SQL programs cannot access Java-based resource bundles, these strings
must be stored in the Message Dictionary.
An example of such a string is the completion text for an ESS program or process.
Strings that are written to ESS job log or output files, as shown in Figure 71.
These strings are used to provide a text record about request processing execution,
failures, and so on.
7-3
You can choose to use the Information message type in one of two ways:
Use the Information message type for all non-error and non-warning messages.
Use the Information message type to store complete messages and use the UI
String message type, which is described in the next section, to store fragments. For
example, if your messages must pass a review process, you might choose to use
the UI String message type for messages that do not need to conform to message
guidelines.
UI String Messages
Use the UI String message type for non-error and non-warning strings that need to be
stored in the Message Dictionary but are not complete messages, such as prompts,
titles, or translated fragments. For example, "Upload Process Parameters." Note that UI
String messages are processed exactly as Information messages.
Note:
Message Text
Message text is required. This is a brief statement of the operation attempted and the
problem that consequently occurred, or information that the user needs to know. The
text is included in log and incident creation messages. The content in this field is
customizable and the text can contain tokens. The maximum field size for messages
stored in the Message Dictionary is 240 characters.
If the entire message, after tokens have been substituted, exceeds the 240 character
limit, the message text is truncated. To allow room for expansion in other languages,
the US version of any translated column should be no more than 70% of the maximum
possible length. (For example, 240 character short text becomes 160 characters in US).
Caution: Tokens are just values substituted into the message at
runtime. Tokens must come from a translated source unless it is a
number, seed data, technical information, or a name that is not
translated. Extreme care must be taken with tokens when substituting
translatable data. You must make sure that it makes sense at run-time
7-5
Message Category: This is a more generic attribute that is used to group messages.
For example, all the messages that relate to one functionality, such as a concurrent
program, can be grouped together into one category.
This is an optional field, but it must have a value to enable implicit incident
creation.
Message categories are defined by lookups (of type extensible) so that they can be
customized by an administrator. The maximum size of this field is 30 characters.
The following are seeded values, but you can add more if required.
Message Severity: This grouping attribute is not generic and indicates the severity
of the message. You must set the severity to High to enable implicit incident
creation for the message. The following are seeded values, but you can add more if
required.
High - This value can be used for serious messages that completely stop the
progress of an important business process or affect a large user community,
and require help-desk personnel's attention.
Medium - This value can be used for less severe and more isolated messages.
7-7
Low - This value can be used when it is unclear whether the message has a
negative impact on end users or business processes.
Valid message severity values are defined by lookups (of type extensible) so that
they can be customized by an administrator. The maximum size of this field is 30
characters.
Message severity: For incident creation, it must be HIGH. For logging, it must be
not null.
Implicit incident creation occurs when logging is enabled.
Implicit logging only occurs if the SEVERE log level or more logging
are enabled.
Note:
Use the Message Dictionary APIs to retrieve a Message Dictionary message. The
PL/SQL methods are in the FND_MESSAGE package and the Java methods are in the
messageService package. For C code, use the methods in the fddutl package.
For more information about the Message Dictionary APIs, see the "Message
Dictionary" chapter in the Oracle E-Business Suite Developer's Guide. You can download
a PDF version of this book from the Oracle Technology Network at
http://docs.oracle.com/cd/V39571_01/current/acrobat/122devg.pdf.
For Java code, implicit incident creation and logging occurs for qualifying messages
when the appropriate formatting methods are called from the MessageServiceAMImpl
class and the MessageServiceAM interface, such as the getUserXML(), formatMap(),
formatUserTextMap(), or formatAdminTextMap() methods. See the MessageServiceAM
and MessageServiceImpl Javadoc for information about which methods to call for
implicit logging. Implicit incident creation and logging also occur when exceptions are
created using the ApplcoreException classes.
When implicit logging and incident creation occurs, additional information is
appended to the message, as follows:
If the incident is created in the middle tier using Java, a Business Process
Execution Language (BPEL) process, or C, the following note is appended:
An application error has occurred. Your help desk was notified. For more
information your help desk may refer to incident {incident number}, {application
server name}, {application server domain name}.
If the incident is created in the database tier using PL/SQL, the following note is
appended:
An application error has occurred. Your help desk was notified. For more
information your help desk may refer to incident {incident number_SID}, {database
server name}, {database instance name}.
To learn more about the information that is included with incidents and associated log
entries, see the "How the Diagnostic Framework Works" section in the Oracle Fusion
Middleware Administrator's Guide.
7.6.1 How to Raise Exceptions Using Oracle Fusion Middleware Extensions for
Applications Exception Classes
Exceptions from messages in the Message Dictionary should be raised using wrapper
classes that are provided in the oracle.apps.fnd.applcore.message package.
Wrappers that are provided correspond to the most commonly used Oracle ADF
exception classes. See Table 71.
Table 71
Exception Class
JboException
oracle.apps.fnd.applcore.messages.ApplcoreException
RowValException
oracle.apps.fnd.applcore.messages.ApplcoreRowValExcepti
on
AttrValException oracle.apps.fnd.applcore.messages.ApplcoreAttrValExcept
ion
In each of these classes, the message name is expected to be passed in the format: APP_
NAME:::MESSAGE_NAME (application short name, followed by exactly 3 colons, followed
by the message name). For example: "FND:::FND_CMN_POSITIVE".
Message tokens passed to most Message Dictionary Java APIs are expected to be
supplied as Map<String, Object> or as an array of alternating String/Object pairs.
With either style, the String is the name of the message token and the following
Object is an object representing the value of that token. The type of the Object is
expected to match the type of the token as shown in Table 72.
Table 72
Token Type
TEXT
java.lang.String
NUMBER
java.math.BigDecimal
7-9
DATE
java.sql.Timestamp
Exceptions that are raised using JboException or one of its subclasses with a severity
level of SEVERITY_ERROR, which is the default, or any java.lang.RuntimeException,
are treated as system errors, and the following occurs:
The error message is replaced with a generic message, such as "An application
error occurred. Your help desk was informed"
A stack trace is written to the log file for the system error
If you do not want the JboException to be treated as a system error, do one of the
following:
You should use the wrappers wherever possible. However, it is possible to also use
native Oracle ADF exceptions directly if there isn't a wrapper that exactly suits your
needs. If you do this, you must specify the FndMapResourceBundle resource bundle
class, and format tokens correctly.
Example 71 shows sample code that raises an ApplcoreException exception.
Example 72 shows an example of raising ApplcoreRowValException exception. Use of
the ApplcoreAttrValException exception is shown in Example 73. Example 74
illustrates how to throw a native JBOException.
To display more than one application error message, such as a series of validation
error messages, bundle the exceptions and throw the bundled exceptions, as shown in
Example 75. The exceptions in the bundle must be only application error exceptions,
such as ApplcoreException, JboException with SEVERITY_RECOVERABLE_ERROR, or
ValidationException. If you include any system error exceptions in the bundle, such
as NullPointerException, the bundle is processed as a system error. For example, if
you include a RuntimeException exception in the bundle, you cannot display the
bundled exception error messages in a popup dialog, because it will be processed as a
system error.
Example 71 ApplcoreException
import oracle.apps.fnd.applcore.messages.ApplcoreException;
// Construct and populate HashMap with token values
Map<String, Object> tokens = new HashMap<String, Object>();
tokens.put("TEXT_TOKEN", "text token value");
tokens.put("NUMBER_TOKEN", new BigDecimal(10));
Calendar cal = Calendar.getInstance();
cal.set(1999, Calendar.DECEMBER, 31, 0, 0, 0);
tokens.put("DATE_TOKEN", new Timestamp(cal.getTimeInMillis()));
errorBundle.setExceptions(details);
throw errorBundle;
7.7.1 How to Associate Error Messages with Oracle ADF Entity Object Validation Rules
To associate an error message with your validation rule:
1. Go to the Failure Handling tab of your declarative validation rule when you have
finished defining your rule. In the Validation Failure Severity field, Select Error.
2.
Click Select Message to open the Select Text Resource dialog. Choose Application
Messages from the Resource Picker dropdown list.
3.
Use the Search area to filter your search results. For example, enter fnd_view in
the search text area to filter your results to messages whose key begins with FND_
VIEW.
You can search for messages only by the message key. All
other types of searches have been disabled. Also notice from the
results that message keys are prepended with the application short
name.
Note:
4.
Select the required error message from the list of results. The Select Text Resource
dialog closes and the selected error message displays in the Failure Message Text
area on the Failure Handling tab.
If the selected message contains tokens, a row for each token is
added into the Error Message Expressions table.
Note:
5.
FND_MESSAGE: This package includes basic APIs to set messages on the error stack,
set tokens, retrieve token substituted message text, and so on.
APP_EXCEPTION: This package includes utilities to raise SQL exceptions with
messages in the Message Dictionary as the exception text.
FND_MSG_PUB: This package includes utilities to set messages on the error stack. In
Oracle Fusion Applications, the error stack also exists natively in the FND_MESSAGE
package; this package is primarily used for backward compatibility with existing
code. PL/SQL code that in EBS was primarily called from Framework usually uses
this method.
For more information about these packages, see the package headers.
msg := fnd_message.get;
-- poping one message out of stack and set it as the current message
fnd_message.pop;
-- get the translated and token subsituted INVALID_USER message
-- then clear the message
msg := fnd_message.get;
If your PL/SQL code uses FND_MESSAGE with FND_MSG_PUB, then errors will be left
on the PL/SQL error stack without raising any exceptions. The call to
OAExceptionUtil should go immediately after the PL/SQL call.
If your PL/SQL code uses APP_EXCEPTION.RAISE_EXCEPTION, or FND_
MESSAGE.RAISE, then errors will cause SQL exceptions to be raised. The call to
OAExceptionUtil.CheckErrors() should be in a SQLException catch block.
If you do not know what style of error handling your PL/SQL code uses, or there
could be a mixture of both, then you should include calls to
OAExceptionUtils.CheckError() in both places, as shown in Example 710.
Example 710
import oracle.apps.fnd.applcore.common.OAExceptionUtils;
...
try
{
// Create and execute a plsql statement
String mystmt = "BEGIN MY_PLSQL_PACKAGE.MY_PROCEDURE(); END;";
DBTransaction txn = getDBTransaction();
CallableStatement mystmt = txn.createCallableStatement(mystmt, 1);
myStmt.executeUpdate();
// Check for errors left on message stack without raising exception
OAExceptionUtils.checkErrors(txn);
}
catch(SQLException sqlE)
{
// Check for FND Messages exception.
// FND Messages exception always has error code -20001.
if (sqlE.getErrorCode() == 20001)
{
OAExceptionUtils.checkErrors(txn);
}
else
// Not a FND Messages exception, re-raise.
throw sqlE;
}
When you receive these types of errors, you can look at the log file entry to find the
original error message.
When generic errors are raised, you will see
oracle.apps.fnd.applcore.messages.ExceptionHandlerUtil class
information at the top of the call stack. This is the code that is replaced
the unhandled exception with the generic error and should not be
mistaken for the original error from the Message Dictionary.
Note:
You can also set one of the following debug options to allow you to see the error more
directly, without having to view the log file entry:
-DAFLOG_ECHOED=true: Sends logging output to the console, as well as the log file
For information about finding the cause of an error and its corrective action and for
information about viewing and managing log files, see the "Managing Log Files and
Diagnostic Data" chapter in the Oracle Fusion Middleware Administrator's Guide and the
"Troubleshooting Oracle Fusion Applications Using Incidents, Logs, QuickTrace, and
Diagnostic Tests" chapter in the Oracle Fusion Applications Administrator's
Troubleshooting Guide.
Programmatically
Exception ex =
new ApplcoreException("FND:::MY_TEST_MESSAGE");
// Retrieve the HTML short message
String htmlShort = Util.formatHTMLMessage(ex);
// Retrieve the HTML message details.
String htmlDetails = (Util.formatHTMLDetailMessage(ex)).getHTMLText();
// Retrieve the plain text messge details
String textDetails = (Util.formatHTMLDetailMessage(ex)).getText();
// Retrieve the full plain text message
String textMsg = Util.formatTextMessage(ex);
7.10.2 How to Convert XML Messages by Configuring the Error Format Handler
You can convert XML messages to HTML or plain text by configuring the error format
handler in the DataBindings.cpx file.
To convert XML messages to HTML by configuring the error format handler:
Under the user interface project, open the DataBindings.cpx file.
1.
In the Property Inspector, set the ErrorHandlerClass field to the value shown in
Example 712 and Figure 74.
Example 712
oracle.apps.fnd.applcore.messages.MessageFormatHandler
Integrating Messages Task Flows into Oracle Fusion Functional Setup Manager
Figure 74 Setting the Value of the ErrorHandlerClass Field in the Property Inspector
Parameters
Passed
Behavior
Comments
NA.
Integrating Messages Task Flows into Oracle Fusion Functional Setup Manager
8
Managing Reference Data with SetIDs
This chapter describes how to share reference data across organizations by using
setIDs to partition the data into different sets of values. Each organization can then
maintain its data in a common table, using a set of values specific to that organization.
This chapter includes the following sections:
Section 8.3, "Integrating SetID Task Flows into Oracle Fusion Functional Setup
Manager"
8-1
Introduction to SetIDs
An attribute passed into an API is validated against the limited set of values
The end goal is to save customers some effort in maintaining reference data by
enabling it to be shared between different parts of the organization that implements
applications. Reference data should not need to be maintained in multiple places at
multiple times. Reference data is data in tables that you do not regard as transactional
and high volume; for example, payment terms that can be used on a customer invoice.
By dividing the reference data into partitions appropriate to the organizational entities
that will use the data, setIDs enable you to share control table information and
processing options among business units. The goal is to minimize redundant data and
system maintenance tasks. For example, you can define a group of common job codes
that are shared between several business units. Each business unit that shares the job
codes is assigned the same setID for that record group.
SetIDs can be thought of as a striping technology to partition referenced data. All
shared reference tables can be striped with a setID column to enable partitions (or sets).
This does not require you to change the tables' primary keys.
With partitioning, a customer can choose to have reference data sets specific to each
organizational unit mapped one-to-one, or have several different organizational units
use the same set of reference data. Customers, rather than development, will have the
choice in determining what level of sharing or exclusivity they would like to maintain
in the reference data.
A setID is the means by which applications can filter reference data into subsets when
they are referenced by different transactional entities. The filtering is driven, indirectly,
by contextual values available in the referring transactional entity.
Asset Book A book that contains assets belonging to a business unit or ledger. It
holds information about the asset's acquisition, depreciation, and retirement. An
asset may be assigned to one or more books; for example, the corporate, tax and
budget books.
Introduction to SetIDs
Cost organization will likely map into a company's enterprise structure as a cost
department.
If you cannot change the reference data for different parts of a deploying
enterprise, the reference data is global and partitioning is not required.
Examples of data suitable for partitioning include (but are not limited to) units of
measure, currency codes, country codes, or anything else governed by a standard.
If the values for the reference data will be decided by the general manager, the best
reference data set determinant is likely to be the Business Unit.
For more information about setID determinant types, see Section 8.2.3, "How to
Annotate Transactional Entity Objects for SetID".
The following sections introduce the elements of setID machinery and the ways in
which they can be used to implement data sharing.
8-3
Introduction to SetIDs
Row striping (ROWSTRIPE) This is the simplest pattern, and the default. In this
pattern the SET_ID column is just a striping column, and is not part of the set of
unique keys for the table. You can filter as follows:
WHERE SET_ID = :1
Row striping with common rows (COMMON) This is the same as the row striping
pattern, with the addition of a COMMON partition. You filter as follows:
WHERE SET_ID IN (:1, 0)
Note: The set with setID of 0 is seeded as the common set. This set
will be available for assignment only if you select Row Striping With
Common Rows for the reference entity.
For more information about partitioning patterns, see Section 8.2.1, "How to Annotate
Reference Entity Objects for Sharing".
Introduction to SetIDs
Sets
Reference groups
SetID assignments
Reference entities
Sets Table
The sets table, FND_SETID_SETS, lists all of the sets defined for Oracle Applications,
plus any new sets that you define. It includes the columns SET_ID and SET_NAME,
which enable you to select the proper SET_CODE.
Sets listed in this table include:
8-5
Introduction to SetIDs
application that owns the reference entities in that group. Application development
teams are ultimately responsible for defining and delivering reference groups.
Only reference entities that might be referenced as setID
targets need to be captured here; this is not intended to be an
exhaustive inventory of all tables in the applications. For more
information about reference groups, see Section 8.1.3.2, "Reference
Groups".
Note:
REFERENCE_GROUP_NAME
DETERMINANT_TYPE
DETERMINANT_VALUE
Note:
Introduction to SetIDs
Fnd_setid_reference_groups package
This package contains table handlers for fnd_setid_reference_groups table.
Fnd_setid_ref_entities_pkg package
This package contains table handlers for fnd_setid_reference_entities table.
Fnd_setid_set_groups package
This package contains table handlers for fnd_setid_set_groups and fnd_setid_set_
group_members tables.
Fnd_setid_utility package
This package contains the following utilities:
isValid
/**
* Returns true if the given parameters are valid, false if not.
*
* @param referenceGroupName The reference group name
* @param setIdDeterminantType The determinant type which could be:
*
BU, RR, LE...
* @param setIdDeterminantValue The determinant value.
* @param setId The setid value.
* @return true or false.
*/
function isValid(X_REFERENCE_GROUP_NAME in varchar2,
X_DETERMINANT_TYPE in varchar2,
X_DETERMINANT_VALUE in varchar2,
X_SET_ID in number) return boolean;
getSetId
/**
* Returns the set ID corresponding to the specified determinant value, type,
* and reference group name. This method implements an LRU cache to speed
* up the lookup.
*
* @param setIdDeterminantValue The determinant value
* @param setIdDeterminantType The determinant type which could be:
*
BU, RR, LE...
* @param referenceGroupName the reference group name.
* @return the corresponding set ID value.
*/
function getSetId(X_REFERENCE_GROUP_NAME in varchar2,
X_DETERMINANT_TYPE in varchar2,
X_DETERMINANT_VALUE in varchar2) return number;
getReferenceGroupName
/**
* Returns the reference group name based on a given reference entity name.
*
* @param referenceEntityName The name of the table to obtain
*
the reference group for
* @return the corresponding reference group name
*/
function getReferenceGroupName(X_REFERENCE_ENTITY_NAME in varchar2) return
varchar2;
8-7
isValidSet
/**
* Returns true if the set ID exists in the FND_SETID_SETS table,
* false if not
*
* @param setId The setId value
* @return Boolean
*/
function isValidSet(X_SET_ID in number) return Boolean;
You specify which setID pattern to use: row striping, row striping with
common rows, or setID subscription.
In the case of the setID subscription pattern, you specify the subscription table
name.
You make sure the attribute corresponding to setID is named SetId, and
specify the determinant type as SET.
You make sure that any view objects built on the reference entity include the
SetId attribute.
For more information about setID partitioning patterns, see Section 8.1.3.1,
"Partitioning Patterns".
On the transactional entities that will use the shared reference data
On foreign keys that point to shared reference entities, you indicate which
determinant attribute drives the set of that reference entity.
Determine which reference entities you want to partition for sharing, and
set-enable them by adding a SET_ID column.
Generate ADF Business Components entity objects for your set-enabled reference
entities and transactional entities. Make sure that your entity objects extend from
Oracle Applications base classes (if available) under
oracle.apps.fnd.applcore.oaext.model.
For more information, see the "Creating a Business Domain Layer Using Entity
Objects" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
Generate ADF Business Components entity associations for all of your entity
objects.
The determinant on the transactional entity that controls the setID of a shared
reference entity.
The Reference Groups have been defined by teams and approved through the
SetID Design Intent Repository process, then seeded in the standard reference
groups table.
All set-enabled lookup types have been identified and approved through the
SetID Design Intent Repository process, and then properly seeded in the
standard lookup types table.
After building an entity object for a shared reference entity, you annotate the entity
object.
To annotate the reference entity object:
1. Double-click the entity object to access its properties, as shown in Figure 82.
8-9
2.
In the Applications section of the Property Inspector, specify the name of the setID
reference group to which the entity object belongs.
For more information, see Section 8.1.3.2, "Reference Groups".
3.
Specify the setID pattern that the reference entity should use. There are three setID
partitioning patterns. Choose one of these patterns based on your business
requirements:
Subscription
When you select the SUBSCRIPTION pattern, the SetID Reference Table Pattern
field appears. Specify the subscription table to use.
The primary key columns of the setID subscription table
must be named the same as those in the reference entity, and the setID
column must be named SET_ID.
Important:
For more information about these options, see Section 8.1.3.1, "Partitioning
Patterns".
4.
In the entity object attributes, ensure that the entity object setID attribute that
corresponds to the SET_ID database column is named SetId, as shown in
Figure 83.
Make sure a destination accessor is generated for the association. ADF Business
Components will not honor the association if you do not generate a destination
accessor.
Because these reference entities are non-composite, you should not generate
source accessors.
2.
Table 81
Code
Determinant Type
AB
Asset Book
BU
Business Unit
CST
Cost Organization
PU
Project Unit
SET
Notes:
3.
For foreign keys that are setID enabled, specify the determinant attribute that
drives each foreign key reference, as shown in Figure 85.
The default value of the setID determinant attribute is the default determinant
type of the reference entity group targeted by the association that is defined for the
foreign key.
If the determinant value is not directly available on the
transaction table, you must create a transient attribute to model it, and
ensure that the attribute is correctly populated.
Note:
Attention:
8.2.5 How to Define a Key Exists Validator for Shared Reference Entities
The key exists validator will include the mapping of the foreign key attributes in the
transactional entity to the corresponding attributes in the reference view accessor.
If an attribute in your transactional entity was defined with
null values allowed, the validator that you create will skip that
attribute, and the end user will receive no indication of any problem.
To ensure that the attribute is validated, you must edit the attribute
and select the Mandatory checkbox in the attribute properties.
Caution:
On the Attributes tab, select the foreign key attribute and add a validation rule.
The Edit Validation Rule page appears, as shown in Figure 86.
3.
4.
On the Rule Definition tab, select ViewAccessor as the validation target type.
5.
Select the entity object lookup code attribute on the left-hand list, and the
corresponding view accessor validation target lookup code attribute on the
right-hand list.
6.
7.
Note:
8.
In the Triggering Attributes section, select the determinant attribute from the
left-hand list and shuttle it to the right-hand list.
9.
2.
3.
4.
In the Updatable section, select Never, then click OK to create the transient
attribute.
5.
On the Java tab, generate or edit a Java class for the transaction entity object.
6.
Because the setID value is computed at runtime based on the values of the
reference group name, determinant type and determinant value, you must modify
the transaction entity object's Java code to return the setID value at runtime.
Open the transactional EOImpl class and edit the getter method of your transient
setID attribute to pass in the corresponding foreign key attribute name. For
example:
/** This method gets the attribute value for TransientSetIdAttr, using the
alias name TransientSetIdAttr.
*/
public Long getTransientSetIdAttr() {
return this.getSetId("SalaryCode");
//"SalaryCode" is the foreign key attribute name on the WorkerAssignments
transactional entity
}
Integrating SetID Task Flows into Oracle Fusion Functional Setup Manager
2.
3.
Select an attribute from the view accessor to validate against, and ADF Business
Components will automatically add that attribute to the list of return values.
4.
Optionally, you can specify additional attributes to be returned to the master row
when an LOV entry is selected.
5.
Optionally, you can customize the LOVs UI hints by clicking Edit List UI Hints to
access the List UI Hints dialog.
8.3 Integrating SetID Task Flows into Oracle Fusion Functional Setup
Manager
Every application registers task flows with a product called Oracle Fusion Functional
Setup Manager. Functional Setup Manager provides a single, unified user interface that
enables implementers and administrators to configure all Oracle Fusion applications
by defining custom configuration templates or tasks based on their business needs.
The Functional Setup Manager UI enables customers and implementers to select the
business processes or products that they want to implement. For example, an HR
application can register setup activities like "Create Employees" and "Manage
Employee Tree Structure" with Functional Setup Manager.
There is an application task flow for managing reference data sets, and one for
managing reference data set assignments. To make these task flows available to
application developers, implementers or administrators, you can register the
appropriate task flow with Functional Setup Manager, using the parameters listed for
Managing Reference Data with SetIDs 8-17
Integrating SetID Task Flows into Oracle Fusion Functional Setup Manager
Task Flow
Name
Parameters Passed
Behavior
Manage
Reference
Data Sets
/WEB-INF/oracle/apps/fnd/applcore
/setid/publicUi/flow/ManageSetIdS
etsTF.xml#ManageSetIdSetsTF
Manage
Reference
Data Set
Assignmen
ts
/WEB-INF/oracle/apps/fnd/applcore
/setid/publicUi/flow/ManageSetIdA
ssignmentsTF.xml#ManageSetIdAssig
nmentsTF
pageTitle='titlestring'
determinantType=type
To optionally restrict the page to assignments
for a single reference group:
referenceGroupName=name
To optionally specify a page heading for the
task flow:
pageTitle='titlestring'
For more information about task flows, see the Oracle Fusion Applications Common
Implementation Guide.
9
Using Oracle Fusion Middleware Extensions
for Oracle Applications Base Classes
This chapter describes the Oracle Fusion Middleware extensions for Oracle
Applications base classes that extend the features of standard ADF Business
Components classes.
The chapter includes the following sections:
TL (translatable) table
WHO column
PL/SQL entity
FND services
Unique ID
Data security
Document sequencing
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-1
The base classes extend ADF Business Components Entity, EntityDef, ViewObject,
ViewRow, and ApplicationModule implementation classes.
The base classes provided by Oracle Fusion Middleware extensions are the following:
OAApplicationModuleImpl
OAEntityImpl
OAEntityDefImpl
OAViewObjectImpl
OAViewRowImpl
OAViewCriteriaAdapter
For each row in the base table, there will be as many rows in the translation table as
there are installed languages. The translation table's primary key is made up of the
foreign key to the base table and a language column, which may be viewed as a
foreign key to the FND_LANGUAGES table.
The translation table is fully populated. This means that rows for all installed
languages are inserted even if the actual translations for these languages are not yet
available. The logic, which maintains multi-language entities, is responsible for
ensuring that the translation rows are inserted, updated, or deleted as required to meet
the "fully populated" requirement. Translations, which have not been supplied, must
be defaulted from one of the available translations. As updates occur to supply
missing translations, the default values will be converted to true translations.
Since applications are run in a single language for any given user session, a convenient
view is provided for the multi-language entities, which joins the base table and
translation table and filters translations to the runtime language. This is the
Multi-language View. This view uses the userenv ('LANG') expression to select the
correct translation based on the session language, which usually comes from the NLS_
LANG environment variable.
The following extensions support TL tables:
OAEntityImpl
OAViewRowImpl
As a developer, you can use multi-language extensions to deal with only one entity
that contains both translatable and non-translatable attributes, instead of having to
deal with two entities, one for the base table and one for the translation table.
Whenever an entity is created, the extensions ensure that the TL entities are also
created for every installed language in the environment.
Whenever an insert is made into the base table or the table is updated, the same
operations must also be performed on the corresponding TL table. Behind the scenes,
the extensions override the appropriate ADF Business Components methods, such as
create() and setAttribute(), to ensure that the TL table is populated correctly.
The extensions also enable you to work with only one ADF Business Components
entity object at runtime for a multi-language database entity, and shield you from the
two underlying tables (base and multi-language) that hold the data. You will see no
inherent difference between a multi-language entity and a standard one. In addition,
the extensions allow you to define an entity as multi-language in a JDeveloper design
time environment, and provide any additional metadata for such that entity.
The same set of APIs also will be provided on the AViewRowImpl object, since it also
would have the same characteristics of a row.
Task 3, "Associate the _VL view and _TL table entity objects"
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-3
Note:
1.
2.
3.
4.
Verify that this extends OAEntityImpl like any other entity object.
5.
Add whatever validation logic you need for this entity and its attributes.
The translatable values are unlikely to need any special validation.
Note:
2.
3.
4.
You could use the entity Property Inspector to set this property, as shown in
Figure 92.
Figure 92 Entity Property Inspector
Follow the standard association object naming convention that describes the entity
relationships. For example, ItemsToTranslation.
2.
3.
4.
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-5
Select the base entity as the source and the _TL entity as the destination.
Since the Applications Core OAEntityImpl class overrides the remove() method
on the EntityImpl class to handle Translation rows deletion, Cascade Delete is not
required.
6.
Note:
Always use the base entity object created for the _VL view. For example,
ItemsDemoEO.
Do not use the _Translation entity object ItemsDemoTranslationEO directly. For
the purpose of any code that needs to access your translatable entity, you should
treat the base entity object as the only entity object. Coordination between the base
and Translation entities is handled automatically and the Translation entity should
remain "invisible". Otherwise, you can treat your base entity object like any other
entity object.
2.
3.
Override doDML() for the base entity to do nothing. This is going to be a virtual
entity that does not have an underlying database table.
4.
Create the translation entity object and the composite association between the base
entity and the translation entity as you would in the regular scenario.
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-7
The Translation EO in this scenario alone must also include the non-translatable
attributes because the base entity's doDML() does nothing. If the translation entity
does not include non-translatable attributes, you might get exceptions saying the
attribute is not populated
5.
Mark all the non-translatable columns in the _TL entity, i.e., non-string fields and
non-primary keys, as explicitly translatable by setting OA Translatable to true in
the Applications section of the Property Inspector, as shown in Figure 95.
By default, only string fields (VARCHAR2 and its variants) are identified as
translatable automatically by the parent. Primary key changes on the entity are
also handled automatically by the framework. This means any numeric, date, or
other data type attributes that are not primary key need to have the OA
Translatable property set explicitly to true.
There is a slight downside to this approach as non-translatable columns (like
numbers and dates), technically, are being marked as translatable. However, this
approach is required in order to ensure attributes set on the base entity are
propagated to the TL entity; otherwise, you will get an "attribute not populated"
exception. This is needed because the base entity is virtual and the doDML()
method on the base entity is empty.
Column Name
Type
Null?
Description
CREATED_BY
VARCHAR2(64)
NOT NULL
CREATION_DATE
DATE
NOT NULL
LAST_UPDATED_BY
VARCHAR2(64)
NOT NULL
LAST_UPDATE_DATE
DATE
NOT NULL
LAST_UPDATE_LOGIN
VARCHAR2(32)
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-9
LastUpdatedBy - modified by
CreationDate - created on
CreatedBy - created by
9.3.2 What Happens with WHO Column at Design Time and Runtime
WHO column features provide the following design time and runtime support:
The extension supports the LAST_UPDATE_LOGIN column and ensures that the
other columns are populated correctly.
The LAST_UPDATED_BY and CREATED_BY columns are populated with a value
based on the user name, and not with the user GUID, a user ID, or a session ID. To
obtain the value to populate these columns in PL/SQL, use FND_GLOBAL.WHO_
USER_NAME. In Java, the CreatedBy and LastUpdatedBy attributes will normally
be populated automatically with the correct value by the base classes, or you can
also obtain the value from OAEntityImpl.getWhoUser().
History is provided for the Session ID of the user who last updated the row.
Proper shaping in the Oracle Fusion Applications Developer role to make this
history available.
TL table support and the ability to override the appropriate DML operation
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-11
3.
4.
Under PL/SQL, select Y from the OA PLSQL Entity dropdown menu, as shown in
Figure 98.
5.
Override the following methods for its DML operations and provide JDBC calls
when applicable:
void insertRow();
void updateRow();
void deleteRow();
Use the PL/SQL entity objects only if you have legacy PL/SQL code that
maintains all your transactions and validations. If you are working on a new
product and/or do not have a lot of PL/SQL legacy code, Applications Core
recommends the use of Java entity objects over PL/SQL entity objects.
6.
Call your PL/SQL insert, update, or delete procedure in your void insertRow();,
void updateRow();, or void deleteRow(); method without calling super().
7.
8.
9.4.3 What Happens with PL/SQL Entities at Design Time and Runtime
The extensions provide the following design time and runtime support:
Profile
Lookup
Message
Language
Application
Taxonomy
Data Security
Attachments
Oracle Fusion Middleware extensions provide an easy way to access these services
and to invoke them. Typically, the services are provided as application modules. An
application module serves as a container for the various view objects and provides
business-service-specific functionality.
The services listed above are provided as a service-specific application module. For
example, Profile functionality is made available in ProfileService.
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-13
Using Unique ID
Extend OAViewCriteriaAdapter and invoke super methods for use cases not
handled by the custom view criteria adapter.
2.
3.
Using Oracle Fusion Middleware Extensions for Oracle Applications Base Classes 9-15
10
Implementing Lookups
10
This chapter discusses how to use lookups for providing lists of values (LOVs) for
application end users to select from, and for performing validation of newly entered
data. It also discusses how to share lookup data across organizations by using setIDs
to partition the data into different sets of LOVs. Each organization can then maintain
its lookups in a common table, using LOVs specific to that organization.
This chapter includes the following sections:
Introduction to Lookups
Note:
A lookup type, which is a string identifier of a type that groups certain codes
together; for example, COLORS.
Within each lookup type, multiple lookup codes can be defined. Example 101
shows sample code for defining multiple lookup codes.
Example 101
A lookup code, which is a string identifier for a code within a type; for example, RED.
A set or setID (for set-enabled lookups), which identifies the reference data set to
which the lookup code belongs.
For more information about setIDs, see Chapter 8, "Managing Reference Data with
SetIDs".
Introduction to Lookups
Note:
A reference to a non set-enabled lookup can be implemented exactly like any other
foreign key reference, by specifying the lookup type in the view criteria. For set
enabled lookups, you must specify the following additional properties, but only to add
the indirection through the setID metadata:
Indicate the view application ID and lookup type for lookup code attributes.
Indicate the determinant attribute and determinant type, if the lookup type is
set-enabled.
The use of setID metadata allows for the use of generic lookup entity objects, because
the lookup type is automatically bound based on the metadata that you provide.
Each lookup type defines a set of lookup codes, and describes the intended usage of
that set of codes. Note the FND_LOOKUP_TYPES_VL table and ADF Business Components
objects are only meaningful when a VIEW_APPLICATION_ID is specified to choose the
view application. You should never use either the table or the view without supplying
the VIEW_APPLICATION_ID.
Product teams that own a view application must expose a pre-defined view for lookup
types, exposing only the lookup types appropriate to their view application.
Product teams that own a view application also are
responsible for providing the service, the loader, the UI, and the
database view.
Note:
If your product has no special validation requirements, you can place your lookups in
one of the central lookup views such as FND_LOOKUPS. However, if you define your
own view application, you must supply a database view to match it.
Lookup Values
Introduction to Lookups
The naming of the lookup objects can get confusing; the Lookups object is intended to
refer specifically to FND lookups. The Lookup Values object in the previous listing is
the generic object. The FND_LOOKUPS view is primarily used to store FND-specific
lookup values but is also used to store lookup values that are common across multiple
applications. For example. the "Yes/No" example given in the overview might be used
by multiple product teams, so to avoid duplication that code can be stored centrally in
FND_LOOKUPS.
This view extends from the FND_LOOKUP_VALUES_VL view, but only selects rows that
have VIEW_APPLICATION_ID = 0 and SET_ID = 0.
Common Lookups
Note:
This view extends from the FND_LOOKUP_VALUES_VL view, but only selects rows that
have VIEW_APPLICATION_ID = 3 and SET_ID = 0.
SetID Lookups
Entity Object: SetIdLookupPEO
Introduction to Lookups
This view is used to store lookup codes that are set-enabled. The meanings
corresponding to the given lookup code will vary depending on the value of the setID
determinant.
This view extends from the FND_LOOKUP_VALUES_VL view, but only selects rows that
have VIEW_APPLICATION_ID = 2.
Lookup Code
Description
User
Extensible
System
Extensible
System
Updating of start date, end date, and enabled fields is not allowed
3.
Define a database view to expose the lookup types included in your lookup view.
At a minimum your view must select from the base FND_LOOKUP_TYPES_VL
view, expose the internal name and the display name, and include "where VIEW_
APPLICATION_ID = my_application_id" in the where clause. In addition, if your
view is set enabled, the lookup types view must include the REFERENCE_
GROUP_NAME column. You are free to join additional tables, add additional
attributes, or add additional filters to the where clause as desired. A template for
the view might be:
select LOOKUP_TYPE,
MEANING DISPLAY_NAME,
REFERENCE_GROUP_NAME, /* Only if set enabled */
...
from FND_LOOKUP_TYPES_VL
where VIEW_APPLICATION_ID = my_application_id
and ...
4.
Define a database view to expose the lookup codes included in your lookup view.
At a minimum your view must select from the base FND_LOOKUP_VALUES_VL
view, expose the lookup type, the lookup code internal name, and the lookup code
display name, and include "where VIEW_APPLICATION_ID = my_application_id"
in the where clause. In addition, if your view is set enabled, the lookup values
view must include the SET_ID column as part of the primary key. You are free to
join additional tables, add additional attributes, or add additional filters to the
where clause as desired. A template for the view might be:
select LOOKUP_TYPE,
LOOKUP_CODE,
SET_ID, /* Only if set enabled */
MEANING,
...
from FND_LOOKUP_VALUES_VL
where VIEW_APPLICATION_ID = my_application_id
and SET_ID = 0 /* Only if not set enabled */
and ...
5.
This script registers required seed data, and must be run on every database
instance.
6.
Referencing Lookups
3.
On the View Accessors tab, add a view accessor. The View Accessors page
appears.
4.
Select a view object from the left-hand list and shuttle it to the right-hand list, then
specify an accessor name.
5.
Select the new view accessor and click Edit. The Edit View Accessor page appears.
6.
Select the view criteria to use (if available), specify an order-by, and provide the
bind parameter value.
All set-enabled view accessors are row sensitive (the
determinant on the master or transactional row affects the query);
therefore the Row-level bind values exist check box must always be
selected for set-enabled view accessors. For example, view accessors
to FND_SETID_LOOKUPS (set-enabled lookups cases) must have
Row-level bind values exist selected because the setID value may
change row by row and affect the validation result. Hence, the
ViewAccessor Row Set will need to be refreshed row by row.
Note:
7.
For a lookup definition where the rowset returned for a lookup type or lookup
code is expected to be less than approximately 100 rows, use a list validator. See
Section 10.4.1, "How to Define a List Validator".
For a lookup definition where the rowset returned for a lookup type or lookup
code is expected to significantly exceed 100 rows, use a key exists validator. See
Section 10.4.2, "How to Define a Key Exists Validator".
If an attribute in your transactional entity was defined with
null values allowed, the validator that you create will skip that
attribute, and the end user will receive no indication of any problem.
To ensure that the attribute is validated, you must edit the attribute
and select the Mandatory checkbox in the attribute properties.
Caution:
On the Validators tab, add a validation rule for the entity. The Edit Validation Rule
page appears, as shown in Figure 101.
3.
4.
On the Rule Definition tab, select the foreign reference column that is the lookup
code (for example, SalaryCode) as the attribute.
5.
6.
7.
From the Select View Accessor Attribute list, select LookupCode as the view
accessor validation target lookup code attribute.
8.
Note:
9.
In the Triggering Attributes section, select the determinant attribute from the
left-hand list and shuttle it to the right-hand list.
10. Optionally, on the Failure Handling tab, specify a failure error message.
11. Click OK to create the list validator for this lookup.
Create a new transient lookup type attribute to map to the LookupType attribute
on the reference entity, as shown in Figure 103.
3.
4.
Set the Value Type to Expression, and provide a constant value for the attribute.
5.
6.
In the Updatable section, select Never, then click OK to create the transient
attribute.
Implementing Lookups
10-11
3.
On the Rule Definition tab, select a Validation Target Type of View Accessor.
4.
Select the entity object lookup code attribute on the left-hand list, and the
corresponding view accessor validation target lookup code attribute on the
right-hand list.
Click Add to include the attribute pair on the mapping list.
5.
Select the entity object transient lookup type attribute on the left-hand list, and the
corresponding view accessor validation target lookup type attribute on the
right-hand list.
Click Add to include the attribute pair on the mapping list.
6.
Select the entity object transient setID attribute on the left-hand list, and the
corresponding view accessor validation target setID attribute on the right-hand
list.
Click Add to include the attribute pair on the mapping list.
7.
Note:
8.
In the Triggering Attributes section, select the determinant attribute from the
left-hand list and shuttle it to the right-hand list.
9.
10. Click OK to generate the key exists validator for this lookup.
11. Save your project.
2.
Annotate each lookup code reference with setID machinery metadata, as shown in
Figure 106.
Implementing Lookups
10-13
Integrating Lookups Task Flows into Oracle Fusion Functional Setup Manager
Figure 106 Lookup Type and View Application ID for a Lookup Code Reference
To specify an attribute for use as a lookup code reference, select the attribute in the
entity object editor. On the Applications tab of the Property Inspector.
3.
Specify the SetID View Application Id and SetId LookUp Type properties.
10.6 Integrating Lookups Task Flows into Oracle Fusion Functional Setup
Manager
Every Oracle application registers task flows with a product called Oracle Fusion
Functional Setup Manager. Functional Setup Manager provides a single, unified user
interface that enables implementers and administrators to configure all Oracle Fusion
applications by defining custom configuration templates or tasks based on their
business needs.
The Functional Setup Manager UI enables customers and implementers to select the
business processes or products that they want to implement. For example, an HR
application can register setup activities like "Create Employees" and "Manage
Employee Tree Structure" with Functional Setup Manager.
There are application task flows for managing common lookups, set-enabled lookups,
and standard lookups. To make these task flows available to application developers,
implementers or administrators, you can register the appropriate task flow with
10-14 Developer's Guide
Integrating Lookups Task Flows into Oracle Fusion Functional Setup Manager
Functional Setup Manager, using the parameters listed for each task flow in
Table 102. These taskflows can be used to manage lookups in the centrally defined
lookup views (FND_LOOKUPS, FND_COMMON_LOOKUPS, and FND_SETID_
LOOKUPS). All other lookup views (and any associated taskflows) are owned by
applications (as determined by the VIEW_APPLICATION_ID). Contact the owning
application for instructions on managing lookups in their lookup views.
Table 102
Task Flow
Name
Manage
Standard
Lookups
Parameters Passed
Behavior
/WEB-INF/oracle/apps/fnd/applcore
/lookups/publicUi/flow/
ManageStandardLookupsTF.xml#
ManageStandardLookupsTF
mode='search'
To restrict search mode to Standard
lookups belonging to a particular product
module:
mode='search'
moduleType='moduletype'
moduleKey='modulekey'
To invoke edit mode for a single lookup
type and its lookup codes:
mode='edit'
lookupType='lookuptype'
To optionally specify a page heading for
the task flow:
pageTitle='titlestring'
Manage
Set-Enabled
Lookups
/WEB-INF/oracle/apps/fnd/applcore
/lookups/publicUi/flow/
ManageSetEnabledLookupsTF.xml#
ManageSetEnabledLookupsTF
Implementing Lookups
10-15
Integrating Lookups Task Flows into Oracle Fusion Functional Setup Manager
Parameters Passed
Behavior
/WEB-INF/oracle/apps/fnd/applcore
/lookups/publicUi/flow/
ManageCommonLookupsTF.xml#
ManageCommonLookupsTF
mode='search'
To restrict search mode to Common
lookups belonging to a particular product
module:
mode='search'
moduleType='moduletype'
moduleKey='modulekey'
To invoke edit mode for a single lookup
type and its lookup codes:
mode='edit'
lookupType='lookuptype'
To optionally specify a page heading for
the task flow:
pageTitle='titlestring'
For more information about task flows, see the Oracle Fusion Applications Common
Implementation Guide.
11
Setting Up Document Sequences
11
This chapter describes how to set up document sequences, which uniquely number
documents, provide proof of completeness, and create audit trails.
This chapter contains the following sections:
Section 11.8, "Integrating Document Sequence Task Flows into Oracle Fusion
Functional Setup Manager"
number. With gapless numbering, no sequence numbers are lost due to incomplete
or failed document creation.
It is recommend that you choose this type only when gapless
numbering is essential, as it may affect the performance of your
system.
Note:
Term
Description
Document Sequences
Document sequences are owned by a product and can be assigned to categories that
belong to the same product as the sequence. Sequences can be automatic, manual, or
gapless, and are effective within a date range.
Document Sequence
Categories
Sequence Assignments
The user assigns a sequence for each category. The assignments are owned by
determinant type and determinant value and are effective within a date range.
A document sequence category is one of the rules you use to define which
documents a sequence assigns numbers to.
You can separately number each document sequence category by assigning a
different sequence to each category.
A document sequence category identifies the database table that stores documents
resulting from transactions your users enter. When you assign a sequence to a
category, the sequence numbers the documents that are stored in a particular table.
assignments of this document sequence. If a determinant type has been specified, then
each assignment of this document sequence must include a particular value (or
"determinant value") for this context. At runtime, only those document sequence
assignments with a determinant value matching the current value for this dimension
in the user's session context will be visible. If no determinant type is defined, then all
assignments are considered global and are always visible.
Table 112 shows the possible values for the determinant type.
Table 112
Name
LEDGER
Ledger
LE
Legal Entity
BU
Business Unit
Name
Null?
Type
DOC_SEQUENCE_ID
NOT NULL
NUMBER(18)
DOC_SEQUENCE_VALUE
NOT NULL
NUMBER(15)
DOC_SEQUENCE_
ASSIGNMENT_ID
NOT NULL
NUMBER(18)
CREATION_DATE
NOT NULL
TIMESTAMP(6)
CREATED_BY
NOT NULL
VARCHAR2(64 CHAR)
LAST_UPDATE_DATE
NOT NULL
TIMESTAMP(6)
LAST_UPDATED_BY
NOT NULL
VARCHAR2(64 CHAR)
LAST_UPDATE_LOGIN
ENTERPRISE_ID
VARCHAR2(32 CHAR)
NOT NULL
NUMBER(18)
/**
* Override of EntityImpl.postChanges() to handle document sequencing.
* If an entity attribute has been identified that it should be populated
* using a document sequence (in the Applications Property Inspector panel),
* then at this point in the entity life cycle, we will populate the attribute
* with a document sequence based on the inputs, provided the sequence method
* is automatic. If the document sequence is manual, we will validate the
* document sequence.
* See parent class for complete documentation
* @param e this Entity Object's transaction event.
* @see #validateDocSequence
* @see #getDocSequence
* @see EntityImpl#postChanges
*/
public void postChanges(TransactionEvent e){...}
/**
* Will populate the entity attribute with a document sequence in Automatic
* mode, based on the schema based properties being set on the attribute using
* Applications Property Inspector in the Entity Attribute editor in JDev for
* fnd:DOC_SEQUENCE (Document Sequence),
* fnd:DOC_SEQ_APPLICATION_ID (Application Id),
* fnd:DOC_SEQ_METHOD_CODE (Method Code),
* fnd:DOC_SEQ_CATEGORY_CODE (Category Code),
* fnd:DOC_SEQ_DETERMINANT_VALUE (Ledger Id),
* fnd:DOC_SEQ_DETERMINANT_TYPE
* fnd:DOC_SEQ_TXN_DATE (Transaction Date)
* Application Id, Method Code, Category Code, Ledger Id and Transaction Code,
* should be populated with valid Groovy expressions.
* The Groovy expressions when evaluated should return a Long for Application
Id,
* and Ledger Id, String for Method Code and Category Code, Timestamp for
Transaction Date fields.
*
* This method will be invoked by postChanges() method on the entity, when
* posting the data to the database.
*
* Override this if you want a different behavior/way of populating the document
sequence.
*
By default, the entity attribute property is not set because it is not a document
sequence field.
Fusion Middleware extensions also capture the additional metadata (as Groovy
expressions) needed to generate a document sequence. Table 114 lists the metadata
fields in the Property Inspector window and their descriptions.
Table 114
Additional Metadata
Field
Description
Application Id
The application ID. The Groovy expression should return an object of type Long.
Category Code
The document sequence category code. The Groovy expression should return an
object of type String.
Method Code
The document sequence method code. Select from the following: "A" (Automatic), "M"
(Manual), or null (both modes). The Groovy expression should return an object of
type String.
Description
Determinant Type
The determinant type to use for this document sequence. The Groovy expression
should return an object of type String.
Determinant Value
The determinant value to use for this document sequence. The Groovy expression
should return an object of type Long.
Transaction Date
The document transaction date. The Groovy expression should return an object of
type Timestamp.
declare
ret number;
begin
-- Define a new document sequence
ret := fnd_seqnum.define_doc_seq(
app_id
=> 222,
-- Application ID
docseq_name => 'MY_DOC_SEQUENCE', -- Unique Doc_Seq Name
docseq_type => 'A',
-- Sequence Type
('A'=automatic,'G'=gapless,'M'=manual)
msg_flag
=> 'Y',
-- Message Flag
init_value => 1,
-- Initial sequence value
start_date => sysdate,
-- Effective Start date
end_date
=> null
-- Effective End date
det_type
=> 'BU');
-- Determinant Type value
if (ret <> FND_SEQNUM.SEQSUCC) then
dbms_output.put_line('Fail: '||to_char(ret));
end if;
end;
Example 113
declare
ret number;
docseq_val number;
docseq_id number;
begin
-- Retrieve the next sequence value for an Automatic sequence
ret := fnd_seqnum.get_seq_val(
app_id
=> 222,
-- Application ID
cat_code
=> 'MY_CAT',
-- Category code
sob_id
=> 12345,
-- Determinant value
met_code
=> 'A',
-- Method Code ('A'=automatic/batch,
'M'=manual)
trx_date
=> sysdate,
-- Transaction date
seq_val
=> docseq_val,
-- Doc Seq value (output value for
automatic)
docseq_id
=> docseq_id);
-- Doc Seq ID (output)
if (ret <> FND_SEQNUM.SEQSUCC) then
dbms_output.put_line('Fail: '||to_char(ret));
else
dbms_output.put_line('Next sequence value is '||to_char(docseq_val));
end if;
end;
Example 114
declare
ret number;
docseq_val number;
docseq_id number;
begin
-- Verify a sequence value for an Manual sequence
docseq_val := 54321;
ret := fnd_seqnum.get_seq_val(
app_id
=> 222,
-- Application ID
cat_code
=> 'MY_CAT',
-- Category code
sob_id
=> 12345,
-- Determinant value
met_code
=> 'A',
-- Method Code ('A'=automatic/batch,
'M'=manual)
trx_date
=> sysdate,
-- Transaction date
seq_val
=> docseq_val,
-- Doc Seq value (output value for
automatic)
docseq_id
=> docseq_id);
-- Doc Seq ID (output)
if (ret <> FND_SEQNUM.SEQSUCC) then
dbms_output.put_line('Fail: '||to_char(ret));
else
dbms_output.put_line('Value '||to_char(docseq_val)||' is valid');
end if;
end;
Example 115
function define_doc_seq (
app_id
in number,
Integrating Document Sequence Task Flows into Oracle Fusion Functional Setup Manager
mod_id
docseq_name
docseq_type
msg_flag
init_value
p_startDate
p_endDate
det_type
p_audit
) return number;
in varchar2,
in fnd_document_sequences.name%TYPE,
in fnd_document_sequences.type%TYPE,
in fnd_document_sequences.message_
flag%TYPE,
in fnd_document_sequences.initial_
value%TYPE,
in date,
in date default NULL,
in fnd_document_sequences.determinant_
type%TYPE default NULL,
in boolean default true
Integrating Document Sequence Task Flows into Oracle Fusion Functional Setup Manager
Table 115
Manage Document
Sequence
Categories
/WEB-INF/oracle/apps/fnd/
applcore/docseq/ui/flow/Ma
nageDocSeqCategoriesTF.xml#
ManageDocSeqCategoriesTF
Parameters
Passed
mode='search'
[moduleType]
[moduleKey]
mode='edit'
applicationId
code
[pageTitle]
Manage Document
Sequences
/WEB-INF/oracle/apps/fnd/
applcore/docseq/ui/flow/Ma
nageDocSequencesTF.xml#Ma
nageDocSequencesTF
mode='search'
[moduleType]
[moduleKey]
mode='edit'
name
[pageTitle]
Behavior
Comments
For more information about task flows, see Oracle Fusion Applications Common
Implementation Guide.
12
Implementing Audit Reports
12
below the tree table, the administrator chooses to add the attributes that need to be
audited.
You also can set up the Fusion Middleware auditing as described in Figure 122.
Metadata
Two database schema tables, FND_AUDIT_WEBAPP_AM and FND_AUDIT_
ATTRIBUTES, hold metadata information that is required for Auditing.
WEBAPP
APPLICATION_MODULE
VARCHAR2(80)
VARCHAR2(240)
WEBAPP
VIEW_
OBJECT
VIEW_
ENABLED_ TABLE_
ATTRIBUTE FLAG
NAME
COLUMN_
NAME
Make sure every application has the webApp defined and set. This is done by
populating the Oracle Fusion Applications Functional Core (ASK) deployment tables.
These tables are populated at deployment time through Oracle Fusion Functional Setup
Manager tasks.
The webApp value is your MODULE_SHORT_NAME from the ASK_MODULES table.
2.
Determine, for a given module, what are the applications modules that are to be
registered in the metadata table (fnd_audit_webapp_am) for audit purposes. You
can use the AuditServiceAM to register these applications modules. This service
allows data to be extracted and uploaded.
To use the AuditServiceAM, follow these steps:
If you do not have access to, or know how to use the AuditServiceAM, you can run
this SQL example (using appropriate values).
describe fnd_audit_webapp_am;
insert into fnd_audit_webapp_am values ('ApplCoreCRMDemo',
'oracle.apps.fnd.applcore.crmdemo.model.CrmDemoAM', sysdate, 'pjl', sysdate,
'pjl', 'pjl',1);
commit;
select * from fnd_audit_webapp_am;
3.
In the list that is displayed on the right, scroll down to select the property
Enable Audit and set its value to Y, as shown in Figure 121.
Note: If your base table is enabled for multi tenant, make the same changes for the
shadow table.
4.
5.
6.
Determine which attributes of each business object you do want to audit and
which ones you do not want to audit. By default:
<Entity
xmlns="http://xmlns.oracle.com/bc4j"
xmlns:fnd="http://xmlns.oracle.com/apps/entityview"
...
<ViewAttribute
Name="Attribute1"
IsUpdateable="false"
PrecisionRule="true"
EntityAttrName="Attribute1"
EntityUsage="AttributeEO"
AliasName="ROWID">
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_ATTR_ENABLED
Value="false"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
<ViewAttribute
Name="Attribute2"
IsUpdateable="false"
PrecisionRule="true"
EntityAttrName="Attribute2"
EntityUsage="AttributeEO"
AliasName="ROWID">
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_ATTR_ENABLED
Value="true"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
7.
The following shows an example for an attribute. Set the Label property under the
UI Hints in the property inspector for an attribute.
<ViewAttribute
Name="TableName"
PrecisionRule="true"
EntityAttrName="TableName"
EntityUsage="FndAuditAttributesEO"
AliasName="TABLE_NAME">
<Properties>
<SchemaBasedProperties>
<LABEL
ResId="TableName_LABEL"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
8.
users may not be able to search down to just one item, they can see the context
values to determine the ones in which they are interested.
<ViewAttribute
Name="TableName"
IsUnique="true"
IsNotNull="true"
PrecisionRule="true"
EntityAttrName="TableName"
EntityUsage="FndTablesEO"
AliasName="TABLE_NAME">
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_USER_KEY
Value="true"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
The user key can be something other than a straight value. This is accomplished
by allowing more tags to be used with the FND_AUDIT_USER_KEY tag:
<fnd:FND_AUDIT_USER_KEY Value="true"/>
<fnd:FND_AUDIT_FK_VIEWOBJECT Value=" "/>
<fnd:FND_AUDIT_FK_DISPLAYATTR Value=" "/>
<fnd:FND_AUDIT_FK_WHEREATTR Value=" "/>
<fnd:FND_AUDIT_FK_WHEREATTR_ADDL Value=""/>
<fnd:FND_AUDIT_VALUE_ADDL Value=" "/>
<fnd:FND_AUDIT_USERKEY_LKP_COND Value=" "/>
Example
<fnd:FND_AUDIT_USER_KEY Value="true"/>
<fnd:FND_AUDIT_FK_VIEWOBJECT Value="abc.PersonVO"/>
<fnd:FND_AUDIT_FK_DISPLAYATTR Value="PersonName"/>
<fnd:FND_AUDIT_FK_WHEREATTR Value="PersonId"/>
<fnd:FND_AUDIT_USERKEY_LKP_COND Value="SELECT PERSON_ID FROM PERSONS WHERE
PERSON_NAME LIKE ?"/>
9.
10. If needed, configure context descriptive attributes to show context attributes that
</ViewObject>
This works the same as Configure Attribute Lookup Based on the FND_
LOOKUPS table, but is not limited to the FND_LOOKUPS table.
<ViewObject ...
<ViewAttribute
Name="OWNER"IsNotNull="true"PrecisionRule="true"EntityAttrName="Owner"EntityUsa
ge="ServiceRequestsEO"AliasName="Owner">
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_FK_VIEWOBJECT Value=" "/>
<fnd:FND_AUDIT_FK_DISPLAYATTR Value=" "/>
<fnd:FND_AUDIT_FK_WHEREATTR Value=" "/>
<fnd:FND_AUDIT_FK_WHEREATTR_ADDL Value=""/>
either <fnd:FND_AUDIT_VALUE_ADDL Value=" "/>
or <fnd:FND_AUDIT_KEYATTR_ADDL Value=""/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
</ViewObject>
12. If needed, define View Criteria on Business Objects to filter the display of view
objects. For instance, a table might be shared by three applications, and you need
to filter based on only one of the applications.
Simple query-based View Criteria:
<ViewObject ...
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_VIEWCRITERIA_DBOBJECT Value=""/>
<fnd:FND_AUDIT_VIEWCRITERIA_CONDITION Value=""/>
</SchemaBasedProperties>
</Properties>
</ViewObject>
Product teams may want to write certain attributes to the shadow table all the
time, even if the attribute is not enabled for auditing. This could be because Virtual
Private Datasource policy is set up on the attribute, or the attribute participated in
a WHERE condition. This sample code shows how to enable force writing of the
attributes:
<ViewAttribute
Name="TableName"
IsUnique="true"
IsNotNull="true"
PrecisionRule="true"
EntityAttrName="TableName"
EntityUsage="FndTablesEO"
AliasName="TABLE_NAME">
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_FORCE_WRITE
Value="true"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
If the property value is set to "true," and the attribute is not enabled for audit,
it will not appear in the audit reports (unless it also is defined as the user key,
context attribute, and so on).
If the property value is set to "true," and the attribute is enabled for audit, it
will only appear when the value changes.
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_FORCE_WRITE
Value="true"/>
</SchemaBasedProperties>
</Properties>
Note that when a search is conducted on a view object, then the search result will
include rows from even the child view objects.
14. If needed, exclude a view object from a search in the Audit Report.
The Audit Reports UI contains a search query panel in which a user can select a
particular Product from the Product LOV and then filter the search further by
selecting a view object from the Business Object LOV.
The fnd:FND_AUDIT_REPORT_EXCLUDE audit annotation provides the ability
to exclude a particular view object from the Business Object LOV, even if it may be
marked as auditable. This is required for use cases in which a view object without
the context of its parent will not make sense, so developers can expose the parent
object and hide the children.
<ViewObject
xmlns="http://xmlns.oracle.com/bc4j"
xmlns:fnd="http://xmlns.oracle.com/apps/entityview"
...
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_ENABLED
Value="true"/>
<fnd:FND_AUDIT_REPORT_EXCLUDE
Value="true"/>
</SchemaBasedProperties>
Implementing Audit Reports 12-9
</Properties>
15. If needed, configure custom display names for Context attribute names.
The custom display name of the Context attribute name in an Audit Report can be
configured by using the annotation fnd:FND_AUDIT_CONTEXT1_LABEL_ID.
The value provided to this annotation must be a resource ID in the resource
bundle of the view object in which these context annotations are defined. If the
annotation is not used, then the display name of the context view attribute itself is
displayed in the Audit Report.
<ViewObject ...
<Properties>
<SchemaBasedProperties>
<fnd:FND_AUDIT_CONTEXT1_VIEWOBJECT Value=""/>
<fnd:FND_AUDIT_CONTEXT1_DISPLAYATTR Value=""/>
<fnd:FND_AUDIT_CONTEXT1_WHEREATTR Value=""/>
<fnd:FND_AUDIT_CONTEXT1_KEYATTR Value=""/>
<fnd:FND_AUDIT_CONTEXT1_LABEL_ID Value=""/>
</SchemaBasedProperties>
</Properties>
</ViewObject>
The custom display name can be configured to each Context attribute by using the
FND_AUDIT_CONTEXT2_LABEL_ID and FND_AUDIT_CONTEXT3_LABEL_ID
annotations.
16. If needed, configure lookups on the User Key attribute.
A Foreign Key lookup can be configured on a User Key attribute. Configure a User
Key attribute as described in step 8. Then configure a Foreign Key lookup as
described in step 11. Include this annotation at the view object level to derive a
User Key from the lookup value while a Description search is performed.
<ViewObject ...
<Properties>
<SchemaBasedProperties>
....
<fnd:FND_AUDIT_USERKEY_LKP_COND Value="<condition>"/>
</SchemaBasedProperties>
</Properties>
</ViewObject>
Example
Assume that the PersonId attribute is defined as a User Key, and Foreign Key
lookup is defined on the User Key, as shown here:
<fnd:FND_AUDIT_FK_VIEWOBJECT Value="abc.PersonVO"/>
<fnd:FND_AUDIT_FK_DISPLAYATTR Value="PersonName"/>
<fnd:FND_AUDIT_FK_WHEREATTR Value="PersonId"/>
</ViewObject>
17. If needed, you can hide a view object under an application module in the Audit
Setup UI
If the view object contains the audit annotation <fnd:FND_AUDIT_ENABLED
Value="true"/>, it will be displayed in the Setup UI. However, there are cases in
which the view object that is owned by a different team is present under the
application module and the user is not interested in seeing it under the application
module in the Setup UI.
For example, when Oracle Fusion CRM creates custom objects, it also creates an
Attachment object as its child, by default. However, they do not want to see the
Attachment object in the Setup UI. Since the Attachment view object is an FND
object and is not owned by Oracle Fusion CRM, there is no way for them to
remove the fnd:FND_AUDIT_ENABLED annotation from it.
The annotation shown here can be specified in the application module which is
registered for audit in the fnd_audit_webapp_am table. The user is expected to
provide a comma-separated list of all view object names that is present in the Data
Model of the application module and needs to be hidden in the Audit Setup UI.
With this, in place the listed view objects and their children, if any, will be hidden.
<AppModule...
<Properties>
...
<CustomProperties>
<Property Name="fnd:FND_AUDIT_SETUP_HIDE_VIEWOBJECT_LIST"
Value =
'oracle.apps.fnd.applcore.audit.setup.view.FndTablespacesVO'/>
</CustomProperties>
<Properties>
</AppModule>
18. If needed, support audit-specific Data Security view criteria in a view object
Audit considers the Data Security privilege for Business Object instances when
specified in application modules (using view criteria in the format of FNDDS_
privilegeNameobjectName_objectAlias) or if specified at the Entity level by
enabling the "read" privilege in the Security section.
If, for any reason, this cannot be done, audit supports the annotation shown here
that allows the Data Security privilege to be specified in the view object. Audit
History will consider this view object-level privilege as first priority.
<ViewObject ...
<Properties>
<SchemaBasedProperties>
....
<fnd:FND_AUDIT_DS_VIEWCRITERIA
Value="FNDDS__read__FND_CRM_CASES__QRSLT,FNDDS__read__FND_CRM_CASES__
CasesEO"/>
</SchemaBasedProperties>
</Properties>
</ViewObject>
19. If needed, there is audit support for PL/SQL-based Data Manipulation Language
(DML) operations
Audit maintains a history of changes done to business objects in Oracle Fusion
Applications.
12-11
p_audit_data IN tt_columns_data);
Coding Steps
If the table is audited and the DML type is INSERT for the base table, call the
PL/SQL API, passing in all the values as new values.
declare
tt FND_AUDIT_UTIL.tt_columns_data;
p_base_table_name varchar2(30);
begin
p_base_table_name := 'FND_LOOKUP_TYPES';
if (FND_AUDIT_UTIL.is_table_audited(p_base_table_name) = 'false') then
return;
end if;
tt(1).column_name := 'CUSTOMIZATION_LEVEL';
tt(1).column_type := 'VARCHAR2';
tt(1).new_data.varchar2_value := 'U';
tt(2).column_name := 'ENTERPRISE_ID';
tt(2).column_type := 'NUMBER';
tt(2).new_data.NUMBER_value := '0';
tt(3).column_name := 'LOOKUP_TYPE';
tt(3).column_type := 'VARCHAR2';
tt(3).new_data.varchar2_value := 'TEST11';
tt(4).column_name := 'MODULE_ID';
tt(4).column_type := 'VARCHAR2';
tt(4).new_data.varchar2_value := '40B3FA7250D19380E040449823C67A1A';
tt(5).column_name := 'VIEW_APPLICATION_ID';
tt(5).column_type := 'NUMBER';
tt(5).new_data.NUMBER_value := '0';
tt(6).column_name := 'CREATED_BY';
tt(6).column_type := 'VARCHAR2';
tt(6).new_data.varchar2_value := 'ADMIN';
tt(7).column_name := 'LAST_UPDATED_BY';
tt(7).column_type := 'VARCHAR2';
tt(7).NEW_data.varchar2_value := 'ADMIN';
tt(8).column_name := 'CREATION_DATE';
tt(8).column_type := 'TIMESTAMP';
tt(8).new_data.timestamp_value := sysdate-10;
tt(9).column_name := 'LAST_UPDATE_DATE';
tt(9).column_type := 'TIMESTAMP';
tt(9).new_data.timestamp_value := sysdate-10;
12-13
FND_AUDIT_UTIL.CREATE_AUDIT_ROW(
p_base_table_name,
'INSERT',
tt);
end;
If the table is audited and the DML type is UPDATE, call the PL/SQL API to get
a list of audit-enabled attributes.
TYPE tt_column_names
FND_AUDIT_UTIL.get_audited_columns(
p_base_table_name in varchar2(30) // input parameter - base table name
) return tt_column_names
If any column that is updated in the current transaction is in the list returned
from get_audited_columns, get the value for all the other columns in the table
and call the PL/SQL API. Note that you need to pass in values (old and new)
for all the columns returned from the get_audited_columns() function, and
also for all the who columns, even if the values have not changed.
declare
tt FND_AUDIT_UTIL.tt_columns_data;
p_base_table_name varchar2(30);
col_list FND_AUDIT_UTIL.tt_column_names;
l_col_change_found varchar2(30);
begin
p_base_table_name := 'FND_LOOKUP_TYPES';
l_col_change_found := 'false';
if (FND_AUDIT_UTIL.is_table_audited(p_base_table_name) = 'false') then
return;
end if;
col_list := FND_AUDIT_UTIL.get_audited_columns(p_base_table_name);
-- assuming here that only customization_level has changed
FOR i IN 1 .. col_list.count LOOP
IF (col_list(i) = 'CUSTOMIZATION_LEVEL') THEN
l_col_change_found := 'true';
END IF;
END LOOP;
--if you dont have all the values, query the rest of the values from your
base table
--then pass the same value for old and new value.
--if the old or new value is blank, audit code will assume that the value
has been cleared out.
if (l_col_change_found := 'true') THEN
tt(1).column_name := 'CUSTOMIZATION_LEVEL';
tt(1).column_type := 'VARCHAR2';
tt(1).old_data.varchar2_value := 'U';
tt(1).new_data.varchar2_value := 'S';
tt(2).column_name := 'ENTERPRISE_ID';
tt(2).column_type := 'NUMBER';
tt(2).old_data.NUMBER_value := '0';
tt(2).new_data.NUMBER_value := '0';
tt(3).column_name := 'LOOKUP_TYPE';
12-14 Developer's Guide
tt(3).column_type := 'VARCHAR2';
tt(3).old_data.varchar2_value := 'TEST11';
tt(3).new_data.varchar2_value := 'TEST11';
tt(4).column_name := 'MODULE_ID';
tt(4).column_type := 'VARCHAR2';
tt(4).old_data.varchar2_value :=
'40B3FA7250D19380E040449823C67A1A';
tt(4).new_data.varchar2_value :=
'40B3FA7250D19380E040449823C67A1A';
tt(5).column_name := 'VIEW_APPLICATION_ID';
tt(5).column_type := 'NUMBER';
tt(5).old_data.NUMBER_value := '0';
tt(5).new_data.NUMBER_value := '0';
tt(6).column_name := 'CREATED_BY';
tt(6).column_type := 'VARCHAR2';
tt(6).old_data.varchar2_value := 'ADMIN';
tt(6).new_data.varchar2_value := 'ADMIN';
tt(7).column_name := 'LAST_UPDATED_BY';
tt(7).column_type := 'VARCHAR2';
tt(7).old_data.varchar2_value := 'ADMIN';
tt(7).new_data.varchar2_value := 'APPLICATION_ADMINISTRATOR';
tt(8).column_name := 'CREATION_DATE';
tt(8).column_type := 'TIMESTAMP';
tt(8).old_data.timestamp_value := sysdate -10;
tt(8).new_data.timestamp_value := sysdate-10;
tt(9).column_name := 'LAST_UPDATE_DATE';
tt(9).column_type := 'TIMESTAMP';
tt(9).old_data.timestamp_value := sysdate -10;
tt(9).new_data.timestamp_value := sysdate;
FND_AUDIT_UTIL.CREATE_AUDIT_ROW(
p_base_table_name,
'UPDATE',
tt);
END IF;
end;
If the table is audited and the DML type is DELETE for the base table, call
PL/SQL API, passing in all the values (as old values) from the base table.
declare
tt FND_AUDIT_UTIL.tt_columns_data;
p_base_table_name varchar2(30);
begin
p_base_table_name := 'FND_LOOKUP_TYPES';
if (FND_AUDIT_UTIL.is_table_audited(p_base_table_name) = 'false') then
return;
end if;
tt(1).column_name := 'CUSTOMIZATION_LEVEL';
tt(1).column_type := 'VARCHAR2';
tt(1).old_data.varchar2_value := 'S';
12-15
tt(2).column_name := 'ENTERPRISE_ID';
tt(2).column_type := 'NUMBER';
tt(2).old_data.NUMBER_value := '0';
tt(3).column_name := 'LOOKUP_TYPE';
tt(3).column_type := 'VARCHAR2';
tt(3).old_data.varchar2_value := 'TEST11';
tt(4).column_name := 'MODULE_ID';
tt(4).column_type := 'VARCHAR2';
tt(4).old_data.varchar2_value := '40B3FA7250D19380E040449823C67A1A';
tt(5).column_name := 'VIEW_APPLICATION_ID';
tt(5).column_type := 'NUMBER';
tt(5).old_data.NUMBER_value := '0';
tt(6).column_name := 'CREATED_BY';
tt(6).column_type := 'VARCHAR2';
tt(6).old_data.varchar2_value := 'ADMIN';
tt(7).column_name := 'LAST_UPDATED_BY';
tt(7).column_type := 'VARCHAR2';
tt(7).old_data.varchar2_value := 'APPLICATION_ADMINISTRATOR';
tt(8).column_name := 'CREATION_DATE';
tt(8).column_type := 'TIMESTAMP';
tt(8).old_data.timestamp_value := sysdate -10;
tt(9).column_name := 'LAST_UPDATE_DATE';
tt(9).column_type := 'TIMESTAMP';
tt(9).old_data.timestamp_value := sysdate;
FND_AUDIT_UTIL.CREATE_AUDIT_ROW(
p_base_table_name,
'DELETE',
tt);
end;
You will notice that some have only an Audit Level drop-down list that lets you pick
Low, Medium or High levels. These are Oracle Fusion Middleware products that
generate event-based entries in the table that is read by the Audit system, and the user
just sets the granularity that is desired. (Refer to the product documentation and to the
online help for a description of how the levels work in each particular product.)
In the example figure, click the Configure Business Object Attributes button to
display the Configure Business Objects Attributes dialog. When it first displays, the
fields will be empty.
To populate the Objects list, open the Application drop-down list and select the name
of the application you want to audit. The example shown in Figure 123 uses the
Applications Core Setup application.
Figure 123 Selecting an Application to Audit
There are three buttons at the top of the Configure Business Object Attributes dialog:
Click Save to save your work and remain in the Audit Setup dialog.
Click Save and Close to save your work and exit the Audit Setup dialog.
Implementing Audit Reports
12-17
Click Cancel to cancel any changes you have made since the last Save action and
exit the Audit Setup dialog.
Objects List
The Objects list has three columns:
Audit
There is no limit to the number of levels that can be included in an audit.
You will notice that items with the same name are displayed and can be selected.
The item at the top of the tree is the root item; the other listed items of the same
name are reflections of the root item and are not separate. That is, if a view object
appears multiple times in the Setup list, there really is only one view object.
Selecting or deselecting any instance of that view object will select or deselect all
instances.
Example:
You pick a view object and select five of its attributes to audit and save. If you then
choose the same view object, but somewhere else in the setup UI, it will have those
five attributes already selected. Now select two more, so that there are seven
attributes selected. When you return to the first instance of the view object, it also
will show seven attributes selected.
Similarly, if you delete one of the five selected attributes, all instances of the
affected view object will show only four selected attributes.
Another way of saying this is "last edit wins."
Any item that is checked in the Audit column will have all its selected attributes
audited. Unless the view objects' Attributes list has been edited, the attributes that
will be audited are default attributes.
If you edit a view object to select specific attributes, the Audit box must still be
checked to audit the selected attributes. (You can edit the attributes, but that, by
itself, does not mean they will be included in an audit, unless the Audit box is
checked.)
Name
The names of the application modules and view objects.
Description
A brief description of the associated application module or view object.
Actions menu
The Actions menu provides the Synchronize option.
Attributes of objects that are being audited are tracked. On a patch or update, or if
customized attributes, such as flexfield attributes, have been added, they must be
tracked if they are meant to be included in the audit. That is, the attribute was
marked as <fnd:FND_AUDIT_ATTR_ENABLED Value="true"/>. Synchronize will do
this.
Note: Synchronization is carried out by product. That is, it will synchronize all
objects in the current product shown in the UI, if those objects have been selected
for audit at any time previously.
View menu
Use the View menu to select the columns you want to display, and to expand and
collapse entries in various combinations.
Click Save and Close to save your selections. Remember that your selections will not
be included in an audit unless the related Audit checkbox also is selected.
12-19
To perform a search, a Date value and either a User or Product value are required. Use
the Date picker to select the date, and the drop-down lists to select a User or a Product
or both. The search results can be further fine-tuned by using the Event Type, Business
Object and Description fields, and the Include child objects checkbox.
These parameters can be saved and recalled by selecting the
user-supplied name in the Saved Search drop-down list. See also"If the
search parameter set you are using is one that you expect to reuse,
click Save to display the Create Saved Search dialog that has these
options:"
Note:
Date. Select an operator, such as Equals, Before, After or Between, and click the
picker to display a calendar from which to choose a date.
User or Product or both.
When you use the drop-down to select a User, you will notice a Search link at the
bottom of the list. Click it to access all the available Users. The dialog, shown in
Figure 126, is displayed.
You can enter a name or part of a name in the User field and click Search. You also
can click Advanced to add a search operators drop-down list, as shown in
Figure 127.
Figure 127 User Name Operators
To select a user, highlight the name in the search results, shown in Figure 128, and
click OK.
Figure 128 Search Results for User
Event Type. Note that the first drop-down list always is set to Equals. Use the
second drop-down list to select any or a combination of the available types. You
also can select All.
For Oracle Fusion applications, the Types are Object Data Insert, Object Data
Update, and Object Data Delete.
12-21
For Oracle Fusion Middleware, the Type selection is dynamic and depends on the
selected Product.
Business Object Type. Note that this field applies only to Oracle Fusion
applications and not to Oracle Fusion Middleware.
Description. You can further limit the search results display by entering a string in
this field that matches a string in the Description column of the search results.
Include child objects. If there is a hierarchy of view objects, such as Opportunity
> Revenue Line > Revenue Line Split, and the search is done on Opportunity, it
only checks the Opportunity view object for changes. But if this option is checked,
it will search all children. So if an Opportunity has five Revenue Lines and each
has some Revenue Line Splits, then if anything in any of them changed, they also
would be reported.
When the necessary fields are filled-in, click Search to display the results in the Search
Results table.
Click Reset to clear all the fields so you can enter new search parameters.
If the search parameter set you are using is one that you expect to reuse, click Save to
display the Create Saved Search dialog that has these options:
Name
This option is mandatory.
This field defaults to showing the name that is displayed in the Saved Search field.
However, if the Saved Search displayed name is "My Recent Changes," the Name
field here will show "My Recent Changes copy."
Set as Default
Select this option to designate this named set of search parameters as the default
instead of My Recent Changes.
This option can be set and cleared by opening the Saved Search drop-down list
and selecting Personalize.
Run Automatically
Select this option to run this named set of search parameters automatically.
This option can be set and cleared by opening the Saved Search drop-down list
and selecting Personalize.
Actions menu
Export to Excel icon that duplicates the function of the Actions menu option of the
same name
Detach icon
Show Attribute Details checkbox. This option becomes active when the Business
Object Type field is populated and a search has been performed.
When this option is selected, it will expand a single row, which originally means
something in this object changed, to, for instance, 10 rows if 10 attributes changed.
Also, three columns are added to the table: Attribute, Old Value, and New Value.
Attribute contains the attribute name. An Old Value will be shown if there was an
old value. New Value shows the current value. A scroll bar will become available
at the bottom of the display so you can view all the columns.
Show Extended Object Identifier Columns checkbox. This option becomes active
only when the Show Attribute Details option is selected.
When this option is selected, three new pairs of columns are added to the Search
Results table: Context Name1 with Context Value1 through Context Name3 with
Context Value3. These are additional information to help identify the object. For
instance, if you need a 4-part key to uniquely identify an object, the Description
could be 1 and these 3 context values could be the remaining.
Note that when a search is conducted on a view object, the search result also will
include rows from the child view objects.
Actions Menu
The Actions menu has the Export to Excel option that is duplicated with the Export to
Excel icon. Select the menu option or click the icon to export all the entries in the
Search Results list to an Excel XLS file. When this option is selected, the standard Save
prompts will guide you through the process.
12-23
Part III
Part III
This part of the Developer's Guide discusses some of the Oracle Application
Development Framework (Oracle ADF) user interface features that you can
incorporate into your Oracle Fusion Applications.
The Getting Started with your Web Interface chapter provides information about how to
create a page and what the wizard settings should be. It also presents the basic
information that is necessary before creating the Application User Interface.
The Implementing the UI Shell, Implementing Search Functions in the UI Shell and
Implementing Additional Functions in the UI Shell chapters provides information about
the UI Shell and Navigator Menu components used to implement user interface
features in JDeveloper. The UI Shell is a page template whose contents are determined
by the menu metadata held in the Navigator Menu.
The Implementing UIs in JDeveloper with Applications Tables, Trees, and Tree Tables chapter
discusses the Applications Tables, Trees and Tree Tables components used to
implement user interface features in JDeveloper. Applications tables are UI components
that already contain an ADF table, a menu bar, a toolbar, and related popups.
Developers do not need to create and assemble all these components separately. The
Applications Tree component provides the basic capabilities that satisfy the
requirements specified in the Application UX designs. These include tree toolbar with
default buttons, facets for adding ADF tree, custom toolbar buttons, and so on, and
default implementations for tree actions. The Applications Tree Table can be added to a
page or page fragment using either the Component First or the Data First approach.
Both approaches launch a wizard that is intended to help you quickly define the
appropriate tree layout that adheres to the Applications UX standards.
The Implementing Applications Panels, Master-Detail, Hover, and Dialog Details chapter
discusses the Applications Panels, Master-Detail, Detail on Demand, and Dialog
Details components used to implement user interface features in JDeveloper.
Applications panels help you create specific UI components as part of the UI
Applications patterns. You must use Applications panels to standardize layout and
appearance for all your page forms and buttons, including read-only pages. The
Master-Detail composite is used in situations where the information is too large,
dynamic or complex to show in a flat table. The user can see the Master, or summary,
information in one area, and the corresponding details in a separate area. Dialog details
are appropriate for use when information must be accessed quickly and then
dismissed. The details are shown in a modeless dialog window.
The Implementing Attachments chapter provides guidelines for implementing
Attachments at design time in a quick and simple manner using Oracle Fusion
Middleware components. The Attachment component provides a declarative and
simple programming mechanism for you to add attachments to the UI pages that you
create for web applications. When added to a UI page, the component gives users the
ability to associate a URL, desktop file, repository file or folder, or text with a business
object, such as an expense report, contract, or purchase order.
The Organizing Hierarchical Data with Tree Structures chapter describes how to create,
update, and delete tree structures, trees, and tree versions, and how to develop
applications using trees. Oracle Fusion tree management allows data in Oracle
Applications to be organized into a hierarchical fashion, and allows Oracle
Applications customers to create tree hierarchies based on their specific data.
The Working with Localization Formatting chapter describes the Oracle applications
standards and guidelines for working with localization formatting. When developing
applications for international users, it is often necessary to format the display of
certain location-dependent data. In the context of JDeveloper and ADF, localization
requires implementing formatting patterns so as to properly display the data
according to local standards.
This part contains the following chapters:
Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
13
Getting Started with Your Web Interface
13
This chapter provides information that you may need before you begin developing
your web pages. It introduces the UI Shell page template and UI patterns and features
that are available in JDeveloper.
This chapter includes the following sections:
13-1
patterns are common flow or page designs that are used across all product families. By
using design patterns in all phases of product development, valuable development
time may be spent innovating other areas in the product, consistency is ensured across
the entire enterprise, and users only have to learn the interaction once with the
expectation that their experience will be the same in any product they encounter.
Dashboard
There are two types of dashboards: Home Based Dashboards and Transaction
Dashboards. A Home Based Dashboard consists of one or more tabs. Each tab is a
container for a set of configurable regions displaying content that a user may want to
monitor. Transaction Dashboards are built with a specific role in mind. The basic
building blocks are the individual regions. Every dashboard can choose which regions
it wants to include. In Figure 131, these are the Watchlist, Reports and Analytics,
Worklist, and Gallery. Each of these is built as Oracle Application Development
Framework (Oracle ADF) Bounded Task Flows.
Figure 131 Home Based Dashboard Example
Work Area
A Work Area, as shown in Figure 132, consists of a Regional Area, a Local Area and a
Contextual Area. Each area is intended to have content for a specific purpose.
Figure 132 Work Area example
The Regional Area is the collapsible region on the left of the page that contains a
column of panels that provides information and actions that drive the business process
that a work area supports. The Local Area is the focus of the users work. The contents
of it should contain all of the information and actions required to accomplish the task.
The Contextual Area is the collapsible region on the right-hand side of the page that is
filled with a column of panels. It provides additional space above the fold of the page
to present actions and information, based on the information and state of the local
area, that can assist the user in the task.
Designing Your UI
Your web user interface will be designed using the Oracle Fusion GPS concepts and
design patterns. Many of these designs are delivered through the Oracle Fusion
Middleware Extensions for Applications (Applications Core). Dashboards and Work
Areas are built using the UI Shell. A set of design-time wizards and components that
help support many of the Oracle Fusion GPS design patterns is also provided. These
components, with those provided by Oracle ADF and WebCenter, provide the basis for
all web interfaces.
Global Search
Navigation menus
Cross-application navigation
13-3
Enforcement of patterns.
Faster development.
Changes can be made to one component definition rather than to each instance in
every application.
Applications Tables
Applications Panels
Applications Master-Detail
Applications Tree
Applications Tables
Applications tables are UI components that already contain an ADF table, a menu bar,
a toolbar, and related popups. Developers do not need to create and assemble all these
components separately.
Applications Panels
Applications Panels help you create the following UI components as part of the UI
applications patterns:
Page title
Form title
You must use Applications Panels to standardize layout and appearance for all your
page forms and buttons, including read-only pages.
Applications Master-Detail
Master-Detail refers to the interaction of selecting an object from a master list, and
refreshing the details in an adjacent area. It is not the relationship of the data.
The Master-Detail composite is used in situations where the information is too large,
dynamic, or complex to show in a flat table. The user can see the Master, or summary,
information in one area, and the corresponding details in a separate area. This can be
achieved using different master and detail components, such as table, tree table, and
tree.
For instance, when the user selects an employee from the master table, the
corresponding employee details are displayed in the region below in a label/data
format.
Applications Detail On Demand
Dialog details are appropriate for use when information must be accessed quickly and
then dismissed. The details are shown in a modeless dialog window.
a title
standard buttons
data binding
design-time support
Facets for adding items such as ADF tree table and custom toolbar buttons
Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
13-5
14
Implementing the UI Shell
14
This chapter discusses the UI Shell page template used to build web pages, and the
components used to implement user interface features in Oracle JDeveloper
(JDeveloper), such as menus and task flows.
This chapter includes the following sections:
Section 14.4, "Controlling the State of Main and Regional Area Task Flows"
Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
The UI Shell for Applications User Experience (Applications UX) patterns provides a
system of containers that fulfill common layout and navigational requirements in a
structured, consistent manner. The UI Shell focuses on providing detailed design for
defining and organizing various types of navigation and other functionality such as
search and auxiliary information for Oracle Fusion Middleware alone.
Before You Begin:
You should be familiar with JDeveloper, be able to create and run JavaServer Faces
(JSF) pages, and be able to create an Oracle Application Development Framework
(Oracle ADF) task flow.
The four areas (refer to the circled numbers on the image) are:
1.
Global Area: The global area, across the full width at the top of the UI Shell, is
stable, consistent, and persistent for an individual user. It contains controls
that generally affect the contents of the other three areas. See Section 14.1.2.1,
"Global Area Standard Icons."
2.
Regional Area: The regional area is in the left-hand pane of the UI Shell. It has
controls and content that generally affect the contents of the local and
contextual areas. Tasks lists in the regional area automatically are bulleted to
make it clear when a line item wraps to the next line.
3.
Local Area: The local area is in the center of the UI Shell where users do their
work. It is the main work area and typically contains the transaction form with
the menus and controls that enable users to be productive. Controls in, and the
content or state of, the local area generally affect the contents of the contextual
area.
*
4.
Main Area: This term designates the combination of the local area and the
contextual area.
Contextual Area: The contextual area is in the right-hand pane of the UI Shell,
with controls and contents that generally are affected by controls in, or the
content or state of, the local area; although in specific cases the contextual area
can also affect the contents of the local area (causing a local-area reload).
Application designers, customers, and administrators can set the regional and
contextual areas as collapsed for specific applications. End users can expand those
areas at runtime.
If there is no content in the regional or contextual area, the area is collapsed and
the ability to expand it is disabled.
The contextual area is directly bound to the local area. The application developer
can bind the contextual area content to the local area such that each invocation of a
local area automatically causes a relevant contextual area in the correct state to
appear alongside the local area.
Home
Click this icon to return to the defined Home page. See Section 16.3,
"Implementing the Oracle Fusion Home Page UI."
Navigator
The Navigator, shown in Figure 1423, is rendered when the Navigator icon is
clicked on the UI Shell. See Section 14.5.1.2, "Displaying the Navigator."
Favorites takes the most recent task flow visited by a user (see Section 15.2,
"Implementing Recent Items") and adds it to the Favorites list.
Recent Items tracks a list of the last 20 task flows visited by a user. See
Section 15.2, "Implementing Recent Items."
Tags is a service that allows users to add tags to selected resources in Oracle
Fusion Applications to contribute to resources other users have visited. See
Section 15.1, "Implementing Tagging Integration."
Watchlist
Click the Watchlist icon to display a user-accessible UI that provides a summary of
items the user can track using shortcuts. See Section 15.3, "Implementing the
Watchlist."
Notification
Click the icon to display the Notification dialog shown in Figure 143.
Social
Click the Social icon to display Oracle Social Network conversations. See
Chapter 66, "Implementing Oracle Social Network Integration."
Notes:
Accessibility
The Accessibility icon appears on all pages. It will allow users to set their
accessibility preferences because the Personalization menu, which includes
preferences, is hidden for anonymous users.
Search
Click the icon to display the Global Search dialog shown in Figure 144.
Help
When you click the Help icon, it turns orange. Then, if there is context help on the
page, smaller orange icons will display, as shown in this figure.
Populating a UI Shell
You then click the one you want for the context help topics, as shown below.
Figure 146 Example of Context Help Links
If there is no context help available on the page, the main Help icon turns orange,
but no smaller icons are displayed.
To turn off Help, click the main icon again.
Populating a UI Shell
For more information about starting JDeveloper, see Chapter 2, "Setting Up Your
Development Environment."
To create a JSF page:
1.
2.
Choose File > New > Web Tier > JSF > JSF Page.
The Create JSF Page dialog is displayed, as shown in Figure 147.
3.
In the dialog:
Click OK.
Populating a UI Shell
4.
The new JSF page is displayed in the editor. Note that the page headers in the
Design view do not display exactly as they will at runtime.
This JSPX page is just the container for the UI Shell template.
All other page content, such as the regional, local, and contextual area
flows, and the dynamic task flows, are defined independently. At
runtime, the menu definition assembles the various parts. All task
flows are loaded into a page created with the UI Shell template by
configuring the Menu file. This is done to control the behavior and the
dynamic loading of task flows at runtime. It also creates the Navigator
and Task List menu. See Section 14.5, "Working with the Global Menu
Model" and Section 14.2.1.1, "Working with the Applications Menu
Model."
Note:
Now you can add components to the page. Table 141 lists the itemNode properties
that can be used for a JSF page. See Section 14.2.1.1, "Working with the Applications
Menu Model" for how to add a menu to the page.
Table 141
ItemNode Property
Property Value
Description
action
dataControlScope
String
isDynamicTabNavigation
True or False
id
Unique identifier
Populating a UI Shell
Property Value
Description
label
String
focusId
formUsesUpload
regionalAreaWidth
Numeric value
isRegionalAreaCollapsed
True or False
Populating a UI Shell
Right-click the adfc-config.xml file and choose Open to display the file in the
JDeveloper editor.
The adfc-config.xml file is located in the following location: <project_name> >
WEB INF.
2.
Drag pages from the Application Navigator to the adfc-config.xml file in the
editor.
View nodes that represent the pages or task flows are displayed in the editor.
When you drag the pages or task flows, they automatically are grouped into the
same menu.
3.
Populating a UI Shell
4.
Click Find Pages to populate the display with all the JSPX pages that have been
added to the adfc_config.xml file. As shown in Figure 149, pages that do not yet
have a menu associated with them will have a checkbox that defaults to being
selected, and pages that already have an associated menu are shown with a
checkmark to the right.
5.
Click OK to automatically create a menu file for each selected page and to update
the task flow with a managed bean.
Note: Menu files will follow the <focusViewId>_taskmenu.xml
naming standard. For example, the menu file for the Example.jspx file
will be /WEB-INF/menus/Example_taskmenu.xml.
The menu file is generated and placed into the following directory:
ViewController/public_html/WEB-INF/menus
The following are generated and appear in the adfc-config.xml file:
The new menu that contains your pages is now accessible from the Navigator
panel.
Populating a UI Shell
Figure 1410
2.
Enter a page fragment name, for example, you might enter def_main.jsff.
The file name should follow these patterns:
<Object><Function>.jsff
<Object>.jsff
The page name should convey the object it presents (an employee, a supplier,
an item, a purchase order, an applicant, and so on), and the function being
performed (search, promote, hire, approve, view). For some pages, the object
is sufficient.
For update or create pages, just the object is necessary (unless the create and
update pages are different as shown in the examples).
Never give pages step number names, such as PoCreateStep1.jsff or
PoCreateStep2.jsff. Always describe the page function, such as PoDesc.jsff
or PoLines.jsff.
b.
Note:
3.
Click OK.
The Local and Contextual area facets of the page fragment appear in the editor.
4.
Choose File > New > JSF > ADF Task Flow to create a default task flow.
Most applications will have multiple task flows for the
Regional, Local and Contextual areas. For instance, Figure 141, "UI
Shell Areas" shows 10 task flows.
Note:
The Create ADF Task Flow dialog shown in Figure 1411 is displayed.
14-11
Populating a UI Shell
Figure 1411
5.
Ensure that the JSF page fragment file is selected in the Application Navigator and
is displayed in the Edit view.
a.
b.
c.
In the Application Navigator, select an applicable task flow, such as the one
you created in Step 4, to add to the localArea. This should be an XML file
located under ViewController > Web Content > WEB-INF > oracle > apps >
application_name > ui > flow.
d.
Drag and drop the appropriate flow from the Navigator pane to immediately
following <f:facet name="localArea"/>.
e.
Example 142
<af:region value="#{bindings.EmpCreateUpdateFlow1.regionModel}"
id="EmpCreateUpdateFlow1"/>
</f:facet>
g.
h.
i.
In the Source view, find and highlight the new <af:showDetailItem ...>
entry.
Populating a UI Shell
j.
In the Application Navigator, select an applicable task flow, such as the one
you created in Step 4, and drag and drop it onto the highlighted entry in the
Source view.
k.
l.
Example 143
<af:region value="#{bindings.EmpSummaryTF2.regionModel}"
id="EmpSummaryTF2"/>
Figure 1412
Now that you have created the main area page fragment, you must wrap it in an
ADF task flow.
6.
b.
Ensure that the Create as Bounded Task Flow and the Create With Page
Fragments boxes are selected.
Do not change the other default settings.
7.
Click OK.
The new task flow is displayed as a blank visual editor in the JDeveloper middle
section.
8.
In the Application Navigator, select your recently created page fragment (.jsff
file), and drag and drop it onto the editor.
The page fragment itemNode appears in the editor, as shown in Figure 1413.
Figure 1413
14-13
Populating a UI Shell
9.
a.
b.
Figure 1414
10. To the right of the focusViewId field, click the ellipsis to display the Edit Property
dialog.
In the dialog, choose the ADFc View Activity ID of the page under which you are
registering the task flow, then click OK.
Populating a UI Shell
<pageID>_<taskFlowName>
This ID example consists of the concatenated page ID (or page name), an
underscore, and the task flow name, for example, ExpenseWorkArea_
CreateExpense.
12. Click Finish.
The new item node is displayed in the structure view, under the menu tree.
13. With the item node selected in the structure view, click the Property Inspector tab,
14. In the label field, enter a label for the task flow, such as CreateExpense.
This label will be the title of the tab that is opened by the Task Type defaultMain.
Do not leave this field null. This is the label that will appear in
the tab header when in a tabs page. Even if you are in a no-tabs page
(see Section 14.2.3.4, "Supporting No-Tab Work Areas"), do not leave it
blank because this label will be used in other ways, such as Add to
Favorites, or when the system tracks the Recent Items.
Note:
15. Select test_menu_taskmenu.xml in the Project Navigator tree, and your task
flow in the structure view to display its Property Inspector, or select the Property
Inspector tab.
In the Advanced section of the Property Inspector, enter the following values:
Task Type: defaultMain (the task flow is displayed by default whenever the
page is rendered).
The Data Control Scope should have been set to isolated, inside the task flow
definition for any task flow in the menu (defaultMain or dynamicMain) or any
call from openMainTask. See dataControlScope in Table 141.
14-15
Populating a UI Shell
Figure 1417
Click Open to automatically enter the location in the Task Flow field. The task
flow ID is a concatenation of the file location for the task-flow definition and
the task-flow name. It typically resembles
/WEB-INF/MyTaskFlow.xml#MyTaskFlow. The Property Inspector for the
itemNode should resemble the example shown in Figure 1416, "Task Flow
Property Inspector".
16. To run the JSPX page, select the page in the Application Navigator, right-click the
17. Check that the newly rendered page contains one tab whose content is the task
Populating a UI Shell
Table 142
itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property
taskType
Property Value
Note: taskType can have four
values:
dynamicMain
defaultMain
defaultRegional
taskCategory
label
String
taskFlowId
True or False
14-17
Populating a UI Shell
Table 142 (Cont.) itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property
Property Value
keyList
String
openMainTask
discloseRegionalTask
collapseRegionalTask
navigate
openSubTask
True or False
The no-tab navigation mode can load a main area task flow
and a dependent task flow simultaneously, while displaying
only one flow at a time. (See Section 14.2.3.4, "Supporting
No-Tab Work Areas.")
The UI Shell is limited to 12 task flows: 10 tabs in tab mode; 1
tab in no-tab mode and 1 dependent in no-tab mode.
Dependent Flow is applicable only to the no-tab navigation
model. Instead of having only one region for the no-tab
navigation model, there are two regions: one for the main task
flow and another for the dependent flow. These regions are in
a switcher, so that only one is visible at a time. If a dependent
task flow is loaded, only the dependent task flow region is
shown, and the main task flow region is hidden. When the
dependent task flow is closed, the main task flow region is
redisplayed, with its state preserved.
When loadDependentFlow is true, the openMainTask API will
load the target task flow in the dependent region. Loading a
new task flow in the main task flow will close both the existing
main task flow and, if any, the existing dependent task flow.
Loading a new task flow in the dependent task flow will
replace only the existing dependent task flow, if any, and leave
the main task flow intact.
forceRefresh
True or False
Populating a UI Shell
Table 142 (Cont.) itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property
Property Value
stretch
disclosed
(optional)
True or False
All the task flows will be rendered in the main area. The task
flow that has disclosed set to true will be in focus.
More than one defaultRegional task can have a true
disclosed value, because more than one detail item may be
disclosed at a time under a panelAccordion component. If the
disclosed value is true, the regional area is expanded. If the
disclosed value is false, the regional area is collapsed.
active
default <False>
False
True
taskFlow
destination
String
parametersList
String
14-19
Populating a UI Shell
Table 142 (Cont.) itemNode Properties for Main and Regional Task Flows for Application Menus
itemNode
Property
Property Value
contextCode
objectType
String
objectName
String
14.2.3 How to Add Dynamic Main Area and Regional Area Task Flows to a Page
Unless otherwise noted, follow the procedure outlined in Section 14.2.2, "How to Add
Default Main Area Task Flows to a Page," to insert the appropriate itemNode properties
listed inTable 142.
Note: The taskFlowId value path must appear in a single line to avoid an exception
during runtime.
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/patterns/
uishell/ui/publicFlow/TasksList.xml#TasksList"
disclosed="true"
parametersList="fndPageParams=
#{pageFlowScope.fndPageParams}"/>
Set label to the default label provided by the Oracle Fusion Middleware
Extensions for Applications (Applications Core).
Populating a UI Shell
taskFlowId should point to the tasks list task flow provided by Applications Core.
The disclosed attribute is usually set to true. Although, it can be set to false if
you do not want to disclose tasks list by default.
parametersList should set fndPageParams as previously shown so that this object
is available in the pageFlowScope of the tasks list task flow. This context is
necessary for Single Object WorkArea. For more information, see Section 16.4,
"Using the Single Object Context Workarea."
In the Structure window for the menu, right-click the page itemNode whose
taskType value is dynamicMain and choose Surround with... .
The Surround dialog is displayed.
2.
3.
id field: Concatenation of the page ID and a short category name, using the
following format, is suggested:
pageId_categoryName
For example, you might enter: ExpenseWorkArea_NewExpense.
4.
Click Finish.
5.
Note:
6.
Run the page by right-clicking the JSPX page file in the Projects tree view and
choosing Run
Confirm that the page contains task links arranged by category. The Task List is in
the left regional area of the page. Items in the Task List are bulleted to make it clear
when a line wraps.
14-21
Populating a UI Shell
Example Metadata for a Link in a Task List that Links to Another Page
<itemNode id="__ServiceRequest_itemNode__toTestPage1"
focusViewId="/ServiceRequest" label="Go to different page"
navigateViewId="/TestPage1"
taskType="dynamicMain"
taskFlowId="/oracle/apps/fnd/applcore/patterns/demo/SRTree.xml#SRTree"/>
2.
Go to Property Inspector.
3.
Select Advanced > Page > Dynamic Tab Navigation. Selecting the Page tab lets
you set attribute values for page-level item nodes.
4.
Other menu metadata stay the same. Tasks List will continue to render. Clicking a
Tasks Link will replace the current main area task flow with the new one.
Load a task flow into a popup when the user clicks one of the Tasks List links.
Cancel from the popup or open a new main area task flow, passing in parameter
values from the popup.
Implementation Notes
The UI Shell provides an af:popup component with a modal af:panelWindow as its
immediate child, which would contain a dynamic region defined in it. When selected
by the user, the UI Shell will load the task flow into the dynamic region, and show the
modal af:popup panelWindow without any buttons. Therefore, the task flow must
include the OK and Cancel buttons that are used to open a dynamic tab and dismiss
Populating a UI Shell
the popup, respectively. The dialog title will be set according to the label mentioned in
the menu metadata of the dynamic task link. There is a refresh condition set on the
dynamic region that refreshes the task flow and reloads it each time the popup is
opened.
Implementation Notes
Remember the following when you implement the Task Popup feature:
For a dynamicMain task that you would like to load into the popup, specify the
loadPopup property as true. For example, as shown in Example 146, the ChooseSR
task flow would be loaded in a popup when the user clicks its link in the Tasks
List. The label that is mentioned will be displayed as the dialog title of the popup
that starts the task flow.
Example 146
<itemNode id="__ServiceRequest_itemNode__ChooseSR"
focusViewId="/ServiceRequest" label="Choose SR"
taskType="dynamicMain" taskFlowId="/WEB-INF/ChooseSR.xml#ChooseSR"
parametersMap="#{pageFlowScope.Mybean.Map}"
loadPopup="true"/>
You can define any components within this task flow, except the af:popup and its
child components, such as af:dialog, af:panelWindow, and af:menu.
You cannot have a UIShellMainArea page template or any other templates inside
the popup task flow.
You must add the necessary buttons as part of the task flow. For example, if the
task flow has a simple .jsff file, it should contain OK and Cancel buttons, along
with other components.
Create a managed bean to set the action listener for the Cancel button. See
Section 18.4.1.3, "Implementing OK and Cancel Buttons in a Popup."
Create another method for the OK button that calls the method in Example 185,
and any additional processing logic. The common use case would be opening a
new task in the main area by using the openMainTask API. For example, you can
bind the OK button to a managed bean and add your own action listeners. See
Section 18.4.1.3, "Implementing OK and Cancel Buttons in a Popup."
You then can pass the parameters directly from the managed bean to the
openMainTask API bindings for the popup task flow page to open a new dynamic
tab. The menu data entries for parameters will not have any bearing on the
dynamic taskFlow tab that they are loading in the main area. The details of that
task flow should come from the openMainTask API that is bound to the OK button.
14.2.4 How to Pass Parameters into Task Flows from Tasks List
Item nodes with a taskType of dynamicMain, defaultMain, and defaultRegional have
parameter support. In addition to specifying the taskFlowId to load when the user
clicks a task flow link, you can specify which parameters to pass into that task flow.
This is accomplished with the parametersList and methodParameters properties on
the itemNode.
For the itemNode where you would like to specify parameter passing, add the
parametersList property. The value of this property is a delimited list of parameter
name-value pairs that will resemble Example 147.
14-23
Populating a UI Shell
Example 147
Code in the managed bean for passing a hashmap to the task flow would resemble
Example 148. A hashmap is a data structure that uses a hash function to map
identifying values, known as keys (such as a person's name), to their associated values
(such as their telephone number).
Example 148
Then, in the managed bean of the task flow, the Java object can be read, as shown in
Example 149.
Example 149
Therefore, the only input that the task list link will need is the internal path (within the
webApp) of the file. After the path is provided to UI Shell, it will determine the
current contextual root of the application and append it to the internal path of the file.
After the Universal Resource Identifier (URI) for the file is generated, this is set on the
URLView activity and an action expression is set on the task link to open the URL view.
UI Shell also must call an actionEvent JavaScript method on the client side that will
not allow the page to lose its current state upon redirection from the URLView activity.
You can only open data files that are part of your webApp,
such as /oracle/apps/fin/acc/file1.xls. This feature supports only
opening data files through the task list. Any other URI paths, such as a
JSPX or a JSF page, are not supported.
Note:
Implementation Notes
For a dynamicMain task item that you would like to use to open the data file, there is a
property called filePath in the Menu panel for the UI Shell page XML file. To enable
this property in the Menu panel, during design time, the task type of the itemNode
must be dynamicMain. The file URI path then should be specified against the filePath
attribute in the Menu panel, as shown in Example 1410.
Example 1410 Specifying the File URI Path
<itemNode id="__ServiceRequest_itemNode__ChooseSR"
focusViewId="/ServiceRequest" label="Download File"
taskType="dynamicMain" filePath="/WEB-INF/oracle/apps/Accounts.xls" />
You can specify any file type, such as xls, doc, pdf, txt, rtf, and ppt, that is within the
application.
If any one of these conditions is not true, security is not checked and the itemNode will
be protected only by the rendered attribute.
Application menus can have a security Expression Language expression on the
rendered attribute that, if it returns false, will not render the menu entry. To do this, set
the rendered attribute of the menu entry to an expression that evaluates anything. For
instance, if the task list is to edit certain tax forms, this could be a business rule to hide
or show links based on whether the customer is a nonprofit company. If it evaluates to
14-25
false, the menu will not appear. For more information on all the security expressions,
see the "Adding Security to an Oracle Fusion Web Application" chapter in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
If your UI Shell pages are secured by ADF Security, you must add a policy similar to
that in Example 1411 to the jazn-data.xml file and the system-jazn-data.xml file.
Example 1411 Adding a Security Policy to the jazn-data.xml File
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.internal.core.principals.JpsAnonymousRoleImpl</class>
<name>anonymous-role</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.adf.share.security.authorization.RegionPermission</class>
<name>oracle.apps.fnd.applcore.uicomponents.view.pageDefs.oracle_apps_
fnd_applcore_templates_UIShellPageDef</name>
<actions>view</actions>
</permission>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/oracle/apps/fnd/applcore/patterns/uishell/MainArea.xml#MainArea</name>
<actions>view</actions>
</permission>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/oracle/apps/fnd/applcore/patterns/uishell/RegionalArea.xml#RegionalArea</na
me>
<actions>view</actions>
</permission>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/TasksList.x
ml#TasksList</name>
<actions>view</actions>
</permission>
</permissions>
</grant>
If the policy is missing, then framework-level checks will prevent access to the task
flow (typically by throwing an error).
But how would a menu item or command link disable or hide itself based on a
preliminary check of the same permission? Example 1413 shows the generic
Expression Language expression being used to perform a preliminary check of the
Task Flow Permission. Note that this is only needed for an itemNode with
taskType="defaultMain" or "defaultRegional". The security check is performed
automatically for an itemNode with taskType="dynamicMain" (that is, what is in the
tasks list).
Example 1413 Generic Expression Language Expression Used for Task Flow
Permission Preliminary Check
rendered =
"#{securityContext.userGrantedPermission['permissionClass=oracle.adf.controller.se
curity.TaskFlowPermission;
target=/WEB-INF/audit-expense-report.xml#audit-expense-report;
action=view']}"
Note that both of these checks actually go directly against the policy store; that is, they
do not query the task flow definition. This avoids the overhead of loading a large
number of ADF artifacts to render links and menus.
14.4 Controlling the State of Main and Regional Area Task Flows
UI Shell tasks to open or close a main area tab are exposed as data control methods so
that you can create such UI artifacts through drag and drop. You do not need to create
your own data control methods and manually raise Contextual Events.
FndUIShellController.openMainTask
14-27
Note:
To open or close a main area tab, drag and drop the appropriate data control method
to create the UI functionality. Having specified the parameter values for these
methods, user clicks will prompt the UI Shell to react accordingly.
To use the openMainTask data control method:
1. Expand the Data Controls and select the openMainTask item, as shown in
Figure 1419.
Figure 1419
2.
Drag openMainTask and drop it onto the page fragment. When you do, the
Applications Context menu shown in Figure 1420 is displayed so you can choose
one of the three options.
Figure 1420
Figure 1421
2.
Drag closeMainTask and drop it onto the page fragment. When you do, the
Applications Context menu shown in Figure 1422 is displayed so you can choose
one of the three options.
Figure 1422
Two APIs shown in Example 1415 open and close a main area tab.
Example 1415 APIs Open and Close a Main Area Tab
/**
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
14-29
* @param methodParameters From Drop 6 Build 7, this can be used for passing
*
a Java object into the task flow that is specified
*
in the taskFlowId parameter. Use setCustomObject()
*
in FndMethodParameters for setting the Java object.
* @return For internal Contextual Event processing
*/
public FndMethodParameters openMainTask(String taskFlowId,
String keyList,
String parametersList,
String label,
Boolean reuseInstance,
Boolean forceRefresh,
Boolean loadDependentFlow,
FndMethodParameters methodParameters)
public FndMethodParameters closeMainTask(FndMethodParameters methodParameters)
Example 1417 shows code in a managed bean for passing a hashmap to the task flow.
Example 1417 Sample Code in a Managed Bean for Passing a Hashmap to the Task
Flow
private FndMethodParameters fndMethodParams;
...
public void setRichCommandLink1(RichCommandLink richCommandLink1)
{
this.richCommandLink1 = richCommandLink1;
FndMethodParameters methodParams = new FndMethodParameters();
HashMap testHashMap = new HashMap();
testHashMap.put("param1", "12345");
testHashMap.put("param2", "67890");
methodParams.setCustomObject(testHashMap);
fndMethodParams = methodParams;
}
Then, in the managed bean of the task flow, the Java object can be read, as shown in
Example 1418.
Example 1418 Reading Java Object in a Managed Bean
public String getTestValue()
{
Map pageFlowScope =
AdfFacesContext.getCurrentInstance().getPageFlowScope();
Object custom = pageFlowScope.get("fndCustomObject");
String outputTextString = "";
if (custom != null && custom instanceof HashMap)
{
HashMap myHashMap = (HashMap)custom;
String temp1 = (String)myHashMap.get("param1");
String temp2 = (String)myHashMap.get("param2");
outputTextString = temp1 + temp2;
}
testValue = outputTextString;
return testValue;
}
14-31
TabB would come into focus. However, when TabB is consequently closed, TabA
would have to be focused, but it has already been closed. This corner case is handled
by moving the focus to the first tab in the main area.
No-Tab Navigation
To keep track of all task flows that have been opened, a Stack instance variable is
introduced in the MainAreaHandler method. When a new task flow is opened, the task
flow ID and its associated parameter values are added to the stack.
Having this information, the call to closeMainTask pops the stack to get the last task
flow ID and its parameter values that were displayed, and reinitializes the main area
with that task flow and parameter information.
See also Section 14.2.3.4, "Supporting No-Tab Work Areas."
Within the regional area, whether a regional area task panel is collapsed or
disclosed.
A given regional area panel that is disclosed on initial rendering of the page
should reflect its assigned pixel height to determine how much screen real estate it
occupies.
Programmatic support: Allows you to control the initial or subsequent state of the
following within a work area JSPX page.
Declarative support is provided using attributes exposed on the respective item node
in the Menu Model.
For regional panels:
There are separate APIs that expose parameters to refresh the task flow and set the
disclosure state for the showDetail items in the panel accordian. The showDetail items
are identified by the task flow ID specified.
Implementation Notes
Specify the default values for the regional or main splitter position and collapsed
state in the menu for the item node that represents the page, using the
regionalAreaWidth and isRegionalAreaCollapsed properties. A sample entry in
the menu file resembles Example 1419.
demo_menuBundle'].SERVICE_CENTER}"
action="adfMenu_SvcCenter" focusViewId="/SvcCenter"
isDynamicTabNavigation="false" regionalAreaWidth="250"
isRegionalAreaCollapsed="false">
If these properties are not set in the menu for the top-level item node that
represents the page, then these default values are used:
regionalAreaWidth="256"
isRegionalAreaCollapsed ="false"
For programmatic control, drag and drop one of the following corresponding
methods from the FndUIShellController data control.
discloseRegionalArea
collapseRegionalArea
setRegionalAreaWidth
Two APIs shown in Example 1420 are exposed as data control methods under
FndUIShellController data control.
Example 1420 APIs Exposed as Data Control Methods Under FndUIShellController
/**
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
14-33
Notes:
If a work area loads because of a page navigation from another work area,
programmatically set options may override declarative settings.
Specify values for the contextual area splitter position and the collapsed state in
the menu for the item node that represents the page using the
contextualAreaWidth and contextualAreaCollapsed properties. A sample entry
in the menu file will resemble Example 1422.
If these properties are not set in the menu for the top-level item node that
represents the page, then these default values are used:
contextualAreaWidth="256"
contextualAreaCollapsed ="false"
For programmatic control, drag and drop one of the corresponding methods from
the FndUIShellController data control:
collapseContextualArea
contextualAreaWidthSelection
To set these values when opening a new task, drag and drop the openMainTask
method from FndUIShellController data control and pass in the
contextualAreaWidth and contextualAreaCollapsed parameters through
"methodsParameters > NamedData" as shown in Example 1423.
Set the method in the page managed bean to set the contextualAreaWidth and
contextualAreaCollapsed values, as shown in Example 1423.
14-35
To set these values using the Navigate API to navigate to a task flow, drag and
drop the navigate method from FndUIShellController and pass in the
contextualAreaWidth and contextualAreaCollapsed parameters through
"methodsParameters > NamedData" as shown in Example 1424.
First you need to set the FndMethodParameters; this should be done by adding
code similar to this to a managed bean that we will call myBean for this example.
private methodParameters fndMethodParams;
...
public void myNavParameters()
{
FndMethodParameters methodParams = new FndMethodParameters();
HashMap testHashMap = new HashMap();
testHashMap.put("contextualAreaWidth", "200");
testHashMap.put("contextualAreaCollapsed ", "true");
methodParams.setCustomObject(testHashMap);
fndMethodParams = methodParams;
}
Contains at least the label, the application name, and the viewID
Calls the Policy Store (optimized bulk authorization) to get the subset of these
menu items to be rendered for that user
Items to which the user does not have access will not be displayed.
Note:
Navigator: This is the global menu that is displayed in the UI Shell global area.
14-37
Home Page Menu: The Home page tabs are actually each a JSPX page assembled
using menu metadata.
Preferences Menu: The User Preferences page has a task list link to all other
preferences pages within Oracle Fusion Middleware. This is assembled using
menu metadata.
<groupNode> Attributes
Attribute
Data Type
Required Description
labelKey
xsd:string
Table 144
Bundle key used for label; the key will be looked up in the
resource bundle specified by the resourceBundle attribute of
<menu>.
Attribute
Data Type
Required Description
webApp
xsd:string
focusViewId
xsd:string
securedResourceName
xsd:string
applicationStripe
String
N/A
Data Type
Required Description
parametersList
String
N/A
pageParametersList
String
N/A
destination
String
N/A
Navigator Example
Items in bold are groups, and items in blue are links. So some groups also are links.
14-39
Note:
The Navigator metadata may be pointing to target work area pages in various
applications. To simplify the runtime behavior, one XML file contains all the menu
entries. An Applications Core application will deploy these menus to Oracle Metadata
Services (MDS). Each application will read these directly from MDS.
Each application must be configured so that the shared library can read the menus
from MDS.
To implement a Global Menu:
1. Verify that the web.xml file of the application has the correct Java Authentication
and Authorization Service (JAAS) filter to enable checking menu security against
Oracle Platform Security Services (OPSS), as shown in Example 1426.
Example 1426 Sample JAAS Filter
<filter>
<filter-name>JpsFilter</filter-name>
<filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
<init-param>
<param-name>enable.anonymous</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>remove.anonymous.role</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>application.name</param-name>
<param-value>crm</param-value>
</init-param>
<init-param>
<param-name>oracle.security.jps.jaas.mode</param-name>
<param-value>subjectOnly</param-value>
</init-param>
</filter>
3.
ADF Menu Security is enabled by default. If you need to disable menu security, such
as for testing, start WebLogic Server after setting the JAVA_OPTIONS environment
variable in the setDomainEnv.sh file:
JAVA_OPTIONS = -DAPPLCORE_TEST_SECURED_MENU=N
14-41
The Expression Language expression should never check the page definition.
However, you can use the Expression Language expression to check security of a
person's role because that is in LDAP.
securedResourceName="oracle.apps.prc.por.createReq.publicUi.page.PrcPorCreateReqWo
rkareaPageDef" applicationStripe="hcm"/>
<itemNode id="itemNode_my_information_self_service_receipts"
label="#{menuBundle['oracle.apps.menu.ResourcesAttrBundle'].RECEIPTS}"
applicationStripe="hcm"
focusViewId="/RcvSelfServWorkarea" webApp="Logistics"
securedResourceName="oracle.apps.scm.receiving.selfService.workarea.ui.page.RcvSel
fServWorkareaPageDef"/>
applicationStripe="hcm"/>
</groupNode>
</groupNode>
</menu>
2.
14-43
Figure 1424
Note:
If the user is logged out, the only way for an unauthenticated user to view a page
is if a page either has no databinding (no pagedef) or has databinding but is
granted to the anonymous role:
When the Sign Out link is clicked, the page is redirected to the application's
default home page if it is accessible. There are cases in which a default home page
is not available to the current user. In such cases, the user application should
implement the setLogoutUrl() API that is included in the
oracle.apps.fnd.applcore.common.ApplSession class of the Oracle Fusion
Middleware extensions for Applications Core API. This API is implemented as:
public void setLogoutURL(String pLogoutURL);
The UI Shell's Sign Out logic will get the logout URL from ApplSession using the
getLogoutURL() API and redirect to it. This API is implemented as:
public String getLogoutURL();
If the logout URL was not set in ApplSession, the application will be redirected to
the default home page.
On clicking the Sign Out link, the user session is cleared from the cookie and
terminated. If the home page is secured, the login prompt will first appear. If the
home page is not secured, the page will appear and the Sign In link will be
enabled.
Switch To / Impersonation
The Switch To menu is available only if the user has the security privilege to
impersonate others and has been given access to impersonate at least one other
user. When clicked, the menu displays the name of the logged-in user and any
user names he or she can impersonate.
Figure 1425
Switch To Menu
14-45
Figure 1426
If an application is not installed, or the user does not have access, the entry in the task
list menu should not appear. If a user does not have access to a particular setting
within a page, you must use the rendered property with a security expression behind
it.
For each application, there should be a preferences page. The preferences page uses
the same path of the current application, but it uses a page name of preferences.jspx.
If no associated preferences page exists, a default General Preferences page will be
shown. This page shows global Applications Core most-used preferences.
If there are several preference pages associated with an application, such as a Common
Setting page and more specific pages, only one preferences page as a target from the
global preferences link can be defined per application. (There will be a default name
for the target focusViewID of the preferences page for an application.) In the
preferences work area, other links are available from the task list to more specific
pages or task flows. (Links in the task list can contain other focusViewIDs that belong
to the same application as the default preference page.)
When the first application is deployed, it will become the location of the General
Preferences page.
Several pages of an application can all point to the same preferences page.
More than one application cannot point to the same preferences page. This implies that
each application can have its own preferences page, and if two applications want to
share a common preferences page, they can, but it can be navigated to only from the
task list. Therefore, from the Preferences link, the user always sees the more specific
preferences page of that application.
14-47
Each application will provide the preferences menu files that contain task list links to
preferences pages delivered by that application. The preferences task list should follow
the Navigator architecture recommendations where it uses sharedNode references to
bring in menus from each application so they can be patched independently.
Applications Core will automatically federate the menu metadata so the task list that is
rendered will contain all the entries from all applications (filtered by security).
Individual menu files will have versions like other distributed menu files, so any
application can apply a patch and the new menu will take precedence over an older
version when federated.
Task List Can Link Only to Full Pages (Not to Specific Task Flows)
The task list will not start task flows dynamically, but will load a Preferences workarea
page. This is because the task list menu must be federated and only page-level entries
are allowed in a federated menu.
No-Tabs Mode
The Preferences page should use a no-tabs mode. This is a standard, not controlled
through any code. You can use tabs if all task flows are defaultMain. See
Section 14.2.3.4, "Supporting No-Tab Work Areas" for more information.
Task List Security
The task list will be filtered by functional page-level security for that user. If all entries
in a category are restricted, then the category should not appear either.
Preferences Settings
Settings will be a view activity in a task flow. It will follow other user experience
standards so it should be built using an Applications Panel. This means the action
buttons will appear at the top.
Different preferences pages can change the same backend setting, depending upon
applications design. If this is needed, it should be stored in a common area, such as
LDAP, or be in the General Preferences page.
1.
Create a UI Shell page that is used solely for the user preferences, such as
PreferencesUI.jspx.
2.
3.
Add the following task flow as a default regional area under the preferences page
entry:
"/WEB-INF/oracle/apps/fnd/applcore/pref/ui/mainflow/GeneralPreferencesF
low.xml#GeneralPreferencesFlow"
The final menu entries for the page will appear similar to those shown in
Example 1431.
The results of this example should display the basic Preferences menu entries in
the default regional area that can be opened to display subflows for each
preferences subtask (for instance, Accessibility and Appearance).
14.6.2.4.1 How to Use the Preferences Menu Model The General Preferences task flow that
is exposed also renders the Preferences Menu Model links by using a call to the Menu
Service API.
The Preferences menu will be part of a central Utility application (menu web service)
that will be deployed in the server. As a developer, you maintain the Preferences
menu.
On any UI Shell page, the global area contains a Personalization menu that contains a
Set Preferences link. This link will redirect the user to an application-specific
Preferences page, depending upon the entry in the menu data.
Example 1432 shows sample Preferences menu data.
Example 1432 Example Preferences Menu Data
<?xml version="1.0" encoding="UTF-8" ?>
<menu xmlns="http://myfaces.apache.org/trinidad/menu" version="1">
<itemNode id="preferences_node_a" label="Preferences Page A"
action="preferences_node_a" focusViewId="/preferencesA"
webApp="fnd" prefForApps="gl, hr" >
<itemNode id="Flow 1" label="Service Flow"
focusViewId="/preferencesA"
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/ServiceFlow.xml#ServiceFlow"
parametersList="id=userName" />
</itemNode>
<itemNode id="preferences_node_b" label="Preferences Page B"
action="preferences_node_b" focusViewId="/preferencesB"
webApp="fnd" prefForApps="fn" >
<itemNode id="Flow 2" label="Request Flow"
focusViewId="/preferencesB"
14-49
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/RequestFlow.xml#RequestFlow"
parametersList="id=userName" />
</itemNode>
<itemNode id="preferences_node_d" label="Preferences Page D"
action="preferences_node_d" focusViewId="/PreferencesUI"
webApp="Demo" prefForApps="Demo"
<itemNode id="Flow 2" label="Request Flow"
focusViewId="/preferencesB"
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/finance/AcceptanceFlow.xml#Acceptanc
eFlow"
/>
</itemNode>
</menu>
In the example menu XML file, each parent item node represents a Preferences UIShell
page. Its child nodes refer to the application-specific task flow in which the Preferences
page exists.
For example, the first itemNode entry refers to the preferencesA page that is part of the
FND webApp. The Service Flow child node is a task flow that belongs to the FND
webApp.
For each parent itemNode, there is an attribute called prefForApps that contains a list
of webApp names. This means that the itemNode is a common preferences page for
those listed webApps.
For example, the Preferences page is common for two webApps -- gl and hr. This
essentially means that all the Dashboards and work area UI Shell pages in the gl and
hr webApps will be redirected to this preferencesA page, which is in webApp FND,
when the Set Preferences link is clicked.
All the task flows under each preferences page itemNode will be displayed in the
General Preferences task flow as navigation links. Therefore, all preferences pages will
have access to these task flows.
14.6.2.4.2 How to Configure User Session and ADF Security To test the general preferences
task flows, configure user session and ADF Security for the test application. See
Chapter 49, "Implementing Application User Sessions."
When configuring ADF Security, there is no need to define users, because you already
are using an Oracle Internet Directory store that will authenticate the users existing in
the policy store.
14.6.2.4.3 How to Retrieve Preference Values and Check Accessibility Mode by Using an
Expression Language Expression See Chapter 21, "Working with Localization
Formatting."
A use case exists where the UI must use an Expression Language expression to check
whether the accessibility mode is set to screenReader to render screen reader-friendly
components in screenReader mode. The recommended method to do this uses
#{requestContext.accessibilityMode} and is documented in "How to Configure
Accessibility Support in trinidad-config.xml" in "Developing Accessible ADF Faces
Pages" in Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle
Application Development Framework.
14.6.2.4.4 How to Implement the Password Management Page The Password link on the
General Preferences page will point to the Password Management page from the
Oracle Identity Management administration application. This page is maintained by
the Oracle Identity Management team. For the Password link to redirect to the
pwdmgmt.jspx page, the deployment information of the current application and the
Oracle Identity Management administration application must be populated correctly
in the Oracle Fusion Applications Functional Core (ASK) tables.
14.6.2.5.2 How to Configure the Accessibility Preference Oracle Fusion applications follow
the Apache Trinidad standards for Accessibility.
Users can set the Accessibility preference by selecting the Set Preferences link from
the Personalization menu in the global area. The Accessibility option will look similar
to Figure 1430.
14-51
Figure 1430
14.6.2.5.3 How to Configure the Regional Preferences The default Regional settings are
based on the selected Language setting unless the Regional setting is saved explicitly.
That is, no matter how the current language is derived, whether it is from login, the
browser or LDAP, if the Regional settings are not yet set, they will default from the
language. But if the user sets the Regional settings and then sets the Language setting,
the Regional settings will not be changed.
Users can set the Regional preferences by selecting the Set Preferences link from the
Personalization menu in the global area. The Regional options will look similar to
Figure 1431.
Figure 1431
apply to all pages, not just the one you are on. (When you use Customize [name of
page] Pages, all the content except the global content is available for customization.)
Manage Customizations...
Select this option to start the Customization Manager.
For information about customization, see Chapter 63, "Creating Customizable
Applications" and Page Composer information in the Oracle Cloud Sales Extensibility
Guide. For more information about the Customization Manager, see the "Extending
Runtime Editing Capabilities Using Composer" chapter, and the "Introduction to
Composer" chapter of the Oracle Fusion Middleware Developing Portals with Oracle
WebCenter Portal and Oracle JDeveloper.
For information about defining and configuring namespaces when promoting a page
fragment to a label, see "Updating Your Application's adf-config.xml File" in the
"Performing Composer-Specific MDS Configurations" chapter of the Oracle Fusion
Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.
Manage Sandboxes...
Select this option to manage sandboxes on your system.
The Sandbox is built on top of the standard Sandbox feature from Oracle Metadata
Service. See "Using the Sandbox Manager: Explained" in the Oracle Cloud Sales
Extensibility Guide.
Setup and Maintenance...
Select this option to start the Oracle Fusion Functional Setup Manager application. See
the Oracle Fusion Functional Setup Manager User's Guide.
Highlight Flexfields
No separate implementation is required. This option is available to any user who has
the permission to view the Administration menu.
Select this option to highlight the Descriptive Flexfields (DFF), Key Flexfields (KFF)
and Extensible Flexfields (EFF) on the runtime page.
When this mode is on, the page displays an information icon by each DFF, KFF and
EFF. This will be displayed whether any Flexfield segments have been configured.
Hovering over the icon shows the Flexfield details. Administrators can note the DFF,
KFF or EFF code so they can search for it in the Manage Descriptive Flexfields,
Manage Key Flexfields, and Manage Extensible Flexfields setup tasks in Oracle Fusion
Functional Setup Manager.
The option changes to Unhighlight Flexfields so that administrators can return to the
normal view of the page.
For more information about Flexfields, see Chapter 22, "Getting Started with
Flexfields."
14-53
<actions>launch</actions>
</permission>
</permissions>
</grant>
Enable all: Select this option to enable all other options on the dialog. When
Enable all is selected, removing the selection from any of the other check boxes
will deselect Enable all.
Applications logging, severity level and modules are stored as user-level profile
options in profile tables. The corresponding profile option names are AFLOG_
ENABLED, AFLOG_LEVEL, and AFLOG_MODULE. See "Configuring Settings for Log Files
and Incidents" in Oracle Fusion Applications Administrator's Guide for information.
Because applications logging, severity level, and modules are profiles, when users
click Save and Close, user-specific profile values will be inserted into the profiles.
If users decide to revert the setting to the default site profile, they must use the
Functional Setup Manager to remove their own profile.
After making changes to any one of the options for applications logging, severity
level, or modules, the user must log out of the Oracle Fusion application, close the
browser session, and log back in for the new options to take effect. These logging
profiles are cached in the user session and initialized when a user logs into an
Oracle Fusion application.
Database trace: This option enables the SQL trace feature for all database
connections used by the current user session. See "Understanding SQL Trace and
TKPROF" in the Oracle Database Performance Tuning Guide.
14-55
For SQL trace, the trace file will have the FND session ID appended to the end. For
example, mysid_ora_4473_881497BF7770BEEEE040E40A0D807BB1.trc.
The trace file can be found on the database host in the directory specified by the
user_dump_dest init.ora parameter.
PL/SQL profiler: This option enables the PL/SQL hierarchical profiler for all the
connections used by the current user session. See "Using the PL/SQL Hierarchical
Profiler" in the Oracle Database Development Guide.
For the PL/SQL profiler, the output will be in the directory defined by APPLLOG_
DIR. The exact path for APPLLOG_DIR can be found on the database host by using
the SQL statement:
select directory_name, directory_path from dba_directories where
directory_name like 'APPLLOG%'
The file names would be PLS_<some number>_<FND session id>_
<timestamp>.txt, such as PLS_49774696_88740EC94E3AAD2CE040E40A0D8036D8_
100607104716.txt.
To process the collected PL/SQL profiles and view results, run the plshprof
command under the $ORACLE_HOME/bin directory.
Severity Level:
Use this option to set what types of information to log, and how much of it to
log.
For more information, see "Managing Oracle Fusion Applications Log Files" in
the Oracle Fusion Applications Administrator's Guide, and "Troubleshooting
Oracle Fusion Applications Using Incidents, Logs, QuickTrace, and Diagnostic
Tests" in the Oracle Fusion Applications Administrator's Troubleshooting Guide.
Modules:
This is the module filter for logging. This is a comma-separated list of modules
to be logged. The percent sign (%) is used as a wildcard. For example, % or
%financial%. The percent sign (%) is the default value and if no other value is
specified, then it means everything will be logged.
When a customer logs a service request with Oracle, the support person will
help the customer enter the values necessary to filter the diagnostic logs for
the needed information.
Tracing Options
This feature is designed for customers to collect diagnostic data to send back to Oracle
for analysis.
When there is a performance issue that is reproducible, the tracing feature streamlines
the data collection process by allowing the end user who is experiencing the problem
to record a trace that will contain the necessary diagnostic information.
Before the user can access this function, the security administrator needs to assign the
Business Flow Troubleshooting role to the user. On each managed server, a maximum
of three users can be tracing at a time. By requiring the troubleshooting role to be
granted, an administrator can grant access to users who actually need to trace, and
revoke access when the issue is resolved.
To grant the role, the administrator will follow these basic steps:
Click Assign.
Right before starting the problematic flow, select Troubleshooting > Tracing
Options. The dialog shown in Figure 1433 is displayed.
Figure 1433
Trace Options defaults are based on the Trace type selection. Click Advanced
Options to see what trace settings are enabled. For fine-grained control, select
different trace options, as shown in Figure 1434.
Important: The user should accept the default settings or contact
Oracle support for additional instructions.
14-57
Figure 1434
Click Start Trace. A confirmation dialog, similar to Figure 1435, with the trace
ID will be displayed. Make a note of the trace ID.
Figure 1435
Subsequent clicks will be traced. The trace will run for a maximum of 30
minutes. If there are more than three simultaneous tracing sessions, an error
message will be displayed.
If the Applications Trace option is selected (enabled by default for the
Performance trace type), the server also needs to have at least 200MB of free
memory in the JVM heap.
After executing the steps that have issues, select Troubleshooting > Tracing
Options again. When tracing is active, only Stop Trace and Cancel will be
active, as shown in Figure 1436.
Figure 1436
Stop Trace
Click Stop Trace. Figure 1437 shows the two options to control whether to
create an incident.
Figure 1437
14-59
When enabled, this will cause the ids of components with testId
attributes to be set to the value of the testId and the client component
attribute of the component to be forced to true.
TestId attribute is now deprecated; use the 'id' attribute instead.
</description>
<param-name>oracle.adf.view.rich.automation.ENABLED</param-name>
<param-value>true</param-value>
</context-param>
Also, "upk" must be provisioned by the System Administrator. That is, an entry with
DEPLOYED_MODULE_NAME = "upk" must be added in the ASK deployment tables. These
tables are populated at deployment time through Oracle Fusion Functional Setup
Manager tasks. Without the entry, the menu item "User Productivity Kit ..." will not be
shown in the Help menu.
Applications Help
Select this option to open the help system in a separate window.
Privacy Statement
Select this option to display the privacy statement, which will appear in a new browser
window. This option is always inactive until it is implemented. To set up the privacy
statement, enter a fully-qualified URL in the PRIVACY_PAGE profile option. See
Section 56.3, "Setting and Accessing Profile Values."
About Applications
Select this option to display the Oracle copyright statement and information about the
application.
About This Page
Select this option to display information for the product and product family of the
current page. This makes it easier to know to which product the current page belongs
and makes it easy to log a Service Request or find a patch for the correct product.
Click your user name to open the Settings and Actions menu.
Figure 1438
In the Proxies pane, click the Create icon to open the Select and Add: People
dialog.
Figure 1440
Proxies Pane
Enter known data in any of the fields and click Search. This example uses the User
Name field and the APPLICATION_DEVELOPER name.
Figure 1441
14-61
Click OK. The information is entered on the Proxies pane, as shown here.
Figure 1442
Enter the necessary dates in the Start Date and End Date fields and click Save.
Now Impersonatee has granted proxy access to APPLICATION_DEVELOPER.
APPLICATION_DEVELOPER can impersonate Impersonatee and perform
transactions on his or her behalf.
Open the Settings and Actions menu and click Sign Out.
Sign back in as APPLICATION_DEVELOPER using the password for that user ID.
Click Switch To. The menu shows the names of the logged-in user and the users
he or she can impersonate.
Figure 1443
Switch To Menu
Select the name of the Impersonatee. You will be asked to confirm the switch.
Figure 1444
The name of the impersonatee now is displayed with an icon indicating that the
user is being impersonated.
Figure 1445
15
Implementing Search Functions in the UI
Shell
15
This chapter discusses how to implement search functions in the UI Shell page
template that is used to build web pages.
This chapter includes the following sections:
Section 15.6, "Implementing the Oracle Fusion Applications Search Results UI"
Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
Tagging is being enabled on a business object. The Model or View already exists
for the business object.
Your pages are using the UI Shell template.
15-1
You have identified the business objects that you want to Tag.
You have database connections to the ApplicationDB database and WebCenter
Portal.
You have enabled data security.
Important Considerations
When working with tags, keep these points in mind:
Tags are attached to objects, not task flows. When you click a link belonging to a
tagged object, you will go to a page and task flow to view that particular object.
You can enable tagging at the page level if it is clear that the page represents a
specific object.
If you have several pages in a task flow, all representing the same object, you can
enable tagging on every page.
You can enable tagging in a table if each row represents a specific object.
You can tag an object from several different places. You can give several target
navigation paths from the Tag Center. This allows different users to access the
same object from different work areas.
Oracle Fusion Applications Search allows only a single navigation path, but a
global search allows alternate links and multiple service view objects for alternate
navigation paths. That is, you can tag an object from one work area, but on
navigation from the tagged object link in Tag Center or Oracle Fusion Applications
Search, the work area that it navigates to could be different.
Security will hide a tagged object in both Tag Center and Oracle Fusion
Applications Search based on the object's data security, not task flow security,
although page and task flow security are enforced after clicking the tag.
Preliminary Setup
The following steps are condensed from the Oracle Fusion Middleware Developing Portals
with Oracle WebCenter Portal and Oracle JDeveloper.
1.
2.
Ensure that your database connection has access to WebCenter Portal schema. If it
does not, create another connection to access WebCenter Portal schema. Name the
connection WebCenter. Tagging looks for this connection to access the data.
You should now see at least two connections in your
connections.xml file: WebCenter and ApplicationDB.
Note:
3.
In the resource Palette, open My Catalog > Web Center Service Catalog > Task
Flows. Ensure that you see task flows similar to tagging-launch-dialog.
4.
In the Component Palette, right-click your View Controller project and select
Project Properties > Technology Scope > Project Properties. Ensure that Tagging
Service is selected. In the Component Palette, search for tagging. You should see
Tagging Button and Tagging Menu Item.
5.
Add users and roles, and configure security and authorization for the application;
this is highly recommended. Furthermore, it is required for implementing security
for tagging.
15.1.1 How to Use the Delivered Oracle WebCenter Portal Tagging Components
Three pieces of information are needed to define tagging to a business object:
1.
You need the unique key of the object that can identify the object. This is stored in
a field called RESOURCE_ID (VARCHAR2(200)) in the tagging schema. If you have
multiple fields that define the unique key, use a period as the separator. For
example, PK1.PK2. Additional restrictions include these:
2.
3.
Note:
From the Component Palette, select WebCenter Tagging Service. Drag and drop
the tagging button onto the page. (If you do not find the button, ensure that you
added the WebCenter Tagging JSP Tag Library to your user interface project.)
2.
Open the Property Inspector for the tagging button. Enter the bound values for
resourceId, resourceName and serviceId, similar to Example 151.
Example 151
<tag:taggingButton
resourceId="#{row.AuctionHeaderIdString}"
resourceName="#{row.AuctionTitle}"
serviceId="oracle.apps.pon.auctionheadersall"/>
Note:
15-3
3.
From the Resource Palette, go to My Catalogs > WebCenter Services Catalog >
Task Flows, and drag and drop the Tagging Dialog (as a Region). If you do not
find the Tagging Dialog, ensure that you added the WebCenter Tagging Service
View to your user interface project (Properties > Libraries and classpath). Note
that you may drop multiple tagging buttons on your page depending upon your
requirement. You need to drop the tagging dialog only once on the page.
Whenever you click a tag icon (tagging button) on the page, it will call the same
tag dialog region.
If you are placing tags within rows of a table, the Tagging
Dialog region must be dropped outside of the table. Otherwise, it is
instantiated for every row, which will not work.
Note:
The ability to tag an object is now enabled on the page. The code will look similar
to that shown in Example 152.
Example 152
Enabling Tagging
<af:region
value="#{bindings.tagginglaunchdialog1.regionModel}"
id="taggi1"/>
If you have multiple objects to tag, there will be multiple tagging buttons you will
drop on your page, whereas there will be only one tagging dialog.
Tagging is enabled, but to see the tagged resource in the Tag Center, you must create a
service definition.
To create a service definition:
1. Expand Application Resources > Descriptors > ADF Meta-INF. If you already
have the service-definition.xml file, open it. Otherwise, create the
service-definition.xml file. Important fields are:
resourceParamList: The list of parameters that you want to pass to the task
flow. For example, your task flow takes invoiceId and invoiceType. If the
RESOURCE_ID for the tagged item is 123.C45 where 123 is the invoiceId and
C45 is the invoiceType, in resourceParamList you should specify
invoiceId;invoiceType. The Applications Core class will parse the resource
ID 123.C45 and pass invoiceId=123,invoiceType=C45 to the task flow. To use
a different delimiter, use the customDelimiter attribute.
object will always need both composite keys to be identified as a unique entity.
So, the resourceParamList will always contain the same number of parameter
names as the composite keys. The task flow must take both EastCoast and C45
as parameters. But the page-level parameters can be called out in the
pageParametersList. For example:
resourceParamList = "Region,InvoiceType"
pageResourceParamList = "Region"
Example 153
Sample service-definition.xml
Make it unique so teams of developers are not trying to push files to the
exact same location in MDS.
15-5
3.
Open Application > Application Properties > Deployment. Select the MAR
file and choose Edit.
In the Edit dialog, select User Metadata and choose Add. Browse to select the
meta directory you just added and click OK.
Example 154
<adf-config
<adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config"
version="11.1.1.000">
<mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
<persistence-config>
<metadata-namespaces>
<namespace path="/oracle/apps/meta"
metadata-store-usage="WebCenterFileMetadataStore"/>
</metadata-namespaces>
<metadata-store-usage id="WebCenterFileMetadataStore"
default-cust-store="true" deploy-target="true">
<metadata-store
class-name="oracle.mds.dt.persistence.stores.file.SrcControlFileMetadataStore">
<property name="metadata-path" value="../../mds"/>
</metadata-store>
</metadata-store-usage>
</persistence-config>
</mds-config>
</adf-mds-config>
</adf-config>
4.
Add the entry shown in Example 155 to your adf-config.xml file to enable the
default resource action handler from Applications Core.
Example 155
<wpsC:adf-service-config>
<resource-handler
class="oracle.apps.fnd.applcore.tags.handler.FndResourceActionViewHandler"/>
</wpsC:adf-service-config>
The Tag icon will appear on the page. When you click the Tag icon, it will take
you to the UI where you can enter a new Tag.
You can share the tag or not share it. Only shared tags are available to Oracle
Fusion Applications Search.
After creating the tag for the first time, again hover the mouse over the icon. It
will display My Tags and Popular Tags.
Clicking the Tag takes you to the Tag Center UI where you are shown all
resources that have been tagged by that word.
Clicking a resource from Tag Center will take you to the task flow defined in
your service definition, passing the parameters you specified so you can view
the object.
<resource-view
taskFlowId="/WEB-INF/dummy^/WEB-INF/dummy^/WEB-INF/Test1Frag2TF.xml#Test1Frag2TF">
<parameters>
<parameter name="viewId" value="DummyView^Region6UIShellPage^Test2"/>
<parameter name="webApp"
value="ApplCoreCRMDemo^ApplCoreCRMDemo^SimpleApplication1_application1"/>
<parameter name="pageParametersList" value=""/>
<parameter name="taskParametersList" value=""/>
<parameter name="resourceParamList" value="val"/>
<parameter name="navTaskLabel" value="My Employee Details^My Employee Details
2^My Employee Details"/>
Implementing Search Functions in the UI Shell
15-7
<parameter name="applicationStripe"
value="ApplicationsCommon^ApplicationsCommon^AppStripe1"/>
<parameter name="pageDefinitionName"
value="pageDef.not.exist^oracle.apps.view.pageDefs.Region6UIShellPagePageDef^oracl
e.apps.view.pageDefs.Test1PageDef"/>
</parameters>
</resource-view>
The lists of taskFlowId, viewId, webApp, and so on, are specified as a delimited string,
with each value delimited by a caret. Two parameters, applicationStripe and
pageDefinitionName, are available for checking security when the target is in a
different webApp.
If the current view ID matches any one of the viewId values in the target list, you take
the corresponding task flow (that is, if the third viewId value matches the current view
ID, you take the third taskFlowId value) and open it in the current page, if the user
has view access to that task flow, which overrides the order of the list. Otherwise, you
check a list of link targets for the first target to which the current user has access. You
are responsible for making sure that all users who can access this object have at least
one match to a target task flow defined in the service-definition.xml file.
When the target is in a different webApp, the security check is performed by calling
checkBulkAuthorization API. Therefore, you must use a standalone Oracle WebLogic
Server and LDAP policy store. This requirement is optional when the lists of targets
are within the same webApp.
Select or create a new task flow that will act as your resource viewer for a service
(business object):
a.
In the task flow definition, define an input parameter that is called resourceId
(in this example), with class equal to java.lang.String, with value equal to
#{pageFlowScope.resourceId}, and with required set to enabled.
Note that the value for resourceId is set automatically when clicking a tagged
item link in Tag Center.
b.
c.
Add the setCurrentRow method as the default activity in the task flow and
bind the method (right click the method in the task flow and go to page
definition) with the parameter value of #{pageFlowScope.resourceId}, type
java.lang.String, and name equal to the parameter variable name in the
setCurrentRow method signature.
d.
Add the bounded task flow for the details or information page of the tagged
item to the new task flow.
e.
Add a control flow case from the setCurrentRow method to the details or
information page task flow, as shown in Figure 151.
2.
Register the new task flow in the service-definition.xml file. Register the
resource viewer for a particular service (business object) to its section in the service
definition file. See Example 153 for samples of the service-definition and
resource-view entries.
Basically, you have defined a task flow that takes the resource ID as input. Use the
resource ID to uniquely identify the business object and display any desired extra
detail. Note that clicking a tagged item in Tag Center displays the details or
information page for the tagged item in the local area of the workarea page for that
task flow.
Example 157
FND_CRM_CASES is the object you want to secure that is found in the FND_OBJECTS
table. This is usually the object's main table name.
15-9
Put the service definition into MDS. For ease of deployment, service definition
files will be stored in MDS.
Tagging an object by having the Tag button and tagging dialog in the task flow. On
clicking the Tag button, a tagging dialog is displayed and prompts the user to tag
the object with a name, as shown in Figure 152.
To see the tagged object in the Tag Center task flow, click the Tags link in the UI
Shell Global Area and the Tag Center task flow displays the list of tags available,
as shown in Figure 153.
Click one of the tags in the tag cloud region of the Tag Center to view the tagged
items, as shown in Figure 154.
Click the tagged item to view the object in the task flow mentioned in the service
definition file, as shown in Figure 155.
To check whether the object is already tagged, hover over the Tag button to see the
tags. On clicking the tag link on the hover dialog, the Tag Center task flow will be
started with the selected tag, as shown in Figure 156.
/**
* Notify UIS hell to record a given sub flow on the stack and
* also notify Recent Items to include it on the list.
*
* @param taskFlowId Task flow to open
* @param parametersList Parameters list for the task flow.
*
This is a semicolon delimited String
*
of name-value pairs. For example,
*
"param1=value1;param2=value2".
*
Implementing Search Functions in the UI Shell 15-13
All the parameters required to be passed in openSubTask are exactly same as used by
the Navigate API. For more information, see Section 16.1, "Introducing the Navigate
API."
values and make decisions, such as if you need to first initialize the parent flow, or if
you need to set Visible to False on some of the actions on the page.
Both will start the execution in the parent flow. Because the sub flow must be
piggybacked on the parent flow when it is started from the Recent Items menu, you
need to change the parent flow following these directions:
Add a new router activity at the beginning of the parent flow. Based on a test
condition, it will route the control to either the original parent flow or the task
flow call activity (that is, the sub flow).
Add an optional method call activity to initialize the sub flow before it is started
from the Recent Items menu. Product teams can code the method in such a way
that it can navigate to the sub flow after initializing the parent state. This allows
product teams to render the contextual area, navigating back to the parent flow
from the sub flow, and any other customizations.
Bind openSubTask to the command component (such as a link or button) which
causes the flow to navigate to the task flow call activity in the original parent flow.
The openSubTask API registers the parent flow details and input parameters to the
sub flow (to be started as a sub flow later) to the Applications Core task flow
history stack.
Usually, you do not need to modify your sub flow for this task. However, you can
consolidate the initialization steps from two execution paths in this way:
Remove initialization parts from both paths in the parent flow. Instead, set input
parameters in both paths only.
Modify the sub flow to take input parameters.
Add a new method call (such as initsubflow) at the beginning of the sub flow to
initialize states in the parent flow (for example, parent table) so that the sub flow
can be started in the appropriate context.
Note that the design pattern also requires the application to be able to navigate back to
the parent flow from the sub flow. The initialization code should take this into
consideration, such as by setting up states to allow the sub flow to navigate back.
In this example, you will use an Employee sample implementation to demonstrate the
details of this design pattern.
The Ename column in the search result table is a link that can be used to navigate to
the employee detail page of a specific employee. When this link is clicked, a sub flow
(or nested bounded task flow) is called to display the Employee Complete Detail page,
as shown in Figure 158.
Figure 158 Example Employee Complete Detail Page
The router activity decideFlow decides whether the control task flow should go to the
original parent task flow path (initParent) or to the sub task flow path (toChild). The
condition is defined as:
<router id="decideFlow">
<case>
<expression>#{pageFlowScope.Empno == null}</expression>
<outcome id="__9">initParent</outcome>
</case>
<case>
<expression>#{pageFlowScope.Empno != null}</expression>
<outcome id="__10">toChild</outcome>
</case>
<default-outcome>initParent</default-outcome>
</router>
The test checks whether the Empno variable in the parent task flow's pageFlowScope is
null. #{pageFlowScope.Empno} is set using its input parameter Empno when the parent
task flow is called. The input parameters on the parent task flow (that is,
ToParentSFFlow) are defined as:
<input-parameter-definition>
<name>Empno</name>
<value>#{pageFlowScope.Empno}</value>
<class>java.lang.String</class>
</input-parameter-definition>
When the parent task flow is started from the task list, the Empno parameter is not set
(that is, it is not defined in the application menu's itemNode). Therefore, the parameter
is null and the router will route it to the initParent path.
When the sub task flow is recorded through the openSubTask API, the Empno
parameter is set on parametersList as:
<methodAction id="openSubTask" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="openSubTask"
IsViewObjectMethod="false" DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName="FndUIShellController.methodResults.openSubTask_
FndUIShellController_dataProvider_openSubTask_result">
<NamedData NDName="taskFlowId" NDType="java.lang.String"
NDValue="/WEB-INF/oracle/apps/xteam/demo/ui/flow/ToParentSFContainerFlow.xml#ToPar
entSFContainerFlow"/>
<NamedData NDName="parametersList" NDType="java.lang.String"
NDValue="Empno=#{row.Empno}"/>
<NamedData NDName="label" NDType="java.lang.String"
NDValue="#{row.Ename} complete details"/>
<NamedData NDName="keyList" NDType="java.lang.String"/>
<NamedData NDName="taskParametersList" NDType="java.lang.String"/>
<NamedData NDName="viewId" NDType="java.lang.String"
NDValue="/DemoWorkArea"/>
<NamedData NDName="webApp" NDType="java.lang.String"
NDValue="DemoAppSource"/>
<NamedData NDName="methodParameters"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>
taskFlowId to be the parent task flow's, not the sub task flow's
When users click the link (the Ename) to which the openSubTask method is bound,
openSubTask will be called. This link component is defined as:
<af:column sortProperty="Ename" sortable="false"
headerText="#{bindings.ComplexSFEmpVO.hints.Ename.label}"
id="resId1c2">
<af:commandLink id="ot3" text="#{row.Ename}"
actionListener="#{bindings.openSubTask.execute}"
disabled="#{!bindings.openSubTask.enabled}"
action="toChild">
<af:setActionListener from="#{row.Empno}"
to="#{pageFlowScope.Empno}"/>
</af:commandLink>
</af:column>
actionListener and the action specified on the link are executed, in that order.
openSubTask is called only from the original parent task flow path (that is,
initParent), not from the sub task flow path (that is, toChild).
The EmployeeDetails activity in Figure 159 is a Task Flow Call activity that invokes
the ToChildSFFlow sub task flow. Before the sub task flow is executed, add
initialization steps. These initialization steps could include, but are not limited to:
Set up parent states. For this example, set the selected employee's row to be the
current row.
Set up states to allow the sub task flow to navigate back to the parent task flow.
For the first approach, you can add logic to initialize both paths before the task flow
call activity in the parent task flow. For the second approach, you initialize states in the
sub task flow by using input parameters of the sub task flow. For example, the sub
task flow will take an input parameter named Empno. In effect, the second approach
just postpones the initialization to the sub task flow.
The definition of input parameters in the task flow call activity is:
<task-flow-call id="EmployeeDetails">
<task-flow-reference>
<document>/WEB-INF/oracle/apps/xteam/demo/ui/flow/ToChildSFFlow.xml</document>
<id>ToChildSFFlow</id>
</task-flow-reference>
<input-parameter>
<name>Empno</name>
<value>#{pageFlowScope.Empno}</value>
</input-parameter>
</task-flow-call>
Note that this means that the calling task flow needs to store the value of Empno in
#{pageFlowScope.Empno}. For example, from the original parent task flow path, it is
set to be #{row.Empno} using the setActionListener tag. For the sub task flow path, it
is set using the parent task flow's input parameter Empno. On the sub task flow, you
need to specify its input parameters as:
<task-flow-definition id="ToChildSFFlow">
<default-activity>TochildSFPF</default-activity>
<input-parameter-definition>
<name>Empno</name>
<value>#{pageFlowScope.Empno}</value>
<class>java.lang.String</class>
</input-parameter-definition>
...
</task-flow-definition>
Note that the name of the input parameter (Empno) must be the same as the parameter
name defined on the task flow call activity. When the parameter is available, Oracle
ADF will place it in #{pageFlowScope.Empno} to be used within the sub task flow.
However, this pageFlowScope is different from the one defined in the task flow call
activity because they have a different owning task flow (that is, parent task flow
versus sub task flow).
The definition of the sub task flow is shown in Figure 1510:
Figure 1510
In the sample implementation, you implemented the initialization step in the sub task
flow. The Empno variable is passed as a parameter to the sub task flow and used to
initialize the parent state. When the sub task flow is started, the default view activity
(TochildSFPF) is displayed. Before it renders, the initPage method on the
ChildSFBean will be executed. The page definition of the default page is defined as:
<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel">
<parameters/>
<executables>
...
<invokeAction id="initPageId" Binds="initPage" Refresh="always"/>
</executables>
<bindings>
...
<methodAction id="initPage" InstanceName="ChildSFBean.dataProvider"
DataControl="ChildSFBean" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="initPage"
IsViewObjectMethod="false"
ReturnName="ChildSFBean.methodResults.initPage_ChildSFBean_
dataProvider_initPage_result"/>
...
</bindings>
</pageDefinition>
The initPage method is specified in the executables tag and will be invoked when
the page is refreshed. The initPage method itself is defined as:
public void initPage()
{
FacesContext facesContext = FacesContext.getCurrentInstance();
ExpressionFactory exp = facesContext.getApplication().getExpressionFactory();
DCBindingContainer bindingContainer =
(DCBindingContainer)exp.createValueExpression(
facesContext.getELContext(),"#{bindings}",DCBindingContainer.class).getValue(faces
Context.getELContext());
ApplicationModule am =
bindingContainer.getDataControl().getApplicationModule();
ViewObject vo = am.findViewObject("ComplexSFEmpVO");
vo.executeQuery();
Map map = AdfFacesContext.getCurrentInstance().getPageFlowScope();
if(map !=null){
Object empObj = map.get("Empno");
if(empObj instanceof Integer){
Integer empno =(Integer)map.get("Empno");// new Integer(empnoStr);
Object[] obj = {empno};
Key key = new Key(obj);
Row row = vo.getRow(key);
vo.setCurrentRow(row);
}
else
{
String empnoStr = (String)map.get("Empno");
Integer empno = new Integer(empnoStr);
Object[] obj = {empno};
Key key = new Key(obj);
Row row = vo.getRow(key);
vo.setCurrentRow(row);
}
}
}
The initPage method takes the input parameter Empno from #{pageFlowScope.Empno}
as a key to select a row and set it to be the current row in the master Employee table.
15.2.4 How to Use Additional Capabilities of the Recent Items openSubTask API
The openSubTask API has additional capabilities. For example, consider an employee
search page in which you enter parameters such as department number and manager
ID, and search for the matching employee records. You can use the openSubTask API to
register a search page with search parameters. The next time the user can see the
search results by just starting it from the Recent Items menu. This is similar to using
parametersList to specify search parameters while registering the search task flow.
While starting, additional programming can be done to retrieve the search parameters
and execute the query with the parameter values.
Favorites
As soon as tasks are recorded on the Recent Items list, they are eligible for Favorites.
The Favorites menu is implemented on top of Recent Items. Any current task on the
Recent Items list can be bookmarked and placed in the Favorites folders. Currently,
only a one-level folder is supported. Similar to Recent Items, tasks on the Favorites list
can be started directly from the list. So, the description in this section for Recent Items
applies also to the Favorites implementation. For example, sub flows based on the
design pattern described in this section can be registered on the Favorites list as well as
the Recent Items list.
15.2.5 How to Implement Data Security for Recent Items and Favorites
Data security controls access to the data displayed on the target. When data security is
enforced on the target page, any changes to the access that the user has is properly
reflected on the data.
However, there are use cases in Oracle Fusion Applications where the Recent Items
and Favorites features may cause security issues. In some cases there is a
master/detail relationship between objects in which only the parent object has data
security implemented. The child object has no data security enforced and is expected
to inherit security from the parent. In such cases, the user can only navigate to the
child task flow through the parent task flow. But because the child task flow can be
added as a Recent Item or Favorite, users can navigate directly to the child through
Recent Items, whether they still have access to the parent.
Data security ensures that user access is properly enforced on all flows that can be
accessed from Recent Items or Favorites.
Implementation
Implementation consists of ensuring that security is enforced consistently in all
scenarios and that authorization exceptions are handled by the standard central
method.
Security Enforcement
For function security, no additional implementation is required. The recommendations
for data security are:
Figure 1511
Code view objects with bind variables and default values for bind variables as
needed for calculating the Watchlist count. These view objects will be executed at
runtime by the Watchlist API to get the Watchlist count for the user.
Code task flows to enable drill-down from the Watchlist UI.
Seed FND deployments to specify host, port, and context root information for UI
drilldown and service invocation.
Seed FND standard lookups for each Watchlist category and item meaning.
Seed information to tell the Watchlist what counts to track, how to display them to
the user, which view objects to execute, and how to drill down to the work area
and tasks.
Import Watchlist JAR files as ADF libraries in service and UI projects.
Set up a service interface method so that product code and Watchlist code can
interact.
Table 151
ATK_WATCHLIST_CATEGORIES
Column Name
Datatype
Required
Comments
WATCHLIST_CATEGORY_CODE
VARCHAR2(100)
Yes
CATEGORY_LOOKUP_TYPE
VARCHAR2(30)
Yes
Reference to FND_STANDARD_LOOKUP_
TYPES.LOOKUP_TYPE
Product teams will seed the lookup type with
meaning for the category (VIEW_APPLICATION_ID
= 0 and SET_ID = 0). The translated lookup type
meaning is shown in the Watchlist UI for the
category.
OWNING_MODULE_NAME
VARCHAR2(4000) Yes
Reference to FND_APPL_TAXONOMY.MODULE_NAME
for the owning product or module. This is used
for seed data purposes.
OWNING_MODULE_ID
VARCHAR2(32)
Yes
OWNING_APPLICATION_ID
NUMBER
Yes
Reference to FND_APPL_TAXONOMY.ALTERNATIVE_
ID for the owning product or module. This is
used for seed data purposes.
REFRESH_SERVICE_ENDPOINT_
KEY
VARCHAR2(60)
Yes
REFRESH_SERVICE_NAME
VARCHAR2(400)
Yes
REFRESH_SERVICE_METHOD_
NAME
VARCHAR2(400)
Yes
ENABLED
VARCHAR2(1)
Yes
CREATED_BY
VARCHAR2(64)
Yes
CREATION_DATE
TIMESTAMP
Yes
LAST_UPDATED_BY
VARCHAR2(64)
Yes
LAST_UPDATE_DATE
TIMESTAMP
Yes
LAST_UPDATE_LOGIN
VARCHAR2(32)
Yes
Table 152
ATK_WATCHLIST_SETUP
Column Name
Datatype
Required
Comments
WATCHLIST_ITEM_CODE
VARCHAR2(100)
Yes
ITEM_LOOKUP_CODE
VARCHAR2(30)
Yes if WATCHLIST_ITEM_
TYPE != USER_SAVED_
SEARCH
Reference to FND_LOOKUPS.LOOKUP_
CODE
Product teams will seed the lookup
code with the meaning for the
parent category lookup type. The
translated lookup meaning is
shown in the Watchlist UI with the
count appended.
CATEGORY_CODE
VARCHAR2(30)
Yes
None
PRIVILEGE_BASED
VARCHAR2(1)
Yes
Yes if
OWNING_PRIVILEGE_NAME
PRIVILEGE_BASED = Y
FUNCTION_PRIVILEGE_NAME
VARCHAR2(400)
WATCHLIST_ITEM_TYPE
VARCHAR2(30)
HUMAN_TASK_DEF_ID
VARCHAR2(200)
Yes if WATCHLIST_ITEM_
TYPE = HUMAN_TASK
HUMAN_TASK_STATE
VARCHAR2(100)
Yes if WATCHLIST_ITEM_
TYPE = HUMAN_TASK
REFRESH_AGE
NUMBER(9)
Yes if WATCHLIST_ITEM_
TYPE != HUMAN_TASK
VIEW_OBJECT
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE != HUMAN_TASK
Datatype
Required
Comments
SUMMARY_VIEW_ATTRIBUTE
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE != HUMAN_TASK
and this is a summary
view object
APPLICATION_MODULE
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE != HUMAN_TASK
AM_CONFIG_NAME
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE != HUMAN_TASK
VIEW_OBJECT_INSTANCE
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE != HUMAN_TASK
VIEW_CRITERIA_ID
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE = SEEDED_SAVED_
SEARCH
NAVIGATION_URL_KEY
VARCHAR2(60)
Yes
VIEW_ID
VARCHAR2(400)
Yes
PAGE_PARAM_LIST_STRING
VARCHAR2(400)
No
TASKFLOW_ID
VARCHAR2(400)
Yes
TF_KEY_LIST_STRING
VARCHAR2(400)
No
Datatype
Required
Comments
TF_PARAMETER_STRING
VARCHAR2(400)
Yes if WATCHLIST_ITEM_
TYPE IN (SEEDED_
SAVED_SEARCH, USER_
SAVED_SEARCH)
TASK_TAB_LABEL
VARCHAR2(400)
Yes
ENABLED
VARCHAR2(1)
Yes
CREATED_BY
VARCHAR2(64)
Yes
CREATION_DATE
TIMESTAMP
Yes
LAST_UPDATED_BY
VARCHAR2(64)
Yes
LAST_UPDATE_DATE
TIMESTAMP
Yes
LAST_UPDATE_LOGIN
VARCHAR2(32)
Yes
Because this item is of type USER_SAVED_SEARCH, Watchlist items are created when
the user promotes a saved search on the search panel in Expenses. This invokes a
Watchlist service on the Watchlist that does the Watchlist item creation. This is not
needed for Watchlist items of type SEEDED_QUERY or SEEDED_SAVED_SEARCH.
A request to refresh the Watchlist item count comes from the Watchlist portlet.
This will invoke an exposed service, which delegates the call to a method on a
provided Watchlist JAR file.
The method on the Watchlist JAR file will take care of rerunning the query (on the
expenses database) and taking the results to update the Watchlist item count (on
the Watchlist database).
Determine or set up view objects to execute the query for Watchlist count. You
may want to include view criteria with bind variables and specify default values
for bind variables. (Not needed for Human Task)
For example, most view objects seeded for the Watchlist would filter by user to
show counts specific to the logged-in user. You could create a view criteria with a
bind variable called userId and specify the default value as a groovy expression to
determine the current user ID from the security context. You then would seed this
view criteria ID in the setup table along with the view object. The Watchlist API
would execute the view object by applying this view criteria to get the row count.
Example 159 shows code from the view object xml for a bind variable with a
default value.
Example 159
Value
Example Code from the View Object XML for Bind Variable with Default
<Variable
Name="userId"
Kind="where"
Type="java.lang.String">
<TransientExpression><![CDATA[return
adf.context.securityContext.userName;]]></TransientExpression>
</Variable>
(Optional) Set up a summary view object to facilitate a refresh count and specify
the summary attribute in the Watchlist setup table. Watchlist code would use this
information to query the count instead of doing a rowcount on the executed view
object results.
Include Watchlist model JAR files in your service project and set up a
refreshWatchlistCategory service method. This method only will contain code
to delegate the call to the nested Watchlist application module method that
actually executes the view object queries by reading your Watchlist setup data.
This requires that all the corresponding model projects are included as JAR files in
this service project so view objects are available in the class path. This service
should be exposed so that the Watchlist UI can use it to start the refresh process.
Determine and code task flows for drilldown from the Watchlist UI. There is no
special coding required for these task flows; the key-value parameter string that
you specify in the setup table will be used as the input parameter list when
invoking the specified task flow for the UI drilldown on Watchlist items.
(Optional) Enable saved search promotion to the Watchlist. Include Watchlist
model JAR files in the corresponding project for the query panel and work with
the Watchlist API. For promotion and demotion of user-saved searches, code must
invoke a method in the provided Watchlist JAR, which then will handle
interaction back to the Watchlist. Add promotion and demotion components on
the search panel so that saved searches can be used as Watchlist items.
Include Watchlist UI and Protected model JAR files in your UI SuperWeb project,
to enable Watchlist menu drilldown in the UI Shell Global Area, as shown in
Figure 1512.
Figure 1512
Create FND_LOOKUPS for the displayed Watchlist category and item meaning (FND_
STANDARD_LOOKUP_TYPES.LOOKUP_TYPE). Product teams must seed the lookup type
with the meaning for the category (VIEW_APPLICATION_ID = 0 and SET_ID = 0).
The translated lookup type meaning is shown in the Watchlist UI for the category,
while the corresponding lookup value meanings are shown in the Watchlist UI for
items (user saved search item meanings come from the saved search directly).
Product teams must create seed data for this lookup.
Example 1510 presents sample code to create or update the lookup.
-- X_DESCRIPTION
-- X_ENABLED_FLAG
-- X_START_DATE_ACTIVE
-- X_END_DATE_ACTIVE
-- X_DISPLAY_SEQUENCE
);
end;
IN
IN
IN
IN
IN
Seed Watchlist categories and setup information. Create your category in ATK_
WATCHLIST_CATEGORIES and then seed your items in the reference data table (ATK_
WATCHLIST_SETUP). The watchlist_item_type determines how the Watchlist code will
handle the item.
HUMAN_TASK items only require seeding in the tables to work;
there are no view objects to create.
Note:
15.3.4.1 Making the Watchlist Link in the UI Shell Global Area Work
To ensure the Watchlist link works in your pages, complete these steps.
Add this ADF Library JAR file to the SuperWeb user interface project for your
application (the JAR file must be part of your Web Archive (WAR) in the
WEB-INF/lib directory):
fusionapps/jlib/AdfAtkWatchListPublicUi.jar
Add this dependent model ADF Library JAR file in your application (the JAR file
must be part of your Enterprise Archive (EAR) in the APP-INF/lib directory):
fusionapps/jlib/AdfAtkWatchListProtectedModel.jar
Add this dependent resource bundle ADF Library JAR file in your application (the
JAR file must be part of your EAR in the APP-INF/lib directory):
fusionapps/jlib/AdfAtkWatchListPublicResource.jar
Add these resource-ref entries to the web.xml file in your SuperWeb user
interface project:
<resource-ref>
<res-ref-name>wm/WorkManager</res-ref-name>
<res-type>commonj.work.WorkManager</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<resource-ref>
<res-ref-name>jdbc/ApplicationDBDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
By default, Watchlist code will access the application module or view object that is
specified in the setup table, and rerun the query to refresh the Watchlist count. The
summary view object is one way to get the count. Usually this will be for
efficiency reasons.
The product team can signal that it wants the Watchlist code to use its summary
view object by seeding something in SUMMARY_VIEW_ATTRIBUTE of ATK_WATCHLIST_
SETUP. If this is not null, the Watchlist code will get the view object, but instead of
running the query, it will take only the first row and get the specified attribute.
Your task is to create a view object with the correct count in the attribute specified
in the setup table.
15.3.4.3.1 Summary Tables One common reason to use a summary view object is if the
seeded query is based on Multiple-Organization Access Control (MOAC) data
security. This is because you can calculate the count of this query for each Business
Unit ID (BUID). The count of a user is just the sum of the counts of the BUIDs that the
user can access.
For example, say you have a table (or query) that has three rows of BUID #1, three
rows of BUID #2, and three rows of BUID #3. The current user has access to BUIDs #1
and #2.
If you wanted to get the count, MOAC would filter the rows by BUID and return six
rows.
However, because you are interested only in the count, a more efficient way would be
to create a summary table for this table. The summary table keeps track of the count
for each BUID. For the example table, the summary table would resemble Table 153.
Table 153
BUID
Count
Now, instead of using MOAC to find a count for a particular user, you use MOAC to
find the sum of counts for the user. The example user would get the first two rows
returned, and you can calculate the total count by summing the count column.
You can use summary tables to populate the summary view object attribute.
Use the UI to create saved searches and name them. For each saved search, select
Run Automatically.
Inside that directory, there should be an xxxVO.xml.xml file that contains the
created saved searches. Keep that file.
In that XML file, note the saved search ID, which should match the View Criteria
ID in the reference data.
This ID can be different than the display name that you
entered in the saved search UI.
Note:
15.3.4.5 Creating Application Module and View Objects (All except HUMAN_TASK)
Refer to Section 15.3, "Implementing the Watchlist."
15.3.4.10 Importing Watchlist JAR Files into the Saved Search Project (USER_
SAVED_SEARCH)
For subsequent steps that require running Watchlist APIs from your code, you must
import the Watchlist JAR files. These also contain an AppMasterDB connection that
must point to the Watchlist database.
Populate ATK tables with SEED watchlist category information. Product teams
need to provide information about the service that refreshes the watchlist item
count.
Populate ATK tables with appropriate watchlist setup information. There must be
a watchlist setup item of type USER_SAVED_SEARCH.
Ensure the application is MDS enabled so users can save their searches and that
the saved searches exist across sessions.
From the watchlist UI, users can drilldown to the transactional UI flows. Ensure
that the transactional UI flow is properly set up so that it can show the search page
when the user clicks the Watchlist item in the Watchlist UI.
In the application project, create a backing bean and register it as a
backingBeanScope bean. In the backing bean, create the Java method shown in
Example 1512:
15.3.4.11.1 How to Promote a User-Saved Search to the Watchlist Follow these steps to
integrate the ATK task flow to promote saved searches to the Watchlist.
If you already have implemented promoting the user-saved
search to the Watchlist, see Additional Steps for Existing Consumers.
Note:
1.
2.
Start JDeveloper and open the .jspx or .jsff page containing the query region whose
saved searches have to be promoted.
3.
b.
c.
Figure 1513
4.
In the toolbar facet of the query region, drag and drop an ADF Toolbar
component, such as Toolbar (ADF Faces.Common Components) shown in
Figure 1514, onto the page.
Figure 1514
The toolbar facet in the Source view will look similar to:
<f:facet name="toolbar">
<af:group id="g1">
<af:toolbox id="t1">
<af:region
value="#{bindings.AtkWatchlistUserSavedSearchPromotionTF1.regionModel}"
id="r7"/>
</af:toolbox>
<af:toolbar id="t2"/>
</af:group>
</f:facet>
5.
Open the Resource Palette and create a File System connection to the directory
containing the AdfAtkWatchListPublicUI.jar file, as shown in Figure 1515.
Figure 1515
6.
Expand the connection node and the ADF library node in the Resource Palette as
shown in Figure 1516.
Figure 1516
When the ADF Task Flows node is expanded, you should see two task flows. The
task flow AtkWatchlistUserSavedSearchPromotionTF is the one to be used.
7.
Select the userSavedSearchList input field, click the small "v" icon present
at the end of the field and select the Expression Builder option.
b.
Select the value from the Java method shown in Example 1512. In this
case, the value is watchListUserSavedSearchList, found in ADF
Managed Beans > backingBeanScope >
searchOrderScheduleBackingBean > watchListUserSavedSearchList.
The Expression will be:
#{backingBeanScope.searchOrderScheduleBackingBean.watchListUserSavedSea
rchList}
c.
When you are finished, the Edit Task Flow Binding dialog will resemble
Figure 1517.
Figure 1517
8.
Figure 1518
9.
Open the page definition file and select the executable associated with the
Watchlist-related task flow.
10. Open the Property Inspector and set the Refresh field to ifNeeded, as shown in
Figure 1519. The ATK saved search promotion task flow has to be refreshed each
time the query model changes. This step ensures that the task flow is refreshed
whenever the query model changes.
Figure 1519
Open the jazn-data.xml file and select the ADF Policies tab.
b.
Figure 1520
12. Run the UI page. In the toolbar facet of the query region, there will be a Watchlist
When you click the button, a popup with the list of all saved searches is displayed,
as shown in Figure 1522.
Figure 1522
In your pageDef, change the WatchList task flow parameter called queryModel
from:
<parameter id="queryModel"
value="#{bindings.ExistingCriteria.queryModel}"/>
to:
<parameter id="userSavedSearchList"
value="#{backingBeanScope.YourBean.watchListUserSavedSearchList}"/>
to:
parameter id="internalCriteriaName"
value="#{backingBeanScope.searchRelatedBean.internalCriteriaName}"
javax.el.ExpressionFactory;
javax.el.MethodExpression;
javax.el.ValueExpression;
javax.faces.context.FacesContext;
oracle.adf.model.binding.DCBindingContainer;
oracle.jbo.uicli.binding.JUSearchBindingCustomizer;
15.3.4.12.1 Saved Search For saved search Watchlist items, you will want the drilldown
to load a specific saved search by default.
One function of the Watchlist portlet will be to take a user to the corresponding action
area when the user clicks a Watchlist item. For saved searches, the desired
functionality is to open the task flow containing the saved search panel and by default,
show the clicked saved search.
On the portlet, upon clicking the link, code will put the proper ViewCriteria name
into the PageFlowScope with the parameter name vcName.
When loaded, the destination task flow will have two tasks:
Obtain the RichQuery object, and apply the ViewCriteriaName to it, if one is given.
You will be concerned with implementing the two steps for the destination task flow.
First, you can retrieve the ViewCriteriaName from the PageFlowScope with the code
shown in Example 1514.
Example 1514 Retrieving the ViewCriteriaName from the PageFlowScope
Map pfs = RequestContext.getCurrentInstance().getPageFlowScope(); String vcName =
(String) pfs.get("vcName");
Second, you can use the code shown in Example 1515 to apply the ViewCriteria to
the search panel. If no ViewCriteria was passed, the code loads the default
ViewCriteria.
Example 1515 Applying ViewCriteria to the Search Panel
if (vcName == null || vcName.equals("")) {
// If no ViewCriteria is given, load default VC
DCBindingContainer dcbc =
(DCBindingContainer)BindingContext.getCurrent()
.getCurrentBindingsEntry();
FacesCtrlSearchBinding fcsb =
(FacesCtrlSearchBinding)dcbc
.findExecutableBinding("ImplicitViewCriteriaQuery");
FacesCtrlSearchDef def = (FacesCtrlSearchDef)fcsb.getDef();
DCParameterDef paramDef =
(DCParameterDef)def.getParameterDef(
JUSearchBindingCustomizer.PARAMCRITERIA);
fcsb.evaluateParameter(paramDef.getExpression(),false));
} else {
QueryModel model = search_query.getModel();
QueryDescriptor selDescriptor = model.create(vcName, null);
if (selDescriptor != null) {
model.setCurrentDescriptor(selDescriptor);
}
BindingContainer bindings =
BindingContext.getCurrent().getCurrentBindingsEntry();
OperationBinding method = (OperationBinding)
bindings.getControlBinding("applyViewCriteriaByName");
method.getParamsMap().put("name", vcName);
method.execute();
}
This code should be run once upon loading the destination task flow. One solution is
to connect it to the rendered property of the search panel, and use a static variable to
ensure that it only runs once.
15-40 Developer's Guide
Add this entry in the ejb-jar.xml file in your service project that contains the
watchlist service next to the similar entry for ApplicationDB. You need
resource-ref entries for both ApplicationDB and AppMasterDB:
<resource-ref>
<res-ref-name>jdbc/AppMasterDBDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
Add this entry in the web.xml file in your SuperWeb project next to the similar
entry for ApplicationDB. You need resource-ref entries for both ApplicationDB
and AppMasterDB:
<resource-ref>
<res-ref-name>jdbc/AppMasterDBDS</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
The connections.xml file should have a valid database entry for AppMasterDB.
15.4.1 Assumptions
These assumptions are made:
2.
3.
b.
c.
d.
To make a homepage tab appear within UI Shell, deploy the Functional Setup
Manager application.
When the Group Spaces link is clicked, a popup displays the logged-in user's
Group Spaces.
When the user clicks a Group Space from the list, the Group Space's home page is
opened in an iFrame. This iFrame is rendered within a Home Page tab called
WebCenter. The Group Space is opened suppressing the WebCenter Portal chrome
but will still render all the tabs within that Group Space. (Note: Chrome is a term
for the visible graphical interface features of an application.) This chrome level
suppresses the WebCenter Portal chrome but will still render all the tabs within
that Group Space.
When the user clicks View All Group Spaces, the same UI as the My Group
Spaces in the spaces application is rendered. This is also rendered as an iFrame
within the WebCenter Portal HomePage tab where it suppresses the chrome as
well as the top level WebCenter Portal tabs.
Actor - The user who performed the action that triggered the business event. For
Oracle Fusion Applications, this will be the userid fetched from the user session.
ActivityType - The type of Activity to be published. This defines the format of the
Activity message.
Objects - The objects associated with the Activity. There could be multiple objects
associated with an Activity, but for business events, only the event source is used
as an object.
{actor[0]}: Replaced by the display name of the user who triggered the event.
{object[0]}: Replaced by the value of the attribute in the event payload whose
attribute name matches the object type name.
{custom[attr1].value}: Replaced by the value of the attr1 attribute in the
event's payload.
BusinessActivity Class
This is an abstract class that is used to represent an Activity corresponding to a
business event. BusinessActivityPublisher:publishActivity() takes an instance of
this class as a parameter. You would implement an instance of this class to encapsulate
the details of the Activity corresponding to the non entity object-based model changes
and invoke the publishActivity API with this as a parameter.
BusinessActivityPublisher will find the matching ActivityType and ObjectType
defined for this Activity in service-definition.xml and publish the Activity to the
ActivityStreaming Service asynchronously. Details of the API on this class are shown
in Example 1517.
Example 1517 BusinessActivity.java
/**
* Name of the ActivityType defined in service-definition that
* corresponds to serviceId returned by getServiceId().
* @return Name of the ActivityType
*/
public String getName()
/**
* ID of the service-definition containing the metadata for this
* Activity.
* @return serviceId
*/
public abstract String getServiceId();
/**
* Array of GUIDs for Actors of the Activity.
* @return array of guids for the Actors.
*/
public abstract String[] getActors();
/**
* This api will return additional service ids
* @return Array of ServiceIds
*/
public String[] getAdditionalServiceIds(){ return null};
/**
* This attr provides a "," separated list of object type
* names associated with a particular Activity.
* @return
*/
protected String getActivityObjectTypeNames(){
return null;
}
**
* Payload for the Activity. Every attribute that is part of this payload is
* persisted in WC as custom attribute of the Activity Object so only
* attributes needed for the Activity Message should be added to the payload
* to avoid performance overhead.
* The payload typically contains:
* 1. Attribute(s) whose name matches the object-type name attribute in
*
service-definition. This value is used in generating the object-id
*
of the object referenced in the Activity Stream message.
* 2. All the attributes referenced in the Message format using {custom}
*
token.
* @return a map containing the attribute names and their values needed to
* display the Activity Message for this Activity.
*/
public abstract Map getPayload();
BusinessActivity
This is an abstract class that is used to represent an Activity corresponding to a
business event. BusinessActivityPublisher:publishActivity() takes an instance of
this class as a parameter. You would implement an instance of this class to encapsulate
the details of the Activity corresponding to the non entity object-based model changes
and invoke the publishActivity API with this as a parameter.
BusinessActivityPublisher will find the matching ActivityType and ObjectType
defined for this Activity in the service-definition.xml file and publish the Activity
to the ActivityStreaming Service asynchronously. Details of the API on this class are
shown in Example 1518.
Example 1518 BusinessActivity.java
/**
* Name of the ActivityType defined in service-definition that
* corresponds to serviceId returned by getServiceId().
* @return Name of the ActivityType
*/
public String getName()
/**
* ID of the service-definition containing the metadata for this
* Activity.
* @return serviceId
*/
public abstract String getServiceId();
/**
* Array of GUIDs for Actors of the Activity.
* @return array of guids for the Actors.
*/
2.
3.
On the business events page, expand the Event Publication section and click the
Edit event publications icon.
4.
In the Edit Event Publications dialog, click New to create a new event.
5.
Double-click the new cell in the Event column, and select the appropriate event.
6.
Double-click the corresponding cell in the Event Point column, and select the
appropriate event point action.
7.
You optionally can define conditions for raising the event using the Raise
Conditions table.
8.
Click OK.
An event definition in the Entity XML file would look similar to:
<EventDef Name="OpportunityStatusUpdate">
<Payload>
<PayloadItem AttrName="OpptyId"/>
<PayloadItem AttrName="Status"/>
<PayloadItem AttrName="Customer.CustomerId"/>
</Payload>
</EventDef>
Overriding isActivityPublishingEnabled()
Method
Return
Type
Description
Corresponding
Declarative
Transient Attribute
Optional/ (See
Required Section 15.5.4.3)
isActivityPublishingEna
bled()
None
getActivityActorsGUIDs(
)
WCActivityActorGui
d1,
WCActivityActorGui
d2
Return
Type
Method
Corresponding
Declarative
Transient Attribute
Optional/ (See
Required Section 15.5.4.3)
Description
getActivityStreamServic
eId()
String
getAdditionalServiceIds
()
Optional
WCAdditionalActivi
tyServiceId1,
WCAdditionalActivi
tyServiceId2
getActivityObjectTypeNa
mes()
String
Optional
WCActivityObjectTy
peNames
WCActivityServiceI
d
The different transient attributes that can be passed with the payload are shown in
Table 155.
Table 155
Attribute
Type
Description
Sample Value
WCActivityServiceId
String
oracle.apps.crmdemo.model.Opportunity
EO
WCAdditionalActivityServiceId1
String
WCAdditionalActivityServiceId2
String
WCActivityActorGuid1
String
<User_GUID>
WCActivityActorGuid2
String
<User_GUID>
WCActivityObjectTypeNames
String
Emp, Dept
1.
Ensure your user interface project includes the Oracle WebCenter Portal Activity
Streaming Service library in the Libraries and Classpath section in the project
properties dialog.
2.
From Resource Catalog > TaskFlows, drag and drop either an "Activity Stream" or
"Activity Stream Summary - View" task flow onto the page where you want to
display the Activity Stream UI.
3.
4.
For additional details about the Activity Stream task flow, see the chapters in the
"Working with the People Connections Service" partition in the Oracle Fusion
Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.
If necessary, add the directory to the application's MAR profile. To add a MAR,
select Application > Application Properties > Deployment. In the dialog that is
displayed, select the MAR file and click Edit.
2.
In the Edit dialog, select User Metadata and click Add. Browse to the metadata
directory that was just added and click OK.
3.
Set the id attribute on the service-definition element to the entity object name
for which you want to define the Activities.
<service-definition xmlns="http://xmlns.oracle.com/webcenter/framework/service"
id="oracle.apps.crmdemo.model.OpportunityEO"
version="11.1.1.0.0">
4.
Define an activity type for every business event in the entity object for which you
want to display the Activities in the Activity Stream UI. Ensure the event name of
the entity object matches the activity-type name attribute value.
<activity-types>
<generic-activity-category name="UPDATE">
<activity-type name="OpportunityStatusUpdate"
displayName="Opportunity Status Update"
description="Opportunity Status Update"
messageFormatKey="OPPTY_STATUS_UPDATED"
iconURL=""
defaultPermissionLevel="SHARED"/>
</generic-activity-category>
</activity-types>
5.
Each activity-type should have a message format defined. The message format
string can be translated and is stored in a Resource Bundle or an XLIFF bundle.
Oracle Fusion Applications uses XLIFF bundles to store the Activity message
format strings. The activity-type element in the service-definition.xml file
has messageFormatKey attributes that are used to refer to the format strings in the
XLIFF bundle.
Activity Stream supports only Java Resource Bundles. The Common String
Repository is used for the message format strings.
These attributes are supported on the activity-type element:
messageFormatKey
The value of this attribute points to the key defined in the Resource Bundle. These
tokens are supported in the message format string.
{actor[0]}: Replaced by the display name of the user who triggered the
event.
{object[0]}: Replaced by the value of the attribute in the event payload
whose attribute name matches the object type name.
{custom[attr1].value}: Replaced by the value of the attr1 attribute in the
event's payload.
b.
Summarize or aggregate the Actors either by listing them if there are three or
fewer, or by counting them if there more than three.
c.
b.
c.
d.
e.
f.
Example 1519 shows sample format strings for the preceding scenario.
Example 1519 Sample Format Strings for a Summarized View
<resource-bundle-class>oracle.apps.crm.OpportunityResourceBundle</resource-bundleclass>
<activity-types>
<generic-activity-category name="OPPTYUPDATE">
<activity-type name="OpptyStatusUpdate"
displayName="OPPTY_UPDATE"
description="OPPTY_UPDATE_DESCRIPTION"
messageFormatKey="OPPTY_STATUS_UPDATED"
summaryByListMessageFormatKey="OPPTY_STATUS_UPDATED_SUMMARY_LIST"
summaryByCountMessageFormatKey="OPPTY_STATUS_UPDATED_SUMMARY_CNT"
defaultPermissionLevel="SHARED"/>
</generic-activity-category>
</activity-types>
Define an object type for the entity object that is the source of the events. Even
though Oracle WebCenter Portal supports multiple object types, for Oracle Fusion
Applications, only one object type that corresponds to the source of the events is
supported. The value of the name attribute should match the name of the attribute
in the business event's payload. This attribute's value will be used as the display
name of the object when displayed in the Activity message. The primary key of the
event source will be used as the object ID.
<object-types>
<object-type name="OpptyId"
displayName="Opportunity Object"
description="Opportunity Object"
Implementing Search Functions in the UI Shell 15-53
iconURL="">
</object-type>
</object-types>
7.
Table 156
The ObjectType custom attributes can be used to provide additional metadata for
handling business object references in Activity Stream messages. The custom
attributes shown in Table 156 will be used.
Name
Description
service-ref-id
object-id-attr
The name of the attribute in the business event payload that is necessary as the
object-id for an Activity object. Typically this corresponds to the primary key attribute
of a business object. If this attribute is not specified, the object-type element's name
attribute is used as the default.
display-name-attr
The name of the attribute in the business event payload that is necessary as the
display name of the Activity object. This attribute's value will be used to replace the
{object} token in the Activity's message format.
<object-type>
<custom-attributes>
<custom-attribute name="service-ref-id"
defaultValue="oracle.apps.crm.model.OpptyEO"/>
<custom-attribute name="object-id-attr" defaultValue="opptyId"/>
<custom-attribute name="display-name-attr" defaultValue="opptyName"/>
</custom-attributes>
</object-type>
8.
Define resource view handler parameters to allow custom navigation for links
rendered in the Activity message. Navigation from the Actor link in the Activity
message navigates to the user's portrait page. Custom navigation to the business
object workarea is supported. Important fields include:
<wpsC:adf-service-config
xmlns:wpsC="http://xmlns.oracle.com/webcenter/framework/service">
<resource-handler
class="oracle.apps.fnd.applcore.tags.handler.FndResourceActionViewHandler"/
>
</wpsC:adf-service-config>
Ensure the activity-type names are as shown. The messageFormatKey values refer to
the ResourceBundle keys that provide strings displayed for "comments" and "likes"
links displayed in the Activity message.
objectType, "");
System.out.println("Calling Follow for Case : " + id);
followedObject.setServiceID(serviceID);
followManager.followObject(actor, followedObject);
}
catch(ActivityException ae) {
ae.printStackTrace();
System.out.println("Case follow failed");
}
}
If you have implemented ECSF and defined the SearchDB connection, the saved
searches are saved to the Oracle database and are persisted across sessions.
Data Security Integration
Data security (limiting search results to only those items to which the user has
authorized access) is handled by the ECSF.
Remove the ECSF libraries (oracle.ecsf shared lib). Oracle Fusion Applications
Search will detect the missing dependency and disable itself for all pages in the
current user session, even if the user opens a web application that does have the
ECSF libraries available.
Setup switch using a JVM system property.
-DFUSION_APPS_SEARCH_ENGINE_AVAILABLE=N
Figure 1523
Search Term
This is a text field for the values on which to search. The field can hold a maximum of
2048 characters.
The term is searched for in any of the crawled data, which includes the title, fixed and
variable content, attached documents, and tags. So if the search term is foo, the search
returns any data containing the word foo.
Click the Play button to initiate the search.
Today
LastModifiedDate equals "todays date."
This Week
LastModifiedDate >= "last Sunday" AND LastModifiedDate <= "this Saturday"
This Month
LastModifiedDate >= "first day of month" AND LastModifiedDate <= "last day of
month"
This Year
LastModifiedDate >= "first day of year" AND LastModifiedDate <= "last day of
year"
Last Year
LastModifiedDate >= "first day of last year" AND LastModifiedDate <= "last day
of last year"
Categories
When you click the Categories button, a list, similar to that shown in Figure 1525, is
displayed:
Figure 1525
The user can select from the list of Categories and enter a search string. Unchecking
the All category unchecks all of the categories. The subset of selected categories will be
displayed in the entry area of the dropdown list as a concatenated list separated by a
semicolon.
Note: Categories are not set up at design time by developers. They
should be set up either by customers or seeded by teams. Categories
are created and stored in ECSF schema, and ECSF provides an API to
get a list of categories to the UI for a given user.
Oracle Fusion Applications Search uses the ECSF APIs to mimic the SES search and
show the alternate words to the user. Clicking the alternate word does a new search
using the selected alternate word as the new keyword.
Saved Searches
Click the Saved Searches magnifying glass icon to open a list of saved searches. The
list shown in Figure 1526 includes a Personalize action item that will display the
Personalize Saved Searches dialog so that saved searches can be deleted or renamed.
Figure 1526
Show Results of Last Search: Displays the output of the last search.
Personalize: Becomes active if there is a saved search. Click this link to rename or
delete a saved search, as shown in Figure 1527.
Figure 1527
To rename a saved search, select it, enter a new name in the Name field, and click
OK.
To delete a saved search, select it and click Delete.
Note:
Note:
Figure 1528
A Results section. On the initial query, all selected categories that have a non-zero
count will be displayed. That is, if a category has zero results, it will not be
displayed. This helps reduce clutter. Only the first category will be expanded. The
other categories must be manually expanded.
Each result found under a category provides a navigation link back to the record.
the count exact, start SES and select Global Settings > Query Configuration, and click
the Exact count radio button, as shown in Figure 1529. Note that SES warns against
this for performance reasons. See the Oracle Secure Enterprise Search Administration
Online Help.
Figure 1529
Sort By
This function requires no developer implementation; it is built in.
Users can sort results in the results table. The sort may be done in ascending or
descending order, and may be switched using a toggle button.
The sort will be available in two forms, depending on the search parameters:
Figure 1530
The Search result will be expanded in the background from the initial 10 results
returned with the query, to 100 results returned by a background search started in a
separate thread as soon as the 10 results are successfully returned. This is to give a
reasonable result to sort. The sort UI will show a spinner and will be disabled until this
is finished, and the UI will poll for completion every two seconds and enable those
fields. This polling will stop when the background search is complete, or after a fixed
number of polls (to stop infinite polling in case of error).
In addition, if there are fewer than 100 results in total, the "About xx Results" header
will be replaced with "xx Results", indicating the exact number returned.
The default Sort is Relevance descending, which is the way that records are returned
by SES.
The sort is done in memory using a standard Java Collections.sort function, and a
comparator that takes into account the date type of the attribute
(Date/Number/String) and direction.
Recent Searches
Recent Searches retains the last 10 searches conducted by each user over sessions and
makes them available to users to select and run. Keywords entered by the user serve as
the name of the recent search, with digits appended for uniqueness, as needed.
Recent Searches is accessed from the Saved Searches dialog by selecting the Recent
Searches tab, as shown in Figure 1531.
Figure 1531
Clicking any linked portion of the recent search description runs the search and starts
the Oracle Fusion Applications Search dialog to display the results.
Recent searches are implemented using the ECSF recent searches feature. See
Section 33.5, "Managing Recent Searches."
A recent search is uniquely identified by its filters, such as search term, categories, and
facet selections.
A search will be added to the front of the recent search list when performed. If it
already exists in the list, it will be moved from its current place in the list to the front.
You may use this view object using a view link and a predefined Search extension to
enable the crawling of Oracle WebCenter Portal Tags, both in initial and incremental
(someone has updated the tags) crawls.
Follow these steps:
1.
Create your Searchable view object as usual. Example 1526 uses a Searchable
view object over FND_LOOKUPS_VL in the query.
See Section 15.1, "Implementing Tagging Integration" for setting up tags in your
UI. Figure 1532 shows the attributes for lookup types.
Do not forget to mark your key columns and ensure the order
is consistent between the view object and the
tag:taggingButton.resourceId attribute.
Note:
Figure 1532
Figure 1533 shows the attributes for Searchable view object lookup types.
Figure 1533
2.
Add a view link to the TagSVO (service view object) linking the Search view object
and the Applications Core Tag view object.
The view link should look similar to Figure 1534.
Figure 1534
3.
Update the Body field to include the tags of the child view object in the relevant
position in the string as defined by your management.
This will be an expression of the form <accessor Name>.Tag, such as tagSVO.Tag.
Update the Searchable View Object Search Plugin field (see Figure 1534, "View
Link Example") to "oracle.apps.fnd.applcore.search.TagSearchPlugin", or as shown
in Example 1528, create a subclass so that you can incorporate your security rules.
Ensure you add a parameter passing the service ID of the Search view object. This
may be done by clicking the LOV symbol next to the Search Plugin field, shown in
Figure 1533. See Figure 1535.
Figure 1535
Search Plugin
There are two parameters, shown in Table 157, that may be passed to the
extension.
Table 157
Parameter
Required Description
TAG_SERVICE_ID
Yes
KEY_SPLITTER_CLASS
No
2.
You now can crawl using the command-line script. A full crawl will be done first, then
on subsequent crawls the incremental functionality will call the getChangeList()
method.
15.6.5 How to Use the Actionable Results API with Oracle Fusion Applications Search
This section details how to set up ECSF searchable objects to use with Oracle Fusion
Applications Search. For information about setting up your global search
infrastructure, see Chapter 28, "Getting Started with Oracle Enterprise Crawl and
Search Framework."
Figure 1536 shows the result that will be produced (a single row in the search results
table).
Implementing Search Functions in the UI Shell 15-69
Figure 1536
Any other required information would be added later is the Variable Content.
As shown in Figure 1537, ECSF searchable objects support two distinct Action Types:
URL and Task. See also Figure 1538 and Figure 1539.
Most Oracle Fusion Applications will use the Task type with specific named
parameters to integrate with the UI Shell; however both types will work.
Figure 1537
Fixed Content
The Fixed Content is derived from the Search Properties Title field.
Variable Content
The Variable Content is derived from the Search Properties Body field.
For URL Action Types, the Oracle Fusion Applications Search will open a new browser
tab or window containing the URL. To configure this type, add a URL Search Result
Action with these parameters.
A unique name
iconURL Parameter
Name
Required
Description
iconURL
No
The icon will be shown in the search results with the title given in the Title field. When
clicked, a new browser tab or window will open with this URL.
Figure 1539
For Action Types of Task, the Oracle Fusion Applications Search will open a UI Shell
tab in the current page, or a new page containing the task flow. To configure this type,
add a Task Search Result Action with these parameters.
A unique name
A Title
Parameters are shown in Table 159. Note that, although this table resembles
Table 1510, it presents the use case that the majority of users will use. The information
in Table 1510 is for a very small use case.
The action will be shown in the search results with the title given in the Title field.
When clicked, a new UI Shell tab window will open with this task flow. If the viewId
parameter is for the current page, the UI Shell tab will be in the current page;
otherwise the current page will be replaced with a new UI Shell page with the search
result.
Do not enter double quotation marks around the groovy
expressions; use single quotation marks instead.
Note:
Table 159
Name
Required Description
viewId
Name of the page. This is shown in the browser URL bar. For example,
in http://127.0.0.1:8989/context-root/faces/TestUIShellPage, it
would be /TestUIShellPage (Note the leading slash).
pageParametersList
taskFile
taskName
The task flow definition ID. Available from the task definition file
<task-flow-definition> ID attribute. For example,
<task-flow-definition id='task-flow-definition'> would be
"task-flow-definition". See Section 15.6.5.3, "Passing Parameters in
Oracle Fusion Applications Search".
navTaskKeyList
Key list to pass into the task flow to open in the target workspace. This
is a semicolon delimited string of keys or key-value pairs. For example
"key1;key2=value2"
navTaskParametersList
iconURL
toolTip
navTaskLabel
Label to show on the results tab. Set the tab title of the tab that is opened
after clicking a search result action. If not set, it will use the Action
Name (the value shown in the results).
webApp
Attribute used to look up the host and port of the associated WorkArea
or Dashboard from the Oracle Fusion Applications Functional Core
(ASK) deployment tables. These tables are populated at deployment
time through Oracle Fusion Functional Setup Manager tasks.
For Integer types, this is largely automatic (if you reference the
parameter as a String in the task flow), but use caution for dates and
decimals.
15.6.5.2.1 How to Implement Preferred Navigation Oracle Fusion Applications Search
supports two parameters, applicationStripe and pageDefinitionName, in task search
actions that, if they are present, change the definition of the other task action
parameters used for navigation. These parameters all become "caret delimited." That
is, instead of having one value per parameter, they have multiple values, and they are
delimited by the caret "^" character. In this case, all parameters must have the same
number of delimited parts.
Divide all delimited parameters based at the caret, and produce an ordered list of
targets that can be opened.
For each target, determine if the user can open the page and task flow.
Whatever the outcome of the permissions check, you must ensure that at least one
target can be opened, otherwise users will be presented with a blank page when they
click the search result.
The parameters and descriptions for Preferred Navigation are shown in Table 1510.
Note that, although this table resembles Table 159, it presents a more complicated use
case in which developers want to do a security check and direct the user to the most
secure end point (the first allowed one in the list). The meaning of these columns
changes with the caret delimitation; that is, a caret-delimited list of the old values, as
well as two new parameters. Most users need to use only the information in Table 159.
Table 1510
Name
Delimited
Required by caret "^" Description
applicationStripe
pageDefinitionName
viewId
webApp
Table 1510
Name
Delimited
Required by caret "^" Description
pageParametersList
taskFile
taskName
navTaskKeyList
Key list to pass into the task flow to open in the target
workspace. This is a semicolon delimited string of keys or
key-value pairs. For example
"key1;key2=value2^anotherKey1;anotherKey2=value2"
navTaskParametersList
navTaskLabel
The label to show on the results tab. (Set the tab title of
the tab that is opened after clicking a search result action.)
If not set, it will use the Action Name (the value shown in
the results). For example: "Manage user^View User"
(Note: This will be shown on the UI, so use resource
bundles.)
iconURL
Tooltip
Delimited
Required by caret "^" Description
contextCode
CommonDomain
BI
FIN
SCM
CRM
PRJ
HCM
PRC
IC
objectType
objectName
When a search is saved, some of this information (the structural part at the tip of the
click path) is saved, but prior actions and exact scroll positions are not. This means that
when running a saved search, the following items are not restored to the user:
When ECSF returns facet information, it returns facet entries only for the level below
that which is selected. For example, if there are no filters, the facets will be shown
correctly with one level of detail. If a first-level facet is selected, that selection will be
shown, but not its siblings. If there are facets below that level, this next level will be
shown as these are returned. As the user starts to refine or expand the attribute filters,
the search filters will be filled in based on this new click path.
15.6.6 How to Integrate Non-Applications Data into Oracle Fusion Applications Search
Oracle Fusion Applications Search can also be used with non-standard ECSF
searchable view objects.
Source
See the Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence
Enterprise Edition for how to create your Oracle Business Intelligence source.
Define a source based on the Oracle EBusiness Suite R12, and give the following
parameters:
SES Source Configuration:
Configuration URL:
http://10.156.30.40:9704/bisearch/crawler/oracle.biee.search.BISearchableTreeOb
ject/ConfigFeed?forceInitialCrawl=true
User ID: Administrator
Password: password
Authorization Tab:
HTTP endpoint for authorization:
http://10.156.30.40:9704/bisearch/crawler/SecurityService
User ID: Administrator
Password: password
Source Group
Create a source group (SES Searchtab then Source groups) and name it bi_<some
code name>.
It must start with bi_ so Oracle Fusion Applications Search can recognize it as an
Oracle Business Intelligence category.
You may go into Global Settings and translate the group name so the users see a
more recognizable name.
Import the group as an external category into ECSF. See "Importing Source Group
into ECSF".
Searching
When Searching, the Oracle Business Intelligence results will be displayed in a
separate tab, as shown in Figure 1540.
Figure 1540
If there are only Oracle Business Intelligence, or only Oracle Fusion Applications
or WebCenter Portal categories selected, only the one tab appropriate to those
categories is displayed. Otherwise, you can search both and tab between the
results.
When you click a link, you will be redirected to Oracle Business Intelligence. If
you do not have a consolidated Oracle Internet Directory (OID) setup, you will be
asked to log in again.
Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal and then
import the searchable objects into ECSF as external categories.
Importing Source Group into ECSF
The group now should be searchable from within the SES Search UI.
To allow the group to be searchable from Oracle Fusion Applications Search, it must be
imported using the cmdLineAdmin tool or Oracle Enterprise Manager Fusion
Middleware Control. Follow these steps if you use the tool:
1.
2.
3.
4.
5.
Implementing Auto-suggest
With Oracle Secure Enterprise Search (SES) Authentication pointing to the ECSF
SearchFeedServlet, which is using the WebLogic Server container security, this user
will be verified by the SES authentication callbacks.
In a true enterprise environment, both the Oracle Fusion Applications web container
and WebCenter Portal would be set up with the same OID.
Using two different authentication stores will mean you get multiple logins when
clicking results.
Search suggestions. These are keywords that the user wants to search on, and
when selected these words will be placed in the search field.
Shortcuts to other functionality. Selecting these entries will perform a specific
function for that entry; the text will not be placed in the search field as it is not a
keyword. For example, if the user types part of a Navigator entry, the Navigator
link will be suggested to them; clicking it will navigate to that menu entry, just the
same as if the user had selected the entry from the Navigator.
selection into the field only of keyword entries (not menu items)
Implementing Auto-suggest
It also adds to the communication to the server with new initialization, top suggestion
and selection messages.
The user interacts with the suggestion list as follows:
Auto-suggest starts with the third typed character. This can be configured.
The user starts to type into the field against which the search suggest is defined.
As soon as the user selects the search field, a message is sent to the server to start
to pre-load the lists of suggest items, so that by the time the user has typed the
second character (expect a second or so), any delay of startup is done. As many
groups as possible are loaded in a background thread to speed up the load of data.
A user can navigate in the popup by using arrow keys, Home and End to circle
among entries. As they do this, the currently-selected entry will be highlighted,
and if it is a keyword, it will be entered in the search field. If it is a Recent Item or a
Favorite, it will not be placed in the search field because it is not a search term.
Pressing Enter will perform the search by calling task flow with the
currently-selected item. This can be configured.
The match done is a case insensitive instring. The matched substring is
highlighted in bold.
A maximum of 25 items will be spread over the groups as evenly as possible. This
can be configured.
Any item that is to open a URL in a new window will show as a URL in the
popup. This is required to set target="_blank" so the URL opens in a new browser
window or tab, and not by overwriting the current Oracle Fusion Applications
window.
Groups are shown in the order defined in the JSPX tag.
.FndSearchSuggestItem
.FndSearchSuggestItem:selected
.FndSearchSuggestGroup
.FndSearchSuggestGroup:first-child
.FndSearchSuggestItemNormal
.FndSearchSuggestItemCount
.FndSearchSuggestItemCount:rtl
.FndSearchSuggestItemHilight
Implementing Auto-suggest
Table 1511
fnd:searchSuggestBehavior Attributes
Attribute
Name
EL
capable?
Required?
Default
Description
type
Yes
No
Popup
maxSuggested Yes,
Items
resolves to
an integer
No
25
minCharCount Yes,
resolves to
an integer
No
suggestGroup
<x> where x is
a number
between 1
and 8
Yes,
resolves to
a
SearchSugg
estGroup
Yes for
N/A
suggestGro
up1
No for
suggestGro
up2-8
ContextCode< Yes
x> where x is
a number
between 1
and 8
ObjectType<x Yes
> where x is a
number
between 1
and 8
typeDelay
Yes,
resolves to
an integer
No
null
CommonDomain
BI
FIN
SCM
CRM
PRJ
HCM
PRC
IC
No
null
No
500
Implementing Auto-suggest
EL
capable?
suggestionSo Yes,
urceId
resolves to
a string
Required?
Default
Description
No
null
submitOnEnte Yes,
rComponentId resolves to
a string
No
null
inlineSugges Yes,
tionComponen resolves to
tId
a string
No
Null
inlineReplac Yes,
eComponentId resolves to
a string
No
null
topSuggestio Yes,
ns
resolves to
a string
No
On
postSelectio Yes,
nFocusCompon resolves to
entId
a string
No
null
Implementing Auto-suggest
Implementing Auto-suggest
Implementing Auto-suggest
Implementing Auto-suggest
}
return ret;
}
@Override
public List<SearchSuggestItem> getTopSuggestions(String searchText,
int maxSuggestedItems)
{
long now = System.currentTimeMillis();
List<SearchSuggestItem> ret = new ArrayList<SearchSuggestItem>();
ret.add(new
ret.add(new
ret.add(new
ret.add(new
ret.add(new
ret.add(new
ret.add(new
ret.add(new
ret.add(new
SearchSuggestItem("sea"));
SearchSuggestItem("seahawk"));
SearchSuggestItem("Rafael"));
SearchSuggestItem("Sabatini"));
SearchSuggestItem("pirate"));
SearchSuggestItem("English"));
SearchSuggestItem("Spanish"));
SearchSuggestItem("privateer"));
SearchSuggestItem("Armada"));
Collections.sort(ret);
if (AppsLogger.isEnabled(AppsLogger.FINEST))
{
long later = System.currentTimeMillis();
long duration = later - now;
AppsLogger.write(this,
"Global Search: BookSearchSuggestGroup, getTopSuggestions:
Found: " + ret.size() + " items in " + duration +
" mSecs.",
AppsLogger.FINEST);
}
return ret;
}
@Override
public String getName()
{
return NAME;
}
@Override
public void init(Map<String, Object> attributes)
{
long now = System.currentTimeMillis();
Map<String, WordData> words =
loadResource("/oracle/apps/view/backing/theseahawk.txt");
List<SearchSuggestItem> keywords = new
ArrayList<SearchSuggestItem>(words.size());
Iterator<WordData> wordsIter = words.values().iterator();
while (wordsIter.hasNext())
{
WordData word = wordsIter.next();
keywords.add(new SearchSuggestItem(word.word, word.count));
}
Collections.sort(keywords);
_keywords = keywords;
Implementing Auto-suggest
if (AppsLogger.isEnabled(AppsLogger.INFO))
{
long later = System.currentTimeMillis();
long duration = later - now;
System.out.println("Global Search: BookSearchSuggestGroup, init: loaded " +
_keywords.size() + " keywords in " + duration +
" mSecs.");
AppsLogger.write(this,
"Global Search: BookSearchSuggestGroup, init: loaded " + _
keywords.size() + " keywords in " + duration +
" mSecs.", AppsLogger.INFO);
}
}
Section
Live data
Search Terms
No
Yes
No
Navigator
Yes
Watchlist
No
Yes
No
Yes
No
My Search Terms
Alternate search words that will be placed in the search field if the user clicks them.
The user then can perform a search by pressing Enter or clicking the Search icon.
The keywords are those from previous unfiltered searches by the user, using the result
count of that search. These values are stores in a new table:
CREATE TABLE FND_FUSION_SEARCH_KEYWORDS
(
FUSION_SEARCH_KEYWORDS_ID NUMBER(18,0) NOT NULL,
USER_ID VARCHAR2(64 CHAR) NOT NULL,
KEYWORDS VARCHAR2(260 CHAR) NOT NULL,
SEARCH_COUNT NUMBER(18,0) NOT NULL,
RESULT_COUNT NUMBER(18,0),
ENTERPRISE_ID NUMBER(18,0) DEFAULT NVL(SYS_CONTEXT('FND_VPD_CTX', 'ENTERPRISE_
ID'), 1) NOT NULL,
CREATION_DATE TIMESTAMP (6) NOT NULL,
CREATED_BY VARCHAR2(64 CHAR) NOT NULL,
Implementing Auto-suggest
My Recent Items
Recent Items from the recent items menu that match the search String.
When the user clicks a recent item, the task flow opens up directly.
The value shown to the user is the objectName, if present, otherwise it is the taskflow
label (what is shown in the Recent Items UI). Striping is possible using contextCode
and objectType if present. Note that Global Search does not use the striping values.
My Favorite Items
This is similar to recent items, however the favorite items need to be loaded from
tables when first used and are thereafter cached in memory.
My Navigator
The Navigator items are loaded by using the same APIs the navigator menu uses, and
will reuse any loaded or cached menu structure.
The value shown is the itemNode label. Striping is possible using contextCode and
objectType if present. Note that Global Search does not use the striping values.
Support entries that are navigation targets (the
FunUIShellController.navigate(...)), as well as pure URLs (<a href = ...) that
open in a new frame. URLs will be shown in the popup as URLs; that is, with the
underline.
My Watchlist
Watchlist items are loaded when first referenced.
Clicking an item expands into the watchlist item.
Saved Searches
Saved searches are referenced directly from Global Search.
Clicking an item runs the search.
Recent Searches
Recent searches are referenced directly from Global Search.
Clicking an item runs the search.
16
Implementing Additional Functions in the UI
Shell
16
This chapter discusses additional functions, such as the Navigate API and how to
implement the Home Page UI, that are included in the UI Shell page template used to
build web pages.
This chapter includes the following sections:
Section 16.6, "Developing an Activity Guide Client Application with the UI Shell"
Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
Chapter 18, "Implementing Applications Panels, Master-Detail, Hover, and Dialog
Details"
Note:
Expand the Data Controls and select the navigate item, as shown in Figure 161.
2.
Drag navigate and drop it onto the page fragment. When you do, the
Applications Context menu shown in Figure 162 is displayed so you can choose
one of the options.
Figure 162 Selecting a Navigate Option from the Applications Context Menu
You can specify a task flow to load on the target page. Page level parameters also can
be specified.
Table 161
Attribute Name
viewId
navigateViewId
Attribute Name
webApp
requestContextPath
pageParametersList
navigateParamsList
navTaskFlowId
navTaskKeyList
openMainTask
discloseRegionalTask
collapseRegionalTask
navigate
openSubTask
navTaskLabel
Certain parameters, summarized in Table 162, can be passed using the Navigate API's
argument list.
Table 162
Parameter Name
Passed Using
Description
forcePageRefresh
pageParametersList
Default: false
The Navigate API is used to navigate from one
work space to another. If the current view Id is the
same as the viewId parameter, and if navTaskFlow
is null, the current page will be refreshed. If the
current view Id is the same as the viewId
parameter, and if navTaskFlowId is not null, the
current page will not be refreshed, and the
Navigate API will delegate to the openMainTask
API to open the task flow in the main area. This
can be overridden by passing in
forcePageRefresh=true in pageParametersList to
force the page refresh so that openMainTask would
not be used.
Example:
pageParametersList =
"forcePageRefresh=true;param2=value2";
Details:
pageParametersList is a semicolon delimited
string of name-value pairs.
ContextualAreaCollapsed
methodParameters
Default: false
Example:
FndMethodParameters methodParameters = new
FndMethodParameters();
methodParameters.setContextualAreaCollapsed(
Boolean.TRUE);
methodParameters.setContextualAreaWidth(200)
;
contextualAreaWidth
methodParameters
Default: 256
Example:
FndMethodParameters methodParameters = new
FndMethodParameters();
methodParameters.setContextualAreaCollapsed(
Boolean.TRUE);
methodParameters.setContextualAreaWidth(200)
;
loadDependentFlow
navTaskParametersList
Default: false
Example:
navTaskParametersList =
"loadDependentFlow=true;param2=value2";
Note that the value for loadDependentFlow is case
sensitive.
Details:
navTaskParametersList is a parameter list to pass
in to the task flow to open in the target workspace.
This is a semicolon delimited string of name-value
pairs.
Passed Using
Description
contextCode
methodParameters
objectType
methodParameters
objectName
methodParameters
Note: When passing parameters, do not leave the label field null.
This is the label that would appear in the tab header when in a tabs
page. Even if you are in a no-tabs page (see Section 14.2.3.4,
"Supporting No-Tab Work Areas"), do not leave it blank because this
label will be used in other ways, such as Add to Favorites, or when
the system tracks the Recent Items.
The signature and Javadoc of the method are shown in Example 161.
Example 161
/**
* Navigate from one work space to another. If the current view id is the
* same as the viewId parameter, and if navTaskFlow is null, the current page
* will be refreshed. If the current view id is the same as the viewId
* parameter and if navTaskFlowId is not null, the current page will not
* be refreshed. The Navigate API will delegate to openMainTask API to open the
* task flow in the main area. This can be overriden by passing in
* forcePageRefresh=true in pageParametersList to force the page refresh so
* that openMainTask would not be used.
*
* @param viewId viewId of the target workspace
* @param webApp Deployed Module Name of the target workspace.
*
It only must be set when the target workspace is in a different
*
deployed module than the origin workspace. When this is null, it means
*
the target workspace is in the same deployed module of the origin
*
workspace. The webApp attribute is used to look up the host and port of
*
the associated Workarea or Dashboard from the ASK deployment
*
tables. These tables are populated at deployment time through
*
Oracle Fusion Functional Setup Manager tasks.
* @param pageParametersList Parameters list for the page. This is a semicolon
*
delimited String of name value pairs. For example,
*
"param1=value1;param2=value2"
*
If the Expression Language expression evaluates to an Object,
*
toString value of that Object will be passed as the value of
*
the parameter.
*
When forcePageRefresh=true is added to the pageParametersList,
*
the current page will be refreshed even if navTaskFlowId
*
is not null and current view id is the same as viewId
*
parameter value.
* @param navTaskFlowId Id of the taskFlow to open in the target workspace
* @param navTaskKeyList Key list to pass in to the task flow to open in the
*
target workspace. This is a semicolon delimited
*
keys or key-value pairs. For example,
*
"key1;key2=value2"
* @param navTaskParametersList Parameters list to pass in to the task flow to open
*
in the target workspace. This is a semicolon delimited String
*
of name value pairs. For example,
*
"param1=value1;param2=value2."
*
When loadDependentFlow=true is added to the
*
navTaskParametersList, the task flow specified in
*
navTaskFlowId will be loaded as dependent flow.
* @param navTaskLabel Label for the task flow to open in the target workspace.
* @param methodParameters Construct FndMethodParameters object for setting the
*
width of the contextual area, and/or setting the disclosed
*
state of the contextual area.
* @throws IOException
*/
public FndMethodParameters navigate(java.lang.String viewId,
java.lang.String webApp,
java.lang.String pageParametersList,
java.lang.String navTaskFlowId,
java.lang.String navTaskKeyList,
java.lang.String navTaskParametersList,
java.lang.String navTaskLabel,
FndMethodParameters methodParameters)
throws java.io.IOException
viewId determines the view activity within the target web application.
methodParameters.setContextualAreaWidth(200);
Notes:
The task flow to be opened in the target Work Area does not need
to be pre-registered as a defaultMain or dynamicMain task for that
page. The TaskFlow Id, parameters for it, and the label are all
explicitly passed to the target page, and the target page does not
perform any validation.
The webApp value that is passed into the Navigate API is used to
look up the host and port of the associated WorkArea or
Dashboard from the Oracle Fusion Applications Functional Core
(ASK) deployment tables. These tables are populated at
deployment time through Functional Setup Manager tasks.
Because the Navigate API is based on URL redirect, only string
representations of the parameter values can be passed to the target
page. It is not possible to pass an object as a parameter value. For
example, a Java map that is set as a customObject on
FndMethodParameters cannot be passed as a parameter (this is
only supported in openMainTask API).
When navigating to the current page with the
forcePageRefresh=true option using this API, the ADF
Controller state of the source page is not cleaned up.
TaskList links in regional area relaunch a task flow in the main area (with
reuseInstance=true and either forceRefresh=true or with different parameters).
All the main taskflows that render in MainArea should have the
data-control-scope set to isolated.
<data-control-scope id="dc">
<isolated/>
</data-control-scope>
Example 163
<af:commandButton actionListener="#{bindings.closeMainTask.execute}"
text="closeMainTask- with - CL"
disabled="false"
id="cb1">
<af:clientListener method="queueActionEventOnMainArea" type="action"/>
</af:commandButton>
In addition to adding the clientListener, when Data Control APIs are executed
from within the MainArea, developers must add the methodAction shown in
Example 165 to their main page fragment's pageDef whose taskflow is attached
to the tab in MainArea.
Example 165
<methodAction id="checkDataDirty"
InstanceName="FndUIShellController.dataProvider"
DataControl="FndUIShellController" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="checkDataDirty"
IsViewObjectMethod="false"
ReturnName="FndUIShellController.methodResults.checkDataDirty_
FndUIShellController_dataProvider_checkDataDirty_result"/>
The Data Control API shown in Example 165 lets you check for data dirty from
within the child region and identify any pending changes in the child region.
After adding above API to the main page fragment's pageDef, developers should
let the UI Shell know about that by sending the parameter
"fndCheckDataDirty=true" in the parametersList or navTaskParametersList.
Terms
Home page: any one of these JSPX pages.
Oracle Fusion Home: the overall Oracle Fusion Home Page UI.
2.
From the JSPX page, select the <af:pageTemplate> tag. On the property inspector,
set the isHomePage attribute to true. Note that when isHomePage is set to true, the
Regional, Local and Contextual Areas of the UI Shell will not be rendered.
3.
Add content to the HomePageContent facet, following the ADF Layout Basics
guideline for laying out the components.
4.
5.
6.
Create the Home Page menu. See Section 14.5, "Working with the Global Menu
Model."
7.
When running a home page JSPX, the page should look similar to Figure 163.
See Section 14.1.2.1, "Global Area Standard Icons" for a description of the icons.
getURL: getURL is the same as a navigate call, but it returns the URL as a string
instead of doing the navigation. See Example 167.
Example 167
viewId,
Example 168
This area is useful for creating Single Object Workareas, which are particularly useful
in tabbed page mode. A Single Object Workarea is a page that is devoted to one object
so the information of that one object can be put above the Workarea.
Single Object Workareas provide a context for addressing the tasks and processes for
the business process of a single complex object instance at a time. Usually, single object
workareas will use multiple defaultMain flows. Each flow can be about a different
aspect of the same object. For instance, you could have one tab showing recent activity,
and another tab showing payments.
<managed-bean>
<managed-bean-name>fndPageParams</managed-bean-name>
<managed-bean-class>java.util.HashMap</managed-bean-class>
<managed-bean-scope>view</managed-bean-scope>
</managed-bean>
Support for URL parameters defined in the view activity for the page (JSPX) in
adfc-config is to be set in the fndPageParams Hashmap defined in viewScope. This
Hashmap is also passed onto the pageFlowScope of the task flows in the context area,
regional area and main area.
This is accomplished by enabling the Bookmarkable property on the view activity for
the page and specifying the URL parameter names with the value set to be added to
the fndPageParams Hashmap defined in viewScope. See the "How to Create a
Bookmarkable View Activity" section in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
Product team task flows running in the Single Object Context Workarea must be
designed to take in the appropriate context values as input parameters. The
pageFlowScope values must be passed to the appropriate input parameters through
the parametersList for the item node in the menu or the openMainTask API.
Product teams can cause URL navigation (using the navigate data control method
provided by UI Shell by passing required parameters in the pageParametersList) for
changing context or updating context information. This will cause the entire page to be
refreshed based on new context parameter values.
Product teams can also check for the input parameter values (the context) within the
context area task flow. If invalid, a modal dialog can be launched for the end user to
choose a context (rendered as links based on the navigate data control method
provided by UI Shell) before proceeding.
Product teams must create a bounded task flow for the Context Area that appears at
the top of the page. This task flow must accept the context values as input parameters.
This task flow is dropped as a static region onto the Context Area facet in the JSPX
page based on the UI Shell template. In the task flow binding, set the input parameter
values to the corresponding key in fndPageParms viewScope Hashmap.
Example 1611 shows a sample entry in the page definition for the JSPX file for
passing the viewScope values into the Context Area task flow as input parameter.
Example 1611 Sample Page Definition for Passing viewScope Values into Context Area
Task Flow
<taskFlow id="ContextDeptSummary1"
taskFlowId="/WEB-INF/oracle/apps/empdeptdemo/ui/flow/ContextDeptSummary.xml#Contex
tDeptSummary"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="Deptno" value="#{viewScope.fndPageParams['Deptno']}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
</parameters>
</taskFlow>
The UI Shell code passes this viewScope hashmap onto the pageFlowScope of the main
area and regional area task flows. Product team task flows, which are initialized in the
regional area and main area, can access this in pageFlowScope (of a main area or
regional area container task flow owned by Applications Core) for the appropriate
input parameters through the menu model and openMainTask API.
Implementing Additional Functions in the UI Shell 16-13
Example 1612 shows a sample entry for a child item node for defaultMain task in the
menu.xml file to pass the appropriate deptno in the single object context to a task flow
that is initialized based on this input value.
Example 1612 Sample Child Item Node for defaultMain Task
<itemNode id="SingleDeptContextPage_EmpListingDefaultTab"
focusViewId="/SingleDeptContextPage"
label="#{adfBundle['oracle.apps.empdeptdemo.ui.test_
menuBundle'].EMPLOYEE_LISTING}"
taskType="defaultMain" reuseInstance="false"
taskFlowId="/WEB-INF/oracle/apps/empdeptdemo/ui/flow/ContainerTF.xml#ContainerTF"
parametersList="Deptno=#{pageFlowScope.fndPageParams['Deptno']}"/>
Product teams can cause URL navigation (through the navigate data control method
provided by UI Shell) for changing context or after updating context information. This
will cause the entire page to be refreshed based on new context parameter values.
Product teams can also check for the input parameter values within the
pageFlowScope of the context area task flow. If invalid, a modal dialog can be
launched for the end user to choose a context (by providing links based on the
navigate data control method provided by the UI Shell by passing required parameters
in the pageParametersList) before proceeding. This can be achieved by defining an
invoke action executable in the page def for the context area page fragment which
checks for existence of the pageFlowScope value and programmatically shows a modal
dialog for the user to choose the context. The other alternative is to use this approach
to cause navigation to a completely different page where the user can select the
context.
Also, it is important to note that all the bounded task flows that will be initialized in
the Single Object Context Workarea need to check for input parameter values and
show/query data only if the input parameter values are passed. Basically, if the input
parameter values are empty, the task flows handle that, such as in a router activity, and
avoid showing any transaction data to the end user.
A facet reference is under the global area content with its width set to 100 percent.
You should create a bounded task flow with page fragment for the content and
drop it into this facet as a static region. This supports personalization through web
composer since the content is within a page template.
The height property of the panelStretchLayout in the UI Shell template defaults
to 33 px. To view or enable the third party component area (see the dark blue area
at the top of Figure 141), specify the globalAreaHeight property as auto in the
pageTemplate property Inspector.
When the height of the top facet is specified as a CSS length or as auto, this facet
will no longer be stretched and instead will consume the initial offsetHeight
given to its children by the browser. It is important to note that in an average page,
a switch to a layout using automatic heights exhibited a 5- to 10-percent
degradation in initial layout speed. Also, an automatic height will cause the facet
child to not be stretched both vertically and horizontally.
You can set the height of the root layout component within the facet to auto to
ensure auto-resizing of contents within the facet. Consider a showDetailHeader
that is the root element within the facet (in the default view activity for the
bounded task flow dropped in as a region). If the height property for this
showDetailHeader component is set to auto, collapsing the header would resize
the contents and open more real estate in the screen for showing other components
in the page.
In the new application, create a new project using the Web Project template by
right-clicking the application and selecting New Project > Project > Web Project.
Select Servlet 2.5/JSP 2.1 (Java EE 1.5). Click through the wizard, accepting all
default values.
3.
Add the ADF Faces and ADF Page Flow technologies to the client application
project. Right-click the project and select Project Properties > Technology Scope.
Shuttle ADF Faces and ADF Page Flow from the Available Technologies list to the
Selected Technologies list.
Make sure the following technologies are also selected: HTML, Java, JSP and JSF
and Servlets.
Figure 167 Adding the ADF Faces and ADF Page Flow Technologies to the Client
Application
4.
Right-click the client application and select Project Properties > JSP Tag Libraries.
Select the Distributed Libraries folder and click Add. In the Choose Tag Libraries
window, select the tag library Applications Core (ViewController) 11.1.1.0.0 and
click OK.
Figure 168 Select the Tag Library Applications Core (ViewController) 11.1.1.00
5.
In the Project Properties window, select Libraries and Classpath and click the Add
Library button. From the window that is displayed, select the Applications Core
library and click OK.
6.
In the Project Properties window, click the Add JAR/Directory button and browse
for the file oracle.bpm.activityguide-ui_11.1.1.jar. The file is located under
jdev_install/jdeveloper/soa/modules/oracle.bpm.activityguide-ui_
11.1.1.jar.
Click Select to add the JAR to the project classpath.
7.
Add Activity Guide runtime libraries or JAR files to the classpath. Use either
shared libraries or JAR files; do not use both.
a.
b.
8.
Create a file called Config.jar using the wf_client_config.xml file and add it to
the application classpath. The wf_client_config.xml file should include the host
name and port of the WLS instance running the Activity Guide instances.
9.
Create a JSF page. Right-click the application name and click New. In the New
Gallery, select JSF > JSF Page and click OK. Use UIShell as a page template and
select the checkbox Create as XML Document (*.jspx).
If a dialog box displays the message "Confirm Add Form Element," click No.
10. Create Application menu metadata. See Section 14.3, "Implementing Application
Menu Security.".
To add a task flow to the Oracle UI Shell client application:
1. Open the menu metadata menu XML file created in "To develop an activity guide
client application using Oracle UI Shell:".
2.
3.
In the Common Properties window, browse for the name of the JSF page and enter
a unique Id for the itemNode property using the standard format <pageID>_
<taskFlowName>. For example: ItemNode_MainArea_TaskFlow.
4.
Click the Browse button to the right of the focusViewId field. In the Edit Property
window that is displayed, select the focusViewId of the page under which you are
registering the task flow. Click OK.
5.
In the Property Inspector, select the Applications tab and enter a label for the
itemNode such as Main Taskflow.
6.
From the Project Navigator, select the menu metadata XML file. In the Structure
view, select the task flow itemNode Main Taskflow. In the Property Inspector,
enter the following values under the Advanced section:
7.
Task Flow ID: Click the Browse button to display the Select Task Flow ID
window and select the location of the task flow definition:
/WEB-INF/oracle/bpel/activityguide/ui/taskflows/ag-humantask-task-f
low.xml#ag-humantask-task-flow. This is the Id of the main area task flow.
Disclosed: Optionally, set this value to false. This property enables opening a
new tab when clicking the relevant task link at run time. For tabs, the first
defaultMain with disclosed=true is the one that will be in focus.
Repeat Steps 1 through 6 for the regional task flow, naming the label and Id
accordingly. Provide the following values for the regional task flow in step 6:
8.
Example 1614.
Example 1614 Workflow Services Client Configuration File
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workflowServicesClientConfiguration
xmlns="http://xmlns.oracle.com/bpel/services/client">
<server default="true" name="default">
<localClient>
<participateInClientTransaction>false</participateInClientTransaction>
</localClient>
<remoteClient>
t3://host:port
<initialContextFactory>weblogic.jndi.WLInitialContextFactory</initialContextFactor
y>
<participateInClientTransaction>false</participateInClientTransaction>
</remoteClient>
<soapClient>
http://host:port
"To deploy an Activity Guide client application with Oracle UI Shell to the
integrated Oracle WebLogic Server:" or in "To deploy an Activity Guide client
application with Oracle UI Shell to a standalone Oracle WebLogic Server:".
To secure the Activity Guide Oracle UI Shell client application:
Securing the Activity Guide client application ensures that only users with proper
credentials can complete the tasks outlined in the Activity Guide. Security features
include authentication, authorization, realm verification and policy enforcement.
Follow the instructions for securing a Web application as described in the "Enabling
ADF Security in an Oracle Fusion Web Application" chapter of the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
To deploy an Activity Guide client application with Oracle UI Shell to the
integrated Oracle WebLogic Server:
You can deploy an Activity Guide client application with Oracle UI Shell directly from
JDeveloper or to the standalone Oracle WebLogic Server.
From the Application Navigator, right-click the JSF page created in "To develop an
activity guide client application using Oracle UI Shell:" and select Run.
To deploy an Activity Guide client application with Oracle UI Shell to a
standalone Oracle WebLogic Server:
1. Create a connection to the standalone Oracle WebLogic Server.
2.
From the Application Navigator, right-click the project created in step 2 of "To
develop an activity guide client application using Oracle UI Shell:"
3.
4.
5.
Right-click the project and select Deploy. Deploy the project to the standalone
Oracle WebLogic Server connection created in step 1.
6.
The items that are not available on a tablet device take up too much space to be used
comfortably on a small screen.
The page template will also collapse the left-side Regional area by default to save
space.
Also see "Creating Web Applications for Touch Devices Using ADF Faces" in the Oracle
Fusion Middleware Web User Interface Developer's Guide for Oracle Application
Development Framework.
How to use flow mode on a touch screen device
Implementing flow mode follows the "Best Practices When Using ADF Faces
Components in a Mobile Browser" section of "Creating Web Applications for Touch
Devices Using ADF Faces" in the Oracle Fusion Middleware Web User Interface
Developer's Guide for Oracle Application Development Framework.
To use flow mode on a touch screen device, but making sure that nothing is changed
when displaying pages on a desktop system, add this context-param to the web.xml
file of the J2EE application:
<context-param>
<description>
This parameter controls the default value for component geometry on the
page.
Supported values are:
legacy - component attributes use the default values as specified for
the attributes
auto - component attributes use the correct default value given the
value of their parent component. For example, with this setting, the
panelStretchLayout will use "auto" as the default value for its
"dimensionsFrom" attribute instead of "parent".
</description>
<param-name>oracle.adf.view.rich.geometry.DEFAULT_DIMENSIONS</param-name>
<param-value>#{requestContext.agent.capabilities['touchScreen'] eq 'none' ?
'legacy' : 'auto'}</param-value>
</context-param>
In this case, the dimensionsFrom attribute is set to auto only when running on a touch
screen device. But when running on a desktop system, the context-value is set to
legacy and the dimensionsFrom attribute will use the old default value, which is
parent.
The UI Shell sets the dimensionsFrom attribute to children on the root panel
component on a page when running on a tablet device. Setting the dimensionsFrom
attribute to auto, and placing the context-param in the web.xml file, will allow all
other components to use the dimensionsFrom attribute.
Solution
To resolve this problem:
Check that the JpsFilter section is correct in web.xml: Applcore Session code
depends on the JPS subject. The entry must appear exactly as shown in
Example 1615.
Check that the ApplSessionFilter section is correct in web.xml: ApplSession must
be configured immediately after JpsFilter. The entry must appear exactly as shown
in Example 1615.
If the issue is with the ApplSession not being created over a web service request
using SOA, check how the ApplSession context interceptor is configured.
ApplSession information is preserved over SOA/Web Service requests with
context interceptors that fire when requests are sent and received. The
ApplSessionContext interceptor, in particular, will handle propagating all session
attributes from the caller to the web service, and will even attempt to reuse the
same session Id if running against the same database. To enable the context
interceptor, the weblogic-application.xml on both the caller and the called should
include the oracle.applcore.config shared library:
<library-ref>
<library-name>
oracle.applcore.config
</library-name>
</library-ref>
If the context interceptor has not been enabled, the prepareSession() of the root
application module call should still be able to create the session as the right user,
so long as the Subject has been established correctly in the Oracle Web Services
Manager layer. But in that case, no other session attributes will be propagated, and
the session cannot be reused.
Implementing Additional Functions in the UI Shell 16-23
Obtain the session Id from the cookie. The cookie is located in the browser's
cookies folder.
The session cookie is obtained so that subsequent queries can be run to verify the
session's existence and obtain additional info about the session. Note that it is the
session cookie that is stored in the browser cookie location, not the session Id.
They represent the same session, but the actual session Id is internal.
Cookie name: ORA_FND_SESSION_<db_instance_name>
The session cookie value will appear similar to: DEFAULT_
PILLAR:wvlu8CUiH4FYjySCPQtwaEphBOyiUTZwexYd1fYXh5VwV9i9koUL8L3Qhm0bNrZ8
:1282160020177
To retrieve the actual session id, run this SQL statement: select session_id from
fnd_sessions where session_cookie=value_obtained_from_cookie_value.
Note: The value_obtained_from_cookie_value is the alpha-numeric string
between the two colons. In the example, it is
wvlu8CUiH4FYjySCPQtwaEphBOyiUTZwexYd1fYXh5VwV9i9koUL8L3Qhm0bNrZ8. This
value will always be different.
Make sure that you are signed in as a user that has access to some pages in the
Navigator menu. You can type the full URL of the page directly into the browser
and see if the user can access it.
Make sure there is a valid connection to the LDAP server. This is needed to check
the policies of each entry in the Navigator menu.
Use Enterprise Manager to make sure the Applications are registered in the
topology tables.
Make sure the Applications Core Setup application is deployed. (From JDeveloper,
run .../atgpf/applcore/applications/FndSetup/FndSetup.jws.) This contains the
Navigator menu file and usually is deployed to the Oracle Fusion Applications
Global domain.
Check that the menus are in MDS. Check for entries with the path
oracle/apps/menu.
You usually should run without menu security. The first thing to check is if you
have started your web server with this parameter to turn off security checking:
-DAPPLCORE_TEST_SECURED_MENU=N
17
Implementing UIs in JDeveloper with
Application Tables, Trees and Tree Tables
17
This chapter discusses the Applications Tables, Trees and Tree Tables components used
to implement user interface features in JDeveloper.
This chapter includes the following sections:
Edit actions, such as Table Row Edit (Dialog Window) and Table Row Edit (Page)
You must use Applications tables to standardize layout and appearance consistency
for all your page tables, including read-only pages. When you create an Applications
table, you can add table components that allow users to select the table's contents.
Before you begin:
Before you can use Applications tables, you must be familiar with JDeveloper and be
able to create JSF pages.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables
17-1
Note:
Facet Name
Description
Values
table
ADF Table
Description
Values
popup
Table 172 describes Applications table properties (including properties that are part
of the default managed bean), their allowable values, and default actions.
Table 172
Property
Description
Values
id
string
rendered
boolean expression
tableId
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables
17-3
Description
Values
<default>, inline, secondaryWindow, page
<default>: No rows are created. You might choose
this value if your table is read-only.
inline: New row is created at the top of the current
table. If you choose this value, the
createpartialTriggers property on the ADF table is
set automatically.
secondaryWindow: Popup is displayed, allowing
users to enter values into a new table row. The new
row is added to the top of the table. If you choose
this value, you must also set the corresponding
Create Popup Id.
In addition, you must create the popup UI that
shows input fields.
page: An ADFc Controller outcome is returned such
that navigation to the next view activity occurs.
editPatternType
deleteEnabled
boolean
Description
Values
method expression
method expression
string
cditPopupId
string
duplicatePopupId
string
createText
editText
duplicateText
deleteText
attachText
featuresOff
string
inlineStyle
string
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables
17-5
Description
Values
styleClass
string
exportEnabled
createImmediate
boolean / expression
deleteImmediate
boolean / expression
boolean / expression
editImmediate
boolean / expression
attachImmediate
boolean / expression
boolean / expression
boolean / expression
Description
<button_
Partial triggers attribute for the
name>PartialTrigg <button_name> toolbar button.
ers
The partial triggers property of the
Create, Edit, Duplicate and Delete
For example:
deletePartialTrig buttons, and menu items are
exposed. Users can enable and
gers
disable buttons according to rows
selected or other actions carried out
on the page. The same partialTrigger
attribute for each one is used both
for the commandToolbarButton and
the menu item. For example, when
the createPartialTriggers is set in the
Applications Table, the value for this
attribute is set on the partialTrigger
property of both the create command
toolbar button and create menu item.
Values
String of IDs.
Important: The PartialTriggers attribute must be
entered manually by the developer. This is because,
at design time, the JDeveloper Property Inspector
can:
Example 1:
To disable the Edit, Delete and Duplicate buttons
when the table is empty, set this property on the
editDiabled, deleteDisabled or duplicateDisabled
property of the Applications Table.
#{bindings.VOiterator.estimatedRowCount == 0
? true: false} where VOiterator is your
iterator name
Example 2:
Disable any of the buttons in the Applications Table
according to the functional rules or by setting
disable=false when create is selected on an empty
table (considering these buttons were disabled
following Example 1).
To do this, create an attribute binding on the view
object attribute that will decide whether the row can
be deleted/edited/duplicated. For example, you can
use a binding similar to this example on the disable
property of a button:
#{bindings.MyAtttrBinding.inputValue ==
'compare value' ? true : false}
Add Partial Page Refresh (PPR) on the button to the
table ID of the af:table. This does not require any
change in the selectionListener of the table. Keep the
default one.
createAction
method expression
editAction
method expression
duplicateAction
method expression
deleteAction
method expression
createEnabled
duplicateEnabled
editEnabled
createDisabled
editDisabled
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables
17-7
Description
Values
deleteDisabled
confirmDelete
deleteMsg
actionsMenuRender Rendered attribute for Actions menu Boolean value or Expression Language expression
ed
actionsContentDel ContentDelivery attribute for
String value
ivery
Actions menu. This attribute can take
two values.
lazy
immediate
Model
The Applications Table does not expose any bindings to the model. However,
components within the Applications Table, like the ADF table, will be bound to the
model.
Controller
The Applications Table component ships a default managed bean that performs the
following functions that only work with rowSelection="single" on the ADF table:
Default event handlers for all toolbar button action events. Event handler
delegates to custom action method if set on the button action property.
A new row is added into the table when the Create icon is clicked, and the
Create Pattern Type is inline.
A new row is added into the table and a popup is invoked with the
newly-created row available for inserting values (the UI for the popup to show
input fields for the new row has to be created separately by the developer),
when the Create Pattern Type is secondaryWindow.
A new row is not added when the Create Pattern Type is Page. The developer
is responsible for wiring the navigation to the page when the icon or menu
item is clicked. Only a standard outcome is returned from the default handler.
The developer could use this default outcome to define a navigation rule.
The selected row is made available for editing in a popup when the Edit icon
is clicked, and Edit Pattern Type is secondaryWindow.
When the Edit icon is clicked, and Edit Pattern Type is Page, only a standard
outcome is returned.
The Duplicate icon is handled the same way as Create. All attribute values
except the primary key values are duplicated.
If the secondaryWindow option is chosen for any pattern type, and the
corresponding popup Id is set for that button (mandatory), selecting the button
invokes the popup.
If Page is chosen for any pattern type, a standard outcome is returned on clicking
the button. Standard outcomes are create, edit, duplicate and delete for the four
respective toolbar buttons.
Example 171
import oracle.apps.fnd.applcore.patterns.ui.ApplicationsTableEventHandler;
import oracle.apps.fnd.applcore.patterns.ui.util.PatternUtils;
public class CustomEventHandler
{
public String processCreate()
{
// Custom code
...
// Call default event handler if required. It will return a standard outcome
for this button click.
ApplicationsTableEventHandler appTableHandler =
ApplicationsTableEventHandler.getInstance();
String outcome = appTableHandler.processCreate();
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables
17-9
3.
Bring up the Property Inspector for the Applications Table, and choose the Create
Action property. Set #{CustomEventHandler.processCreate} as the expression for
the property.
3.
In the list, click Table. JDeveloper will attempt to place the table at the current
cursor location. If the current location is not appropriate, an error message
displays. You also can drag the Table icon to the page in either the Design or the
Source view. A plus + sign will be added to the arrow when it is over a location in
which a table can be inserted.
The Applications Table wizard is displayed.
To start the Applications Table wizard using the Data First method:
1. In the Application Navigator, open the Data Control panel.
2.
Navigate to the data source that you want to bind to the Applications table. The
data source must represent a rowset; that is, it must be a view object.
3.
4.
In the Create context menu that is displayed, choose Applications > Table.
The Applications Table wizard is displayed.
The Applications Table wizard has two dialogs. Click Cancel in either dialog to cancel
your actions and exit the wizard. Click Next to accept the defaults.
To add an Applications Table using the Applications Table wizard:
When the Applications Table wizard is launched, the Create Applications Table dialog
is displayed, as shown in Figure 171.
Figure 171 Create Applications Table Dialog
1.
Select Read-only Table to prevent users from modifying the data. If you select
Read Only, the options in the Component To Use column will change from
Input to Output components.
b.
Select the Bind Data Now box to bind a data control to the table.
In the Table Data Collection section, click Browse to choose from a list of
data sources available for binding.
This step might take a few minutes.
The Select Table Data Collection dialog is displayed, as shown in
Figure 172.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-11
Select the data source to bind to your table and click OK.
When you bind the data, the table creates placeholder columns that can be
used for layout purposes.
c.
When you choose a data source to bind to your table, these options become
available.
Row Selection
Select None to disable row selection by users.
Select Single to allow users to be able to select individual rows in the table.
This will set the rowSelection attribute to single. Selecting this option means
that instead of the UI component determining the selected row, the iterator
binding will access the iterator to determine the selected row. This is
recommended when using ADF Model data binding.
Select Multiple to allow users to be able to select multiple table rows.
Sorting
Select to allow users to be able to sort columns. Selecting this option means
that the iterator binding will access the iterator which will perform an
order-by query to determine the order. This is recommended when using ADF
Model data binding. Only keep this checkbox unselected if you do not want to
allow column sorting.
Filtering
Select to allow users to be able to filter the table based on given criteria.
Selecting this option allows the user to enter criteria in text fields above each
column. That criteria is then used to build a query-by-example search on the
collection, so that the table will display only the results returned by the query.
d.
The Columns section is used to set the behavior of the table's columns.
Group
Select two or more columns then click this link to group the columns together
in the table. The selected columns will be grouped together under a parent
column.
Ungroup
Select columns that are grouped then click this link to ungroup the columns.
Display Label
By default, the label is bound to the labels property for the attribute on the
table binding. You can instead enter text or an Expression Language
expression to bind the label value to something else, for example, a key in a
resource file.
Value Binding
Shows the attribute to which the value is bound. Use the drop-down list to
choose a different attribute. If you simply want to rearrange the columns, you
should use the order buttons. If you do change the attribute binding for a
column, the label for the column also changes.
Component to Use
Shows the component used to display the value. Use the drop-down list to
choose a different component. By default, output text components are selected
for read only tables. Input text components are selected for all other tables.
Input date components are used for attributes that are dates. If you want to
use a different component, such as a command link or button, you need to use
this dialog to select the outputText component, and then in the Structure
window, replace the component with the desired UI component (such as a
command link). By default, only ADF Faces components are shown in the
menu. You can allow JSF Implementation components to also be chosen.
Add Column
Select a column name from the attributes list and click + to add the column
name to your table. Repeat this step for all your table column names.
Delete Column
Click X to delete a column name.
Sort Column Order
Click the up or down arrows to sort the order of the columns.
e.
Click Continue.
The Configure Table Patterns dialog is displayed, as shown in Figure 173.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-13
2.
In the Configure Table Patterns dialog, select default actions for your
Applications table (optional):
When you have chosen to enable row creation, choose a pattern from the
list to invoke an action.
If you choose the Popup pattern, click Configure Popup to display the
Applications Popup wizard (see Section 17.4, "Using the Custom Wizard
with Applications Popups") and follow the instructions to configure the
popup associated with this pattern. See Table 171, " Applications Table
Facets" for important information about the popup's Cancel button.
When you have chosen to enable row duplication, choose a pattern from
the list to invoke an action.
If you choose the Popup pattern, click Configure Popup to display the
Applications Popup wizard (see Section 17.4, "Using the Custom Wizard
with Applications Popups") and follow the instructions to configure the
popup associated with this pattern. See Table 171, " Applications Table
Facets" for important information about the popup's Cancel button.
When you have chosen to enable row editing, choose a pattern from the
list to invoke an action.
If you choose the Popup pattern, click Configure Popup to display the
Applications Popup wizard (see Section 17.4, "Using the Custom Wizard
with Applications Popups") and follow the instructions to configure the
popup associated with this pattern. See Table 171, " Applications Table
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-15
If you need to manually create or edit the Delete Confirmation parameter, see
Section 17.1.2.2.1, "Manually Enabling Delete Confirmation."
For more information on pattern types, see Table 172, " Applications Table
Properties".
3.
Click OK to save your choices and create the Applications table, or click Cancel to
delete your choices.
4.
If you click OK, the table and its components appear in the editor, as shown in
Figure 175.
17.1.2.2.1 Manually Enabling Delete Confirmation This section describes how to enable
Delete Confirmation, or add or edit the custom confirmation message, if you have an
existing table.
When you set the confirmDelete attribute to true, the confirmation popup displays
and the row is deleted when you click Ok. For this to work correctly, the
partialTriggers on the af:table inside the fnd:applicationsTable should include
::confirm, and the ::delete and ::deleteConfirm ids must be removed so the
partialRefresh happens only when you click Ok in the popup. Setting
deleteImmediate="true" when enabling delete confirmation sets the immediate
attribute of the Ok button in the confirmation popup to true. The Cancel button of the
delete confirmation popup has immediate set to true by default.
See Example 172 for sample code that shows both the delete confirmation enabled
and the custom message.
Example 172
With af:table selected in the Structure view, Figure 176 shows the PartialTriggers
entries in the Property Inspector view.
Figure 176 Delete Confirmation PartialTriggers in Property Inspector
17.1.2.2.2 Multiple Row Selection on Table If multiple row selection is enabled, editing
functions will behave as shown in Table 173.
Table 173
Function
Behavior
Delete
Selecting more than one row and selecting Delete deletes all the selected rows.
Create
Selecting more than one row and selecting Create will create a new row as the
first row.
Edit
Selecting more than one row and selecting Edit will show an alert window
asking you to select a single row to edit.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-17
Table 173 (Cont.) Function Behavior with Multiple Row Selection Enabled
Function
Behavior
Duplicate
Selecting more than one row and selecting Duplicate will show an alert
window asking you to select a single row to duplicate.
17.1.2.2.3 Toggle Click to Edit / Edit All in Applications Table The Applications Table toolbar
has an icon that can be clicked to toggle the Click to Edit and Edit All functions, and
the View Menu on the toolbar includes the same toggle feature. Figure 178 shows the
Edit All menu option and icon when the table is in the Click to Edit mode.
Figure 178 Table Edit All Menu Option and Icon
Figure 179 shows the Click to Edit menu option and icon when the table is in the Edit
All mode.
Figure 179 Table Click to Edit Menu Option and Icon
The toggle mode should only display if the table is editable. If it contains only output
components, there should be no toggle button. This is a true/false property (see
toggleEditRendered in Table 172) on the Applications Table and does not happen
automatically.
Many of these settings are easily changed using the Table Property Inspector, which
contains these sub-sections: Common, Patterns, Style, Customization, and Other. This
section discusses certain selected settings.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-19
Figure 1710
Primary Toolbar Rendered: Set this to False if no default actions or buttons will be
used. If this is set to True and there will be no actions or buttons, the separators
around buttons will display even if no button displays.
Secondary Toolbar Rendered: Set this to False if no default actions or buttons will
be used. If this is set to True and there will be no actions or buttons, the separators
around buttons will display even if no button displays.
Actions Menu Rendered: If no default actions were selected in the wizard, set this
to False to avoid doubled separator lines.
ActionsContentDelivery: Sets the Content Delivery attribute on the actions menu
of the table. The options are Immediate (the default) and Lazy. Immediate
populates the action menus as soon as the page is displayed. Lazy only populates
an action menu when it is selected. There will be a slight delay the first time the
menu is selected; there will be no delay the next time the menu is selected because
the menu items are cached. You should set the ActionsContentDelivery to Lazy
when you do not have any partialTriggers set on the items in the Actions menu
because setting the value to Immediate affects the performance.
Figure 1711
Disabled: Sets whether the button is disabled (shown as grayed). This does not
determine if the button is displayed; it only sets its appearance and functionality.
Enabled: Sets the rendered attribute on the Create/Duplicate/Edit/Delete button
icon and menu item. If you are using the default action, a string called create (or
duplicate/edit/delete) is returned.
Immediate: Sets whether data validation - client-side or server-side - should take
place when events are generated by the button. When immediate is set to true, the
default ActionListener provided by the JavaServer Faces implementation should
be executed during the Apply Request Values phase of the request processing
lifecycle, rather than waiting until the Invoke Application phase.
Partial Triggers: A partial trigger affects only the selected item, rather than the
entire page. For instance, Example 175 sets the partialTrigger attribute value on
the Create button icon and Create menu item
Example 175
<af:inputComboboxListOfValues id="ledgerIdId"
popupTitle="Search and Select: #{bindings.LedgerId.hints.label}"
value="#{bindings.LedgerId.inputValue}"
label="#{bindings.LedgerId.hints.label}"
model="#{bindings.LedgerId.listOfValuesModel}"
required="#{bindings.LedgerId.hints.mandatory}"
columns="#{bindings.LedgerId.hints.displayWidth}"
shortDesc="#{bindings.LedgerId.hints.tooltip}">
<f:validator binding="#{bindings.LedgerId.validator}"/>
<af:convertNumber groupingUsed="false"
pattern="#{bindings.LedgerId.format}"/>
</af:inputComboboxListOfValues>
<fnd:applicationsTable tableId="ATt1" id="AT1" deleteEnabled="true"
createPatternType="inline"
duplicatePatternType="inline"
editPatternType="inline"
createText="#{viewcontrollerBundle.NEW}"
createDisabled="#{bindings.LedgerId.inputValue == null}"
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-21
createPartialTriggers=":::ledgerIdId">
2.
Drag and drop either the entire data source or individual fields:
Figure 1713
For example, to add a field from a data source to a table, drag the field from
the data source to this path: fnd:applicationsTable > f:facet table > af:table
<tableId>. When you drop the field on the component, you are prompted to
choose which component to use for this attribute. Using the example in
Figure 1714, you would choose either the ADF Read-only Column, or the
ADF Column, depending on whether the fields need to be read-only or not.
Figure 1714
<f:facet name="additionalToolbarButtons">
<af:toolbar>
<af:commandToolbarButton text="Button1"/>
<af:commandToolbarButton text="Button2"/>
</af:toolbar>
</f:facet>
For tables and treeTables with selectable columns, the default top level
menu items are View and Format. To turn off the Format menu, the
af:table should not have selectable columns.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-23
When using an Applications Table as a resultant table that shows the results from a
search on a query component, follow these steps to set the resultComponentId
attribute on af:query:
1.
In the JSF page that contains the query component and the Applications Table,
select the query component.
2.
In the Property Inspector, select the resultComponentId property and then Edit.
3.
From the edit panel, select the af:table (the ADF table that is present in the
"table" facet of the Applications Table).
You can select the Applications Tree from the Applications component palette and
drag and drop it on your page.
You can drag and drop a data collection from the data control palette to your page
and select the Applications Tree from the list of available UI components.
The facets shown in Table 174 are exposed on the Applications Tree.
Table 174
Facet
Description
Allowed Children
tree
ADF Tree
additionalToolbarB
uttons
ADF Command
Toolbar Buttons
additionalActionIt
ems
appsTreeSecondaryT
oolbar
ADF Command
Toolbar Button
component
appsTreeStatusbar
ADF component
appsTreeViewMenu
appsTreeAfterToolb
ar
"af:toolbar" or
"af:groups" of
"af:toolbars"
popup
Any number of
popups under a
layout component
The properties shown in Table 175 are exposed on the Applications Tree.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-25
Table 175
Property
Description
Allowed Values
id
string
rendered
boolean / expression
treeId
string
createPatternType
editPatternType
duplicatePatternTy
pe
createEnabled
string
editEnabled
duplicateEnabled
deleteEnabled
createAction
method expression
editAction
method expression
duplicateAction
method expression
deleteAction
method expression
createActionListen
er
method expression
editActionListener
duplicateActionLis
tener
deleteActionListen
er
method expression
If defined, this property can be
used to supplement the default
action specified by the Pattern
Type property or completely
override it.
method expression
If defined, this property can be
used to supplement or override
the default action.
Description
Allowed Values
createPopupId
string
editPopupId
string
duplicatePopupId
createText
Overrides default label for Create menu item. This value expression
will also be shown as the short description for the
Create button.
editText
expression
duplicateText
expression
deleteText
Overrides default label for Delete menu item. This value expression
will also be shown as the short description for the
Delete button.
exportEnabled
boolean / expression
featuresOff
string
inlineStyle
styleClass
string
createImmediate
boolean / expression
deleteImmediate
boolean / expression
duplicateImmediate
boolean / expression
editImmediate
boolean / expression
actionsMenuRendere
d
boolean / expression
primaryToolbarRend
ered
boolean / expression
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-27
Description
Allowed Values
secondaryToolbarRe
ndered
boolean / expression
Sets rendered attribute value of the secondary toolbar.
When no af:commandToolbarButton is added to
appsTableSecondaryToolbar facet, then
secondaryToolbarRendered should be set to false so that
an empty toolbar would not be displayed.
createDisabled
editDisabled
duplicateDisabled
deleteDisabled
confirmDelete
Model
The Applications Tree does not expose any bindings to the model. However,
components within the Applications Tree, like the ADF tree, will be bound to the
model.
Controller
The Applications Tree component ships a default managed bean that performs the
following functions:
Default event handlers for all toolbar button/menu item action events. Event
handler delegates to custom action method if set on the button/menu item action
property.
A new row is created in the data collection, a popup invoked with the newly
created row available for inserting values (the UI for the popup to show input
fields for the new row has to be created separately by the developer), when
Create Pattern Type is secondaryWindow. After the popup is dismissed, the
tree is refreshed to display the newly-created node:
*
A new row is not added when the Create Pattern Type is page, and the
developer is responsible for wiring the navigation to the page when the icon
or menu item is clicked. Only a standard outcome is returned from the default
handler. The developer could use this default outcome to define a navigation
rule.
The selected row is made available for editing in a popup when the Edit icon
is clicked, and Edit Pattern Type is secondaryWindow.
When the Edit icon is clicked, and Edit Pattern Type is page, only a standard
outcome is returned.
When the Duplicate icon or menu item is clicked: A new node is added into
the tree when the Create icon is clicked, and Create Pattern Type is inline. All
non-primary key values of the selected node are copied to the new node.
If Duplicate Pattern Type is inline, the newly created node is placed next to the
selected node.
If Duplicate Pattern Type is popup, a popup invoked with the newly created
row is available for modifying the duplicated values (the UI for the popup to
show input fields for the new row has to be created separately by the
developer).
Clicking the Delete icon deletes the selected node. It currently does not
perform a cascade delete when a parent node is selected for delete.
Applications developers need to handle deleting the child nodes if it is
necessary.
If the secondaryWindow option is chosen for any pattern type, and the
corresponding popup id is set for that button (mandatory), then selecting the
button invokes the popup.
If page is chosen for any pattern type, then a standard outcome is returned on
clicking the button. Standard outcomes are: create, edit, duplicate and delete for
the four respective toolbar buttons.
A default selection listener for the ADF tree is provided (the markup shows
selectionListener="#{ApplicationsTreeBean.treeSelectionHandler}"). If you
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-29
need to add custom logic to the selection listener, you should call this default
selection listener from the custom logic. The treeSelectionHandler method of the
ApplicationsTreeBean provides the following behavior:
Example 178 shows sample code for calling the default selection listener from the
custom selection listener.
Example 178
Calling the Default Selection Listener from the Custom Selection Listener
Example 179
import oracle.apps.fnd.applcore.patterns.ui.ApplicationsTreeEventHandler;
import oracle.apps.fnd.applcore.patterns.ui.util.PatternUtils;
public class CustomEventHandler
{
public String processCreate()
{
// Custom code
...
// Call default event handler if required. It will return a standard outcome
for this button click.
ApplicationsTreeEventHandler appTreeHandler =
ApplicationsTreeEventHandler.getInstance();
String outcome = appTreeHandler.processCreate();
// If popup is required to be invoked after event handling
PatternUtils.invokePopup(popupId);
return outcome;
}
}
2.
3.
Select the Property Inspector for the Applications Tree, and choose the Create
Action property. Set #{CustomEventHandler.processCreate} as the expression for
the property.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-31
When the Data Source is selected, you can configure the ADF tree. Use the Add icon to
add one of the children of the selected Data Source to be the next level of the tree, as
shown in Figure 1717.
Figure 1717
Tree Level Rules: This pane displays rules that control the display order of the
hierarchical tree or tree table UI components. The tree binding populates the tree
UI component starting from the top of the Tree Level Rules list and continues until
it reaches the last rule or until it encounters a rule whose accessor cannot find a
target attribute. The more rules you choose, the more nodes you can display in the
tree or tree table UI component.
Folder Label: Specify an Expression Language expression that selects labels to
display in the tree, such as #{label.countryLabel}.
You also can use the Expression Language expression #{node.accessorLabel} to
obtain information that allows you to traverse up and down a tree of data, not
necessarily starting at the logical root node of the tree. This is useful if you want to
access a parent node rather than the root node of the tree.
Enable Filtering: Select to filter the data that displays in the tree or tree table.
After you select this checkbox, you can select an attribute on the data collection
that will be used to filter the table data that display in the tree or tree table.
Available Attributes and Selected Attributes: The shuttle at the bottom of the
Create Applications Tree panel allows you to control the attributes at each tree
level you wish to display as a tree node in the tree. When finished, click Continue
to proceed to the Configure Tree Patterns Dialog. Select Cancel to abort the
creation of the Applications Tree.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-33
You may select any or all of the following five actions for your Applications Tree:
Create, Duplicate, Edit, Delete and Export. If you enable Create, Duplicate, or Edit,
you must choose the appropriate pattern that will be used to invoke that action (Inline,
Popup, or Page).
Inline - Perform the action on the current table row (only available for the
Duplicate action)
Popup - Bring up a div modal window on top of the current page for the
requested action
Page - Replace the current page or page fragment with a completely separate page
or page fragment to perform the action. Page fragments are used when using
bounded task flows.
The Add button for configuring the Popup button is enabled when the Popup pattern
is selected. When you click Add, a dropdown of the data collection name of each tree
level is displayed. You need to choose the tree level that needs the popup to be
configured. When a data collection name is selected, the Applications Popup wizard is
displayed. (See Section 17.4, "Using the Custom Wizard with Applications Popups.")
This same data collection will automatically be bound to the Applications Popup. The
Popup will also be defaulted as having Editable Content on the Window Buttons page
in the wizard.
Export: Export the data to a Microsoft Excel-compatible file.
Delete: Allows users to delete the row.
Confirm Delete: Select this option so that the default The selected record(s) will
be deleted. Do you want to continue? prompt displays in a popup when the
delete row function is used.
When you set the confirmDelete attribute to true, the confirmation popup
displays and the row is deleted when you click Ok. For this to work correctly, the
partialTriggers on the af:tree inside the fnd:applicationsTree should include
::confirm, and the ::delete and ::deleteConfirm ids must be removed so the
partialRefresh happens only when you click Ok in the popup. See
Section 17.1.2.2.1, "Manually Enabling Delete Confirmation."
Select the <fnd:applicationsTree ...> line in the Source view of the page.
All the components created as part of the Applications Tree are editable using this
same approach, as shown in Figure 1719.
Figure 1719
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-35
2.
3.
Drag and drop either the entire data source or individual fields into the correct
location on the page. The correct location is dependent on the component.
Adding UI Content
To achieve the final goals for a page design, you will likely need to add other
components to the Applications Tree. Common facets are provided to help you achieve
these goals. The facet names and use are documented in the Facet tree of the
Component Structure and Functions. For example, your tree may require an additional
action beyond the standard actions that are provided by the Applications Tree. You can
navigate to the Component Palette and drag and drop a commandToolbarButton
component on to the additionalToolbarButtons facet to add a new icon to the Tree
toolbar.
Increasing Tree Width to Fill 100% of Its Container
An Applications Tree can be stretched by placing it in the center facet of an ADF
panelStretchLayout component. Do not set the inlineStylewidth on
panelStretchLayout. For more information about basic page layout and the
inlineStyle attribute, see the "Organizing Content on Web Pages" and the
"Customizing the Appearance Using Styles and Skins" chapters in the Oracle Fusion
Middleware Web User Interface Developer's Guide for Oracle Application Development
Framework.
Facets for adding items such as ADF tree table and custom toolbar buttons.
Select the Application Tree Table from the Applications component palette and
drag and drop it on your page.
Drag and drop a data collection from the data control palette to your page and
select the Applications Tree Table from the list of available UI components.
The properties shown in Table 176 are exposed on the Applications Tree Table:
Table 176
Property
Description
Allowed Values
id
string
rendered
boolean / expression
treeTableId
string
createPatternType
editPatternType
duplicatePatternType
deleteMsg
deleteEnabled
boolean
createEnabled
boolean
duplicateEnabled
boolean
editEnabled
boolean
confirmDelete
method expression
editAction
method expression
duplicateAction
method expression
deleteAction
method expression
createActionListener
method expression
editActionListener
method expression
duplicateActionListener
method expression
deleteActionListener
method expression
createPopupId
string
editPopupId
duplicatePopupId
string
deletePopupId
string
createText
expression
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-37
Description
Allowed Values
editText
expression
duplicateText
expression
deleteText
expression
exportEnabled
boolean / expression
featuresOff
string
inlineStyle
styleClass
string
createImmediate
boolean / expression
deleteImmediate
boolean / expression
duplicateImmediate
boolean / expression
editImmediate
boolean / expression
createDisabled
deleteDisabled
editDisabled
duplicateDisabled
actionsMenuRendered
boolean / expression
Sets the rendered attribute value of the
Actions menu. When CRUD actions are not
turned on, and no af:commandMenuItem is
added to the additionalActionItems facet,
actionsMenuRendered should be set to False
so that an empty Actions menu will not be
displayed.
Description
Allowed Values
primaryToolbarRendered
boolean / expression
secondaryToolbarRendered
boolean / expression
toggleEditRendered
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-39
Description
Allowed Values
<button_
name>PartialTriggers
String of IDs.
For example:
deletePartialTriggers
Example 1:
To disable the Edit, Delete and
Duplicate buttons when the table is
empty, set this property on the
editDiabled, deleteDisabled or
duplicateDisabled property of the
Applications Tree Table.
#{bindings.VOiterator.estimated
RowCount == 0 ? true: false}
where VOiterator is your
iterator name
Example 2:
Disable any of the buttons in the
Applications Tree Table according to
the functional rules or by setting
disable=false when create is
selected on an empty table
(considering these buttons were
disabled following Example 1).
To do this, create an attribute
binding on the view object attribute
that will decide whether the row
can be deleted/edited/duplicated.
For example, you can use a binding
similar to this example on the
disable property of a button:
#{bindings.MyAtttrBinding.input
Value == 'compare value' ? true
: false}
Add Partial Page Refresh (PPR) on
the button to the table ID of the
af:table. This does not require any
change in the selectionListener of
the table. Keep the default one.
Example 1710 Sample Markup Generated by the Applications Tree Table Creation
Wizard
<fnd:applicationsTreeTable treeTableId="treeTable1" id="appsTree1"
createPatternType="secondaryWindow"
createPopupId="create1,create2"
duplicatePatternType="inline"
deleteEnabled="true">
<f:facet name="treeTable">
<af:treeTable value="#{bindings.ServiceRequestsView1.treeModel}"
var="node" rowSelection="single"
selectionListener="#{ApplicationsTreeBean.treeSelectionHandler}"
id="treeTable1"
partialTriggers="::duplicate ::duplicateMenuItem ::delete
::deleteMenuItem">
Table 177 shows the facets that are exposed on the Applications Tree Table.
Table 177
Facet
Description
Allowed Children
treeTable
additionalAction Facet for adding more menu items to default menu items.
Items
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-41
Description
Allowed Children
ADF component
appsTreeTableVie Facet for adding Menu Items to the default view menu of
ADF menu item component
wMenu
the panelCollection. To add multiple menuItems to the view
menu, add an af:group component containing
af:menuItems.
Facet for adding popups. See Section 17.4, "Using the
Custom Wizard with Applications Popups."
popup
Model
The Applications Tree Table does not expose any bindings to the model. However,
components within the Applications Tree Table, such as the ADF tree table, will be
bound to the model.
Controller
The Applications Tree Table component ships a default managed bean (internal to the
Oracle Fusion Middleware Extensions for Applications team) that performs the
following functions that will only work with rowSelection="single" on the ADF tree
table:
Default event handlers for all toolbar button/menu item action events. Event
handler delegates to custom action method if set on the button/menu item action
property.
If no row is selected when the Create button or menu item is clicked, the
new row is created in the first-level of the Tree.
A new row is not added when the Create Pattern Type is page. Only a
standard outcome is returned
A new row is added into the tree table when the Create icon is clicked,
and Create Pattern Type is inline.
The selected row is made available for editing in a popup when the Edit
icon is clicked, and Edit Pattern Type is secondaryWindow.
When the Edit icon is clicked and Edit Pattern Type is page, only a
standard outcome is returned.
When the Duplicate icon or menu item is clicked, a new node is added
into the tree when the Create icon is clicked, and Create Pattern Type is
inline. All non-primary key values of the selected node are copied to the
new node.
Clicking the Delete icon deletes the selected row. It currently does not
perform cascade delete when a parent node is selected for delete. The
Applications developer needs to handle deleting the child nodes if it is
necessary.
If the secondaryWindow option is chosen for any pattern type, and the
corresponding popup id is set for that button (mandatory), selecting the button
invokes the popup.
If page is chosen for any pattern type, a standard outcome is returned on clicking
the button. Standard outcomes are Create, Edit, Duplicate and Delete for the four
respective toolbar buttons.
The Oracle Fusion Middleware Extensions for Applications (Applications Core)
provides a default selection listener for the ADF tree (the markup shows:
selectionListener="#{ApplicationsTreeBean.treeSelectionHandler}"). If a
developer needs to add custom logic to selection listener, the developer should call
this default selection listener from the custom logic. The treeSelectionHandler
method of ApplicationsTreeBean provides the following behavior:
Example 1711 Sample Code for Calling the Default Selection Listener from a Custom
Selection Listener
String defaultListener = "#{ApplicationsTreeBean.treeSelectionHandler}";
FacesContext fc = FacesContext.getCurrentInstance();
ExpressionFactory ef = fc.getApplication().getExpressionFactory();
MethodExpression me =
ef.createMethodExpression(fc.getELContext(), defaultListener,
String.class, new
Class[]{SelectionEvent.class});
me.invoke(fc.getELContext(), new Object[] {selectionEvent});
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-43
1.
Example 1712 Define a Managed Bean Class to Attach Custom Handler to a Button
import oracle.apps.fnd.applcore.patterns.ui.ApplicationsTreeEventHandler;
import oracle.apps.fnd.applcore.patterns.ui.util.PatternUtils;
public class CustomEventHandler
{
public String processCreate()
{
// Custom code
...
// Call default event handler if required. It will return a standard outcome
for this button click.
ApplicationsTreeEventHandler appTreeHandler =
ApplicationsTreeEventHandler.getInstance();
String outcome = appTreeHandler.processCreate();
// If popup is required to be invoked after event handling
PatternUtils.invokePopup(popupId);
return outcome;
}
}
2.
3.
Open the Property Inspector for the Applications Tree Table and choose the Create
Action property. Set #{CustomEventHandler.processCreate} as the expression for
the property.
Component First
Navigate to the Component Palette. Click the list of libraries and select Applications.
Drag the Applications Tree Table from the list of components and drop it onto the page
to launch the wizard.
Data First
Navigate to the Data Controls panel of the Application Navigator. Open the panel and
navigate through the hierarchy to locate the data source that you would like to include
in the Applications Tree Table. Select that data source and drag it to the page. A
context menu will display a list of components. Select Tree under the Applications
menu to launch the Applications Tree Table wizard, as shown in Figure 1720.
Figure 1720
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-45
Figure 1721
When the Data Source is selected, you can configure the ADF tree. Click the Add icon
to add one of the children of the selected Data Source to be the next level of the tree, as
shown in Figure 1722.
Figure 1722
The shuttle at the bottom of the Create Applications Tree Table panel allows you to
select the attributes at each tree level you wish to display as a tree node or columns in
the tree table, as shown in Figure 1723.
Figure 1723
Selecting Attributes
When finished, click Next to proceed to the Select Tree Table Columns panel. Select
Cancel to abort the creation of the Applications Tree Table.
Select Tree Table Columns Panel
The Select Tree Table Columns panel shown in Figure 1724 allows you to select an
attribute for displaying as node stamp and select an attribute for displaying as path
stamp. You can also configure the columns to be displayed inside the tree table here.
When finished, click Next to proceed to the Configure Tree Table Patterns Dialog.
Selecting Cancel will abort the creation of the Applications Tree Table.
Figure 1724
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-47
You may select any or all of the following five actions for your Applications Tree Table:
Create, Duplicate, Edit, Delete and Export. If you enable Create, Duplicate, or Edit,
you must choose the appropriate pattern that will be used to invoke that action (Inline,
Popup, Page).
The Add button for configuring the Popup button is enabled when the Popup pattern
is selected. When you click Add, a dropdown of the data collection name of each tree
level is displayed. You need to choose the tree level that needs the popup to be
configured. When a data collection name is selected, the Applications Popup Wizard is
displayed. (See Section 17.4, "Using the Custom Wizard with Applications
Popups.")This same data collection will automatically be bound to the Applications
Popup. The Popup will also be defaulted as having Editable Content on the Window
Buttons page in the wizard. Refer to Section 17.4, "Using the Custom Wizard with
Applications Popups."
Export: Export the data to a Microsoft Excel-compatible file.
Delete: Allows users to delete the row.
Confirm Delete: Select this option so that the default The selected record(s) will
be deleted. Do you want to continue? prompt displays in a popup when the
delete row function is used.
When you set the confirmDelete attribute to true, the confirmation popup
displays and the row is deleted when you click Ok. For this to work correctly, the
partialTriggers on the af:treetable inside the fnd:applicationsTreeTable
should include ::confirm, and the ::delete and ::deleteConfirm ids must be
removed so the partialRefresh happens only when you click Ok in the popup. See
Section 17.1.2.2.1, "Manually Enabling Delete Confirmation."
Click Finish to complete creation of the Applications Tree Table. Select Cancel to abort
the creation of the Applications Tree Table.
Figure 1726
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-49
17.3.1.2.1
When you have created the Applications Tree Table, you can add data controls to the
facets and content containers within that tree table using the following steps:
1.
2.
3.
Drag and drop either the entire data source or individual fields into the correct
location on the page. The correct location depends on the component.
17.3.1.2.2
Adding UI Content
To achieve the final goals for a page design, you probably will need to add other
components to the Applications Tree Table. Common facets are provided to help you
achieve these goals. The facet names and use are documented in the Facet table of the
Component Structure and Functions. For example, the tree table may require
additional actions beyond the standard actions that are provided by the Applications
Tree Table. You can open the Component Palette and drag and drop a
commandToolbarButton component onto the additionalToolbarButtons facet to add a
new icon to the Tree Table toolbar.
17.3.1.2.3 Increasing Tree Table Width to Fill 100% of Its Container An Applications Tree
Table can be stretched by placing it in the center facet of an ADF panelStretchLayout
component. Do not set the inlineStylewidth on panelStretchLayout. For more
information about basic page layout and the inlineStyle attribute, see the
"Organizing Content on Web Pages" and the "Customizing the Appearance Using
Styles and Skins" chapters in the Oracle Fusion Middleware Web User Interface Developer's
Guide for Oracle Application Development Framework.
17.3.1.2.4 Toggle Click to Edit / Edit All in Applications Tree Table The Applications Tree
Table toolbar has an icon that can be clicked to toggle the Click to Edit and Edit All
functions, and the View Menu on the toolbar includes the same toggle feature. This
functions the same as described for the Applications Table in Section 17.1.2.2.3, "Toggle
Click to Edit / Edit All in Applications Table."
Note:
Popups are an option when editing rows. While the standard af:popup component
does not provide buttons or data binding, the Applications Popup wizard provides the
base af:popup with:
a title
standard buttons
data binding
design-time support
Pattern Set
Patterns
Description/User Action
Attachments
Attachments Field,
Attachments Column
Compare Objects
Create
Detail On Demand
Popup Details
Edit
Information Entry
Form
Secondary Window
Record Navigation
Transactional
Search/Results
Popup Window
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-51
2.
Navigate to the data source that you want to bind to the popup.
3.
Drag and drop the data control to the JSF page, as shown in Figure 1727.
Figure 1727
4.
In the Create context menu that is displayed, choose Applications > Popup.
The Popup wizard is displayed.
In the Configure Table Patterns dialog, set the Create, Duplicate or Edit Pattern
to Popup.
3.
4.
Note:
Define buttons.
Create a preview.
All mandatory fields in the wizard contain default values, allowing you to accept the
defaults and work through the steps quickly. Clicking Cancel on any of the dialogs
cancels the popup creation and discards any values you entered.
Clicking Finish on any of the dialogs has the following effects:
1.
Enter a popup Id. The Id is a string that must be unique to the page fragment.
It is used when other components want to be related to this component. For
example, if you have a table with Create in Popup, the Create button needs to
include this popup Id so it can call it.
Enter a title for the popup window.
The title is prepopulated with the Oracle Fusion Applications Standard for the
title, which is a combination of the action of the task, the type of object, and
the specific object name:
[Action] [Object Type]: [Object Name]
The title should be a reference to a single message with appropriate tokens,
because, according to Oracle internationalization standards, you should not
concatenate translatable messages in the code. See the "Internationalizing and
Localizing Pages" chapter in the Oracle Fusion Middleware Web User Interface
Developer's Guide for Oracle Application Development Framework, and the
expanded information in "To add an Applications Table using the Applications
Table wizard:".
So, in this example, the title reference in the JSF page fragment source would
resemble: #{af:formatNamed(bundle.EDIT_INVOICE,'INVOICE_
NUMBER',bindings.Invoices.InvoiceNumber)}
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-53
2.
[Optional] Enter a title icon location or click Browse to navigate to the icon's
location.
Select the number of layout columns -- 2 or 3 -- for the popup. This affects the
data you bind to. For instance, if you are showing an address with name,
street, and town, you could put this information in two or three columns.
Figure 1729
The Components table is automatically populated with the data source fields.
Click the Reorder icons to change the position of the selected component
in the list.
Click an entry in the Display Label column to enter a new label, such as
Dept. Number instead of DeptNo.
Figure 1730
Figure 1731
3.
In the Enable Window Buttons dialog, you can perform the following actions:
If the popup requires navigation workflow, such as when choices within the
popup lead users to another window:
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-55
Figure 1732
Figure 1733
4.
5.
Click Cancel to delete the popup information and exit the wizard.
When you click Finish, the af:popup component is displayed in the page, as
shown in Figure 1734.
Figure 1734
Access the popup by double-clicking one of the following on the JSF page:
3.
Drag and drop the entire data source, or individual fields, to the JSF page in
Design mode.
Data-source fields are bound to popup components. Components are stored in the
contents facet under the af:panelFormLayout hierarchy.
Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables 17-57
3.
18
Implementing Applications Panels,
Master-Detail, Hover, and Dialog Details
18
This chapter discusses the Applications Panels, Master-Detail, Hover and Dialog
Details components used to implement user interface features in JDeveloper.
This chapter includes the following sections:
Chapter 17, "Implementing UIs in JDeveloper with Application Tables, Trees and
Tree Tables"
Page title
Form title
You must use Applications panels to standardize layout and appearance for all your
page forms and buttons, including read-only pages.
Before you begin:
Before you can use Applications panels, you must be familiar with JDeveloper and be
able to create JavaServer Faces (JSF) pages.
Data-saving processes: Save, Submit, Save and Continue, Save and Next, Save
and Create Another, Continue, Create Another, Save and Close
Navigational processes: Next, Previous, Back
The buttons are organized into four slots, as shown in Figure 187.
All panel buttons have attributes, and some buttons have facets. Button attributes
include button qualities, such as the title string and the button name. Button facets are
locations that contain panel data, such as content locations and button information
locations.
Table 181 contains attributes that are exposed for the buttons.
Table 181
Property
Description
Data Type
id
string
rendered
boolean or expression
title
Panel title.
string or expression
navigationType
Navigation types:
<button_name>Visible
boolean or expression
For example:
submitVisible
<button_
name>Rendered
For example:
submitRendered
<button_name>Action
EL expression
<button_name>PopupId
string
string
boolean or expression
For example:
submitPopupId
<button_
name>ShortDesc
For example:
previousShortDesc
<button_
name>Disabled
For example:
submitDisabled
Description
Data Type
submitText
string or expression
scrollable
boolean / expression
saveOptionsStyle
Sets the appearance of the Save button. The Save button or dropButton
button can be rendered as a normal button, or as a
drop button, depending on the value of this
attribute. When it is set to dropButton, the
developer is expected to have other save options
turned on (such as saveAndContinue or
saveAndClose), or add af:commandMenuItem to
the saveButtonMenu facet.
instructionText
panelToolbarRendered
Boolean
If no default buttons that are provided by the
Applications Panel are used, set this value to false
to avoid displaying unnecessary separators.
revertImmediate
Sets the immediate attribute on the Revert button. Boolean. Default is false.
Sets whether data validation - client-side or
server-side - should take place when events are
generated by this component. When immediate is
true, the default ActionListener provided by the
JavaServer Faces implementation should be
executed during the Apply Request Values phase
of the request processing lifecycle, rather than
waiting until the Invoke Application phase.
submitStyle
previousPartialSubmi
t
Description
Data Type
nextPartialSubmit
saveAndCreateAnother
Text
String
createAnotherText
String
<button_name>Action
String or EL Expression.
<button_
name>ActionListener
EL Expression.
<button_
name>PartialTriggers
String or EL Expression.
For example:
saveAndClosePartialT
riggers
submitAccessKey
createAnotherAccessK
ey
saveAndCreateAnother
AccessKey
Character
The value to this must be one of the
characters given for the
createAnotherText property to get
an access key. The character will be
displayed as underlined on the
component name.
Character
The value to this must be one of the
characters given for the
saveAndCreateAnotherText property
to get an access key. The character
will be displayed as underlined on
the component name.
By default, a managed bean that ships with the Applications Panel enables certain
actions when certain conditions exist. For example, default actions occur when users
click buttons, and when developers set certain Applications Property values. These
default actions are overridden if you change the value of the default button action
property.
Table 182 contains facets that are exposed for each panel button.
Table 182
Facet
Description
Allowed Children
contents
navigationBar
ADF selectOneChoice
actionButtonBar
saveButtonMenu
af:commandMenuItem or af:group
submitButtonMenu
None
popup
Facet for holding any popups required for any Applications popups under some
of the buttons.
ADF layout components.
appsPanelLegend
appsPanelContext
customSaveDropButton
localContext
Description
taskStamp
Allowed Children
Description
Allowed Children
collabrationToolbar
Example:
Example:
scalingInfo
<f:facet
name="collaborationToolbar">
<af:toolbox>
<af:toolbar>
< af:commandImageLink
text="One" icon="/image1"
id="mycmd1"/>
< af:commandImageLink
text="Two" icon="/image2"
id="mycmd2"/>
< af:commandImageLink
text="Three" icon="/image3"
id="mycmd3"/>
</af:toolbar>
</af:toolbox>
</f:facet>
<af:panelGroupLayout
layout="vertical"
styleClass="AFStampContainer"
id="pgl3">
<af:outputText value="AUD =
Australian Dollar" id="ot5"/>
</af:panelGroupLayout>
Example for scalingInfo with more
than one value:
<af:panelGroupLayout
layout="vertical"
styleClass="AFStampContainer"
id="pgl3">
<af:outputText value="AUD =
Australian Dollar | Amounts in
thousands" id="ot5"/>
</af:panelGroupLayout>
submitButtonMenu
af:commandMenuItem or af:group
Description
Allowed Children
contentsStretch
Description
Allowed Children
This can be either scroll (the
default) or stretch. Set to stretch
when using the contentsStretch
facet.
contentsFacet
Model
The Applications panel does not expose any bindings to the model. However,
components within the panel can be bound to the model.
Controller
The Applications Panel component ships with a default managed bean (internal to the
Oracle Fusion Middleware Extensions for Applications team) that performs the
following functions:
Default event handlers for all button action events. Event handler delegates to
custom action method if set on the button action property. Each button event
handler simply returns a standard outcome which is the name of the button
clicked. For example, clicking the Cancel button will return an outcome "cancel".
If popup ID is set for any button, selecting the button invokes the popup.
Example 181
import oracle.apps.fnd.applcore.patterns.ui.ApplicationsPanelEventHandler;
import oracle.apps.fnd.applcore.patterns.ui.util.PatternUtils;
public class CustomEventHandler
{
public String processCancel()
{
// Custom code
...
// Call default event handler if required. It will return a standard outcome
// for this button click.
ApplicationsPanelEventHandler appPanelEventHandler =
ApplicationsPanelEventHandler.getInstance();
String outcome = appPanelEventHandler.processCancel();
// If popup is required to be invoked after event handling
PatternUtils.invokePopup(popupId);
return outcome;
}
Implementing Applications Panels, Master-Detail, Hover, and Dialog Details 18-9
}
2.
3.
Open the Property Inspector for the Applications panel and choose the Cancel
Action property. As shown in the example in Figure 181, set
#{CustomeEventHandler.processCancel} as the expression for the property.
4.
5.
6.
Click Set.
3.
In the list, click Panel. JDeveloper will attempt to place the panel at the current
cursor location. If the current location is not appropriate, an error message
displays. You also can drag the Panel icon to the page in either the Design or the
Source view. A plus (+) sign will be added to the arrow when it is over a location
in which a panel can be inserted.
The Applications Panel wizard is displayed.
Navigate to the data source that you want to bind to the Applications panel.
3.
4.
In the Create context menu that is displayed, choose Applications > Panel.
The Applications Panel wizard is displayed.
In any Applications Panel wizard dialog, click Cancel to cancel your actions and exit
the wizard. Click Finish on any dialog to accept the defaults and exit the wizard.
To Add an Applications Table Using the Applications Panel Wizard:
When the Applications Panel wizard is launched, the Title and Subsections dialog is
displayed, as shown in Figure 182.
Figure 182 Specifying the Panel Title and Subsections
1.
In the dialog:
Enter the panel title. In the example, LABEL should be predefined in a bundle
as "Edit Journal: ID {OBJ_ID}".
The title is prepopulated with the Oracle Fusion Applications Standard for the
title, which is a combination of the action of the task, the type of object, and
the specific object name:
[Action] [Object Type]: [Object Name]
The Object Name usually is something specific so you can identify a specific
object. For instance, if you were dealing with part numbers, the Object Name
Click the Add icon (+) to add Panel Subsections, or click the Delete icon (X) to
delete the highlighted subsection.
Each subsection has editable title fields, panel type fields (Panel Header for a
basic view or Show Detail Header for a more detailed view), and number of
columns (1-3) fields.
The Panel Subsections is used to divide the Applications Panel facet (contents)
with other layout components, such as panelHeader, show detail header, and
panelGroupLayout. This lets the developer decide the layout during Design
Time without needing to add each of these layouts manually after the panel
creation. Of course, the user can add more or new layouts as needed after the
panel is created.
Use the up or down arrows to change row order.
2.
Click Next.
The Select an initial set of panel components dialog is displayed, as shown in
Figure 183.
3.
a.
b.
If you have added the panel from the Component Palette, the Bind Data Now
field displays. To bind a data source to the panel component:
Click Browse to display the Data Source dialog, shown in Figure 184.
Select the data source, then click OK to add it to the component. Optionally, you can bind the component to a data source at a later time.
When you choose a data source, the component fields in the dialog are
automatically populated with the data source fields, which contain
panel-component information.
4.
c.
d.
Display Label: In general, the labels defined in the selected Data Control will
be what you want and you can leave this value at the default <Default>
setting. Otherwise, enter a new label name.
e.
Value Binding: In general, the label and the Value Binding will match and you
can accept the displayed value. Otherwise, you can click in the field to display
a drop-down list of the values available in the selected Data Control.
f.
Click Next. The Components Layout dialog is displayed, as shown in Figure 185.
5.
6.
Click Next. The Page Buttons dialog is displayed, as shown in Figure 187.
7.
Choose the transactional buttons to display in each panel slot from the
respective slot dropdown menus.
Note that Slot 3 defaults to Continue. However, as shown in Figure 187, if
you select Submit, a text input field displays to the right. You can enter
alternate text that makes more sense in your application for the submit
action, such as OK or Purchase.
You can create a Save or Submit pull down menu. When you choose Save
in Slot 2, or Save and Close in Slot 3, an Add Menu option will appear.
Click it to display a list similar to Figure 188.
These are options that can appear in a pull down menu at runtime under
Save. To select, click the option you want. To add more than one, select
Add Menu again and choose a second option. As they are chosen, check
marks will appear next to each selected item, shown in Figure 189.
When an item is selected from the Add Menu of Slot 3, the selection of the
drop-down in Slot 3 will become the label of af:commandToolbarButton
and the selections in the Add Menu will become the af:commandMenuItem
under af:menu in the popup facet of the af:commandToolbarButton. The
af:commandToolbarButton will be added to the customSaveDropButton
facet (see Table 182).
Figure 189 Add Menu List Showing Multiple Selections
8.
Figure 1811
9.
10. Click Finish to create the panel. When you run this page, it will appear similar to
Figure 1812.
Figure 1812
basic page layout and the inlineStyle attribute, see "Organizing Content on Web Pages"
and "Customizing the Appearance Using Styles and Skins" in Oracle Fusion Middleware
Web User Interface Developer's Guide for Oracle Application Development Framework.
Access the panel by double-clicking one of the following on the JSF page:
When you select the panel as described in this section, the Applications Panel Property Inspector is displayed.
3.
Follow the instructions in the Property Inspector to modify the panel property.
1.
2.
3.
When you double-click the component, the Property Inspector for the component
is displayed. Edit the component in the Inspector.
For example, to edit a subsection display name, select the subsection and edit the
Text property in the Property Inspector for that subsection.
3.
Drag and drop the data source itself (or its individual fields) to the JSF page in
Design mode.
Data-source fields are bound to panel components. Components are stored in the
contents facet as af:panelFormLayout components, and in the various subsections.
For example, Figure 1813 shows a panel's Structure view, which contains added
components.
Figure 1813
To create an additional field in a subsection, drag an attribute from the data source
to the corresponding container. For example, drag the attribute to
fnd:applicationsPanel > f:facet - contents > af:panelGroupLayout >
af:panelFormLayout. When prompted for the component to associate with the
attribute, choose ADF Input Text w/Label.
Drag and drop the button component on to the appropriate popup facet.
For example, to add a new button, drag and drop the button to the
actionButtonBar facet.
For more information on facets, see Table 182, " Facets of Standard Panel Buttons".
The Master-Detail composite is used in situations where the information is too large,
dynamic or complex to show in a flat table. The user can see the Master, or summary,
information in one area, and the corresponding details in a separate area. This can be
Implementing Applications Panels, Master-Detail, Hover, and Dialog Details 18-19
achieved using different master and detail components, such as table, tree table, and
tree.
For instance, when the user selects an Employee from the master table, the
corresponding employee details are displayed in the region below in a label/data
format.
For more information, see the "Displaying Master-Detail Data" section in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Facet
Description
Allowed Children
Master
Detail
Applications Table
View Properties
See Table 172, " Applications Table Properties" in Section 17.1, "Implementing
Applications Tables" for a list of properties exposed on the Applications Table. These
properties can be used to configure the Applications Table under either the Master or
Detail section of the Applications Master-Detail component.
Model
The Applications Master-Detail does not expose any bindings to the model on its own,
but the ADF tables or formLayout components that are encapsulated within the
Applications Table under the master or detail section will be bound to the model.
Controller
The Applications Master-Detail ships a default managed-bean (internal to the Oracle
Fusion Middleware Extensions for Applications (Applications Core) team) that
currently supports translation functions. You can access the implementation of the
Applications Table managed bean which will be exposed as either the Master or the
Detail section of the component. For use and implementation information, see
Controller in Section 17.1, "Implementing Applications Tables."
Table over Heterogeneous (every row can have a different detail section)
Form Layout over Tree (available via Form Layout over Heterogeneous)
Tables are the most common master component. When a table row is selected, the
details appear in the area below the table. A table is also a very common detail
component.
A Tree Table is a layout option in a Master-Detail composite for either a Master or a
Detail (not both). When a Tree Table row is selected, the details appear in the area
below the Tree Table.
Sub tabs are a detail layout option in a Master-Detail composite.
Form Layout is a detail layout option in a Master-Detail composite.
2.
Navigate to the data source that you want to bind to the Master-Detail.
3.
4.
Figure 1814
Figure 1817
Panel Header / Show Detail Header: Select one of these options to activate the
Master Header Label field to enclose the Master-Detail with a header. There are
basically two types of headers:
In the example in Figure 1818, the Edit Element Entries text is the Panel Header
and the Basic Information text with the expand/collapse icon is the Show Detail
Header. The picture, Name and Social Security Number are the content, which is
enclosed by the Show Detail Header. Then everything is enclosed by the Panel
Header, shown in Figure 1818.
Figure 1818
Master Header Label: Enter the label to be used by either the Panel Header or the
Show Detail Header.
Select the Pattern Type (the example uses Table/Table) and any options and click Next.
The Configure Master dialog displays, shown in Figure 1819.
Figure 1819
Click Read-only Table to create a read-only Master table. (optional) If you select
Read-only, the choices in the Component to Use column will change from Input
Text to Output Text types.
2.
In the Enable ADF Behavior section, choose whether to allow users to Select, Sort,
and Filter rows.
3.
Click the menu arrow to select value bindings for each value.
After selecting a component, click the Delete icon (X) to delete it, the Add icon
(+) to edit it, and the Reorder icons to change its position in the field.
Click Next to display the Configure Master Table Patterns dialog, shown in
Figure 1820.
Figure 1820
4.
5.
Click Next to display the Configure Detail Header dialog, shown in Figure 1821.
Figure 1821
6.
7.
8.
Configuring the Details Table Patterns is the same as configuring the Master Table
Patterns; see Figure 1820 and step 5.
9.
Figure 1822
When you click Finish, the Table/Table Master-Detail is added to the editor, and
appears similar to Figure 1823 in Design mode.
Figure 1823
1.
Figure 1824
This configure dialog is the same as the one for creating a Table, except that it does
not have the Enable ADF Behavior settings, as shown in Figure 1819.
2.
Figure 1825
Select the navigation buttons you want to appear on the Main form.
3.
Click Next to display the Detail Header dialog, shown in Figure 1821 for details.
4.
Click Next to display the Configure Details dialog, shown in Figure 1826.
Figure 1826
Use this dialog to create as many tabs on the Details form as you need. To create a
new tab, enter a name in the Name field and click the Add icon. The tab is added
in the area beneath the Name field.
Each tab is the same as the dialog for creating a Table, except that it does not have
the Enable ADF Behavior settings, shown in Figure 1819.
5.
Click Next to display the Configure Navigation Buttons for the Detail section
dialog, shown in Figure 1825.
6.
7.
Figure 1827
Have a page-level Submit or Save button that would save the newly-created
master record before creating a detail record.
2.
Set the autoSubmit property on all the elements (components) of the master to
true. For example, if the master is a table, set autoSubmit="true" on all the
components inside the af:column.
Implementing Hover
af:commandLink
af:commandImageLink
af:commandToolbarButton
The DT will verify whether the component is in a table already bound, and if that
binding is for the collection being dropped.
If so, it will create additional table bindings for the attributes selected.
If it is not dragged into an allowed table component, it will create additional bindings
for that collection.
If the allowed component already has a showPopupBehavior component child, the
menu option will not show. This behavior helps prevent double adding of hovers.
A dialog displays so you can select the attributes to see in the hover popup, and the
alignment of the popup over the "hovered" component, shown in Figure 1829.
Implementing Hover
Figure 1829
afterEnd
beforeEnd
beforeStart
endAfter
endBefore
startAfter
startBefore
The drop component will be given an Id if it does not have one already, and have
the clientComponent attribute set to true.
The drop component will have a <af:showPopupBehavior> component added as a
child.
A popup (<af:popup>) will be added as the previous sibling of the drop
component, shown in Example 182 for the sample markup, and Figure 1830 for
a sample of the result.
Example 182
<af:popup id="popup1">
<af:panelFormLayout labelAlignment="start">
<af:panelLabelAndMessage label="#{bindings.MasterId.hints.label}">
<af:outputText value="#{bindings.MasterId.inputValue}">
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
</af:outputText>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="#{bindings.Col1.hints.label}">
<af:outputText value="#{bindings.Col1.inputValue}"/>
</af:panelLabelAndMessage>
Implementing Hover
<af:panelLabelAndMessage label="#{bindings.Col2.hints.label}">
<af:outputText value="#{bindings.Col2.inputValue}">
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
</af:outputText>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage label="#{bindings.Col3.hints.label}">
<af:outputText value="#{bindings.Col3.inputValue}">
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
</af:outputText>
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:popup>
<af:commandLink actionListener="#{bindings.Last.execute}"
text="#{applcoreBundle.LAST}"
disabled="#{!bindings.Last.enabled}"
id="rolloverComponent2" clientComponent="true">
<af:showPopupBehavior triggerType="mouseOver" popupId="popup1"
alignId="rolloverComponent2"
align="afterStart"/>
</af:commandLink>
Figure 1830
Example 183 shows the sample markup for a table-based layout and Figure 1831
shows an example of how the result appears.
Example 183
<af:panelLabelAndMessage
label="#{bindings.Master1.hints.Col2.label}">
<af:outputText value="#{row.Col2}">
<af:convertDateTime
pattern="#{applCorePrefs.dateFormatPattern}"/>
</af:outputText>
</af:panelLabelAndMessage>
<af:panelLabelAndMessage
label="#{bindings.Master1.hints.Col3.label}">
<af:outputText value="#{row.Col3}">
<af:convertNumber
pattern="#{applCorePrefs.numberFormatPattern}"/>
</af:outputText>
</af:panelLabelAndMessage>
</af:panelFormLayout>
</af:popup>
<af:commandLink ="hover over me" id="rolloverComponent2"
clientComponent="true">
<af:showPopupBehavior triggerType="mouseOver" popupId="popup1"
alignId="rolloverComponent2"
align="afterStart"/>
</af:commandLink>
</af:column>
Figure 1831
Select the Applications Dialog Details from the Applications component palette
and drag and drop it on your page.
Drag and drop a data control to your page and select the Applications Dialog
Details from the list of available UI components.
View
Table 184 shows the properties that are exposed on the Applications Dialog Details.
Table 184
Property
Description
Allowed Values
Id (id)
string
Rendered (rendered)
boolean / expression
Popup Id (popupId)
string
Text (text)
expression
Short Description
(shortDesc)
expression
Disabled (disabled)
Model
The Applications Dialog Details does not expose any bindings to the model. However,
components within the Applications Dialog Details, like the layout inside ADF popup,
will be bound to the model.
Controller
The Applications Dialog Details component does not ship a default managed bean.
Data First
Navigate to the Data Controls panel of the Application Navigator. Open the panel by
clicking its bar, then navigate through the hierarchy to locate the data source that you
would like to include in the Applications Dialog Details. Select that data source and
drag it on to the page. A context menu will appear with a list of components. Move the
mouse over the Applications category list. Select Applications > Dialog Details to
launch the Applications Dialog Details wizard, shown in Figure 1832.
Figure 1832
Figure 1833
You can skip the data control binding step when creating the Applications Dialog
Details. In this case, the Applications Dialog Details will create several default
placeholder outputText fields that you can use for layout purposes in the popup. You
can decide how many placeholder columns you wish to display. When you have
selected the appropriate number of fields, click OK to finish the creation process.
If you wish to bind a data control to the table component using the Component First
approach, check the Bind Data Now checkbox. This will enable the Browse button for
the Data Source property. Click the Browse button to display a list of data sources
available for binding. Navigate through the list, select the desired data source, and
click OK.
When the Data Source is selected, the developer can enter the title for the popup and
choose the Detail Pattern Type.
When link is selected for the Detail Pattern Type, you will need to select an attribute of
the data source that binds to the Text attribute. This is the displayed text of the link.
When image or button is selected for Detail Pattern Type, choosing an attribute is not
needed, as shown in Figure 1834.
Figure 1834
Title
If you want a new Title, enter the string here. The string will be converted to a text
resource and added to the default resource bundle.
If you already have a Title defined in a resource bundle, click the ellipsis and choose
from the list, as shown in Figure 1835.
Figure 1835
Resource Bundle: Select the bundle containing the string you want to use. You can
select a single bundle or all available bundles. The strings will display in the
Matching Text Resources field.
Display Value: You can enter a new string for a title here.
Key: Each resource must have a unique Key. This generally is, in all upper-case
characters, the words of the Display Value separated by an underscore character.
Figure 1836
Image: Shows the Dialog Details component as an image. The image is the same as
in the component palette. Clicking the image will open the Dialog Details popup.
Button: Shows the Dialog Details component as a button that opens the Dialog
Details popup when clicked.
Link: In this case, you will need to select the Text Attribute, which is a list of
columns in the Data Control you have selected (or dragged). This column data is
used as the link text.
Use of a specific pattern type is your choice and does not affect the way Dialog Details
behaves.
To display what the popup would show, you can choose a link that shows data
from the selected data control, such as a column in a table. For instance, in the
Employee table, to show more employee data, you can use the employee name as
the text attribute. Clicking an employee name then would open more data about
that employee.
A button can be used if there is only one Dialog Details popup for the page.
Clicking it gives more information about the data on the page.
Image could be used the same way as button, or on pages with form data.
Text Attribute
This setting is available only if the Detail Pattern Type is link. The text entered here is
shown as the Dialog Details link. This helps give the user an idea about the data
contained in the popup.
Read-only Form
If content in the dialog contains editable fields, the window should be modal.
If you select Read-only, the choices in the Component to Use column will change
from Input Text to Output Text types.
If this option is not selected; that is, the form can be edited by the user, two buttons
automatically are added to the form: Save and Close, and Cancel. Figure 1837 shows
the default buttons in the form in the JDeveloper Design view.
Figure 1837
If this option is selected; that is, the form cannot be edited by the user, only an OK
button automatically is added to the form, as shown inFigure 1838.
Figure 1838
Fields
Display Label: This value will be displayed for the column heading. The default
value is the text that is displayed in the Value Binding field.
Value Binding: This field lists the names of the columns from the selected data
control. Clicking an entry opens a list of the columns so you change the order in
which they appear.
Component To Use: Data in Dialog Details can be read-only or updatable.
Component to Use is similar to what Component does while creating a table.
Clicking it reveals a choice list of values, and the dialog details popup would then
at runtime show that particular column from the datacontrol as the selected
component to use. The choice list is changed according to whether you choose
read-only. If you selected Read-only, the choices will change from Input Text to
Output Text types.
All components created as part of the Applications Dialog Details are editable using
this same approach, shown in Figure 1839.
Figure 1839
2.
3.
Drag and drop either the entire data source or individual fields into the correct
location on the page. The correct location is dependent on the component.
For example, inside the popup that the Applications Dialog Details wizard generates,
the fields of the data source are bound to components. Figure 1840 shows the
Structure view of a page with components already added.
Figure 1840
To add a field from a data source to the af:panelFormLayout inside the popup, drag
the field from the data source to the following path: up > af:dialog >
af:panelFormLayout. As is the case with the data first approach, you will be prompted
to choose which ADF component to use for this attribute.
This example uses the Structure view because it provides an
efficient overview of the page. The field could also be dropped onto
the page in Design or Source view to achieve the same result.
Note:
Adding UI Content
To achieve the final goals for a page design, you will likely need to add other
components to the af:dialog inside af:popup.
"AdfPage.PAGE.findComponent('" + sourceId +
"').findComponent('::TaskPopup').hide();";
service.addScript(FacesContext.getCurrentInstance(), popup);
}
Create another method for the OK button that calls the method in Example 184, and
any additional processing logic. The common use case would be opening a new task in
the Main Area by using the openMainTask API. For example, you can bind the OK
button to a managed bean and add your own action listeners, as shown in
Example 185.
Example 185
Listener
import javax.el.ExpressionFactory;
import javax.el.MethodExpression;
import javax.faces.event.MethodExpressionActionListener;
public void setOkButton(RichCommandButton okButton) {
this.okButton = okButton;
if(okButton.getActionListeners().length==0){
FacesContext context = FacesContext.getCurrentInstance();
ExpressionFactory ef =
context.getApplication().getExpressionFactory();
String methodLink = "#{bindings.openMainTask.execute}";
MethodExpression me =
ef.createMethodExpression(context.getELContext(), methodLink,
null, new Class[]
{ ActionEvent.class });
MethodExpressionActionListener methodActionListener =
new MethodExpressionActionListener(me);
okButton.addActionListener(methodActionListener);
methodLink = "#{pageFlowScope.PopupBean.closePopup}";
me =
ef.createMethodExpression(context.getELContext(), methodLink,
19
Implementing Attachments
19
Section 19.4, "Displaying Attachments for Multiple Entities in the Same Table"
Section 19.9, "Integrating Attachments Task Flows into Oracle Fusion Functional
Setup Manager"
For general information about Oracle Fusion Middleware user interface (UI)
components, see:
19-1
Introduction to Attachments
A link to the most recently attached document or URL. Hovering your mouse
on a link supplies a detail window with attachment information. The detail
window contains the following information about the most recent attachment:
*
Type - File/URL/Text
Attached By
Attached Date
When clicked, the link opens the attachment in a new browser tab or window
depending on the browser settings.
If there are no attachments the value of this field will be None.
When there are more attachments, a link will be displayed in the format "<# of
additional attachments> more...". Clicking this link opens the Attachments
window, which displays the full list of attachments in a table.
Hovering over this link will display a small dialog with a list of up to the next
three most recent attachments. When clicked, these links opens the attachment
in a new browser tab or window depending on the browser settings. If there
are more than four attachments the last bullet is a link with the format " <# of
remaining attachments> more...". The number of attachments shown in the
small dialog list is configurable. Clicking this link opens the Attachments
window, which displays the full list of attachments in a table.
The Delete Attachments icon. Only shown when there is only one attachment
added. Allows the one attachment to be deleted without having to launch the
Attachment window.
Note:
Introduction to Attachments
A link to the most recently attached document or URL. Hovering your mouse
on a link supplies a detail window with attachment information. The detail
window contains the following information about the most recent attachment:
*
Type - File/URL/Text
Attached By
Attached Date
When clicked, the link opens the attachment in a new browser tab or window
depending on the browser settings.
If there are no attachments the value of this field will be None.
When there are more attachments, a link will be displayed in the format "<# of
additional attachments> more...". Clicking this link opens the Attachments
window, which displays the full list of attachments in a table.
Hovering over this link will display a small dialog with a list of up to the next
three most recent attachments. When clicked, these links opens the attachment
in a new browser tab or window depending on the browser settings. If there
are more than four attachments the last bullet is a link with the format " <# of
remaining attachments> more...". The number of attachments shown in the
small dialog list is configurable. Clicking this link opens the Attachments
window, which displays the full list of attachments in a table.
The Delete Attachments icon. Only shown when there is only one attachment
added. Allows the one attachment to be deleted without having to launch the
Attachment window.
Attachment table:
The Attachment table can be shown in:
Implementing Attachments
19-3
Introduction to Attachments
This occurs when you choose to display all attachments for the current record
in a table.
A dialog
Occurs when:
*
The user clicks Add or Edit in the toolbar of the Attachments Carousel
component
Table Toolbar
*
Add button, which adds a new row at the top of the table
Delete button, which deletes the selected rows from the table
Set Primary button, which sets the selected row to be the primary
attachment for its category. Displays when the setting the
enablePrimaryCategory property attribute for the Attachment component
to true (this button is optional)
File (default)
Text
URL
Introduction to Attachments
Repository File/Folder
Category
Category values are defined at implementation time. Make sure to use
functionally relevant category names. If two or more categories are defined,
the category column is displayed. If only one category is defined, the column
is not displayed.
One attachment out of all the attachments that have the same category value
can be designated as the primary. This is option can be enabled by setting the
enablePrimaryCategory property to true. By default it is off. When enabled a
new column title Primary will appear before the Category column. The
primary attachment will be indicated by a tick mark.
If Type is Repository File/Folder, will show a text field and browse button.
Clicking on Browse will launch a document picker for finding files in the
repository.
Title
The user name for the attachment, as the file name or URL may not
adequately convey the contents of the attachment. If users do not enter a title,
it defaults to the value in the File Name or URL field.
Description
The field to include additional information on the attachment.
Attached By
Shows the name of the user that last updated the attachment relationship.
Attached Date
Shows the date on which the attachment relationship was updated.
Implementing Attachments
19-5
Toolbar
Add button - opens the Attachment Table in a dialog with a new row.
Delete button - deletes the current attachment item shown in the carousel
Note:
Detail
Creating Attachments
The detail section contains the following information about the most current
attachment:
Type - File/URL/Text
Attached By
Attached Date
The detail section is hidden by default. However, it can be displayed by setting the
attachmentsDetailsRendered property to True.
Example 191
<grant>
<grantee>
<codesource>
<url>file:${atgpf.oracle.home}/atgpf/modules/oracle.applcore.attachments_
11.1.1/Attachments-Model.jar</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.credstore
.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.wsm.security,
keyName=keystore-csf-key</name>
<actions>read</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore
.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.wsm.security,
keyName=enc-csf-key</name>
<actions>read</actions>
</permission>
</permissions>
</grant>
Be aware that the URLs and <class> entries cannot contain any
spaces or line breaks.
Note:
Implementing Attachments
19-7
Creating Attachments
3.
Create the view object representation of the business object that requires
attachments in your model project.
4.
Log onto the Content Repository and confirm that the following has been created:
Creating Attachments
Note:
6.
Set the maximum size for files that can be uploaded. This setting is made to your
Application and will apply to any page that uses a multi-part form to upload from
the desktop to the Oracle WebLogic Server, not just Attachments.
This step does not need to be completed before continuing with the rest of the
implementation. By default the maximum size is defaulted to 2MB, which allow
an end-to-end implementation to be completed. However, it is important to
modify this setting before deployment. When deciding on the maximum size,
considering the type of files that your typical customer will be uploading with
your Application will help you determine a value.
For information about how to apply the settings, see "Setting Parameters to
Upload Files to Content Repositories" in Oracle Fusion Middleware Developing
Portals with Oracle WebCenter Portal and Oracle JDeveloper.
19-9
Creating Attachments
1.
2.
Choose the Business Tier > ADF Business Components category. Select the
Attachment View Link item, as shown in Figure 196.
3.
Click OK to access Step 1 of the Create Attachment View Link wizard, as shown in
Figure 197.
4.
Select the name of the module that your view object belongs to.
b.
Select the package where the attachment view link will reside.
c.
Creating Attachments
5.
Click Next to access Step 2. The View Object dialog appears, as shown in
Figure 198.
6.
Enter the name for the view link accessor that will be added to the data control of
selected view object. Then, from the Available column, select the view object that
you want to create attachments for.
Tip: There is no need for you to select a destination view object
because the Attachment view link always uses the Attachments view
object as the destination view object.
Figure 198 Create Attachment View Link Wizard View Object (Step 2)
Implementing Attachments
19-11
Creating Attachments
7.
Click Next to access Step 3. The Attachment Entity dialog appears, as shown in
Figure 199. The Attachment Entity is used to uniquely identify your business
object.
Figure 199 Create Attachment View Link Wizard Attachment Entity (Step 3)
8.
Available / Selected: Select only those columns that make up the primary key of
the entity object by shuttling them from the Available column to the Selected
column.
9.
Creating Attachments
Notes:
You can only add, edit or delete categories for the Application that
you selected in Step 1 of the Attachment View Link wizard.
The categories that you create here are not assigned automatically
to their attachment entity. You must ensure that all categories you
select in Step 9 are assigned to their Attachment Entity. For more
information, see Section 19.3.5, "How to Assign Categories to the
Attachment Entity."
Figure 1910
Select the categories to be made available for this entity in the runtime UI.
Note: Use the Add, Edit, and Delete buttons to add, edit, or delete
existing categories for the Application that you selected in Step 1. You
are not able to edit or delete the seeded Miscellaneous FND category.
Tip:
Select Display All Available Categories to show all categories that are assigned to
your attachment entity.
When you select Display All Available Categories, all other fields are
automatically removed from the dialog. You will no longer see a list of categories
and therefore, you will not be able to add, edit, or delete them. This selection,
however, does not override the document category to entity mapping.
You should select this option if you want Categories, assigned to your attachment
entity in the future, to appear in the Categories dropdown list at runtime. Selecting
this option will ensure that customers can create and use their own Categories in
your UI with minimal effort.
Implementing Attachments
19-13
Creating Attachments
Note:
The selected list of categories will be stored as a custom property on the newly
created attachment view link. The value will consist of a concatenated string of
values. All the selected categories are concatenated in a comma-separated list.
Note: It is recommended that you choose the Display All Available
Categories option to allow for customization of the Category list
without code changes. Additionally, please be aware that the list of
available categories, and the list of Attachments displayed can be
further controlled using Category data security. For more information,
see Section 19.10.1, "Attachment Category Data Security."
10. Click Next to access the Application Module page. The Application Module dialog
11. Click Next to access the Summary page, which is shown in Figure 1912. Review
your selections and click Finish to create your attachment view link.
Creating Attachments
Figure 1912
12. If you chose to keep the Application Module option unselected in Step 10, you
need to add your newly created attachments view link to your application module
data model as follows:
a.
b.
Choose Data Model from the list of categories to open the Data Model
Components dialog.
c.
Select the newly created Attachment View Link located in the left column and
select the view object that you created the view link for in the right column.
Shuttle the Attachment View Link over to the right column.
d.
The Attachment view link is created, including generating the Accessor in the
source view object.
All new or changed category information is stored to the FND_DOCUMENT_
CATEGORIES and FND_DOCUMENT_CATEGORIES_TL tables.
A custom property (OAF_ATTACHMENT_CATEGORY) is created on the Attachments
view link, which is a list of all the categories that you select in Step 4 of the wizard.
The custom property stores an empty list when you select the Display All
Available Categories checkbox. When this checkbox is not selected, the custom
property stores a comma-separated list of categories (using the CATEGORY_NAME
from the FND_DOCUMENT_CATEGORIES table) that you manually selected from the list
of available categories.
Implementing Attachments
19-15
Creating Attachments
The WHERE clause that links the Entity view object to the Attachments view object is
derived based on the selected entity primary key columns. For example, if the entity
primary key for the PO_INVOICES entity is made up of the columns INVOICE_HEADER_ID
and INVOICE_LINE_ID then the view link query would be as follows:
Example 192
where PO_INVOICES is the value that you entered in the Entity Name field in Step 3 of
the wizard.
remove() Method
Creating Attachments
See the " Available Seed Data Loaders" table in Chapter 57 for information about
Attachments Seed Data Loaders.
Drag the Detail Data Collection (the Attachments data collection) onto a
databound drop target. The Create context menu appears.
3.
Figure 1913
Create Attachments
Implementing Attachments
19-17
Creating Attachments
Click OK. Do not make any changes on the Edit Taskflow Binding dialog.
Selecting Attachments Field or Attachments Table will add the Attachments
Component to the page. The mode will be set automatically to link or table.
Selecting Attachments Carousel will add the Attachments Carousel Component to
the page. Either component will be bound to the Detail Data Collection.
When using attachments in link mode, the Attachment component must be displayed
inside a panelLabelAndMessage component and a partialTrigger must be added as
an attribute. You must then add the IDs for the appropriate events on the page to the
partialTriggers that cause the underlying business object record to change, which in
turn requires the Attachments data to change. For example, the navigation buttons
Next and Previous as shown here:
Example 195
<af:panelLabelAndMessage label="Attachment"
partialTriggers="btnNext btnPrevious">
<fnd:attachment mode="link" repositoryMode="true"
attachmentModel="#{bindings.Attachments1}/>
</af:panelLabelAndMessage>
<fnd:AttachmentsCarousel id="ac1"
attachmentModel="#{bindings.AttachmentsIterator}"/>
Creating Attachments
Notes:
3.
4.
Click OK. Do not make any changes on the Edit Taskflow Binding dialog.
An Applications Table is created with an Attachments column located in the
rightmost position.
5.
3.
Click OK. Do not make any changes on the Edit Taskflow Binding dialog.
4.
Example 199
<af:column sortable="false"
headerText="#{applcoreBundle.ATTACHMENTS_COLUMN_HEADER}"
width="200">
<fnd:attachment mode="columnLink"
attachmentModel="#{bindings['Attachments1']}"
columnModel="#{row.attachments}"/>
columnLinkTableModel="#{bindings.AuEmployee1.collectionModel}"/>
</af:column>
Implementing Attachments
19-19
Creating Attachments
2.
Go to the Structure pane and select the item node representing the JSPX page.
3.
Go to the Property Inspector > Advanced Properties > Page tab and set the Form
Uses Upload property to true.
4.
2.
Click on the link to the Page Definition File, which is located at the top of the
page.
3.
4.
5.
Note:
When a user chooses to attach a repository file or folder, they are presented with the
Document Picker dialog from which they can select one or more repository files or
folders. After a repository file or folder has been attached, the type is displayed as
either File or Folder.
The ability for a user to add, update, view, or delete an attachment is
programmatically controlled using the addAllowed, updateAllowed, viewAllowed,
deleteAllowed, and ReadOnly attributes on the Attachment component.
The ability to control what type of attachments can be added in the Attachments UI is
controlled by the following attributes on the Attachment component:
fileTypeEnabled, textTypeEnabled, urlTypeEnabled, and attachFolderAllowed.
The type of attachment that is used determines how the attachment is displayed when
the user clicks the attachment link. The browser and client configuration determines
what desktop application is used to display the attachment.
Repository files are viewed in the same way as desktop files. However, if you click the
link in the File Name/URL column in the Attachments table for an attached folder, a
browser window/tab opens and displays the list of files and folders within the
attached folder.
19-21
To configure your data model to display attachments for two or more business
objects:
1. Open the view object for your business object.
2.
Navigate to the Attributes tab. Add a new transient attribute for the secondary
business object for which you want to display attachments. Use the existing
AttachmentEntityName attribute as an example, naming the new attribute
AttachmentEntityName1.
3.
Change the Expression value in the View Attribute screen to be the Attachment
ENTITY_NAME as defined for your business object in the FND_DOCUMENT_ENTITIES
and FND_DOCUMENT_ENTITIES_TL tables
4.
Repeat Steps 2 and 3 for any subsequent business objects for which you want to
show attachments. Make sure that you modify the attribute name and expression
value for each.
Close the view object.
5.
6.
Navigate to the Relationship tab and click the Attributes Edit icon.
b.
Select the foreign key reference column in your view object from the Source
Attribute list and then select the corresponding PknValue column in the
Attachments view object (starting with Pk1Vlaue) from the Destination
Attribute list. Click Add to add this pair.
Repeat this for each column that makes up the foreign key, which identifies
your secondary business object.
c.
d.
Navigate to the Query tab, and click the Source Edit icon.
e.
Navigate to the Source view for the view link and edit the source XML to include
the extra attributes in the Destination array. Make sure you include attributes for
each additional business object for which you want to display attachments.
The AttrArray for the destEnd ViewLinkDefEnd must map to the AttrArray for
the sourceEnd ViewLinkDefEnd.
The design time code inserts an array of unique items where the runtime code
needs a matching item list, as shown in Example 1912. (The added items are in
bold).
Example 1912 Source and Destination Attribute Arrays
<ViewLinkDefEnd
Name="sourceEnd"
Cardinality="1"
Owner="oracle.apps.model.FndDemoDeptEmpVO"
Source="true">
<AttrArray Name="Attributes">
<Item Value="oracle.apps.model.FndDemoDeptEmpVO.DeptNum"/>
<Item Value="oracle.apps.model.FndDemoDeptEmpVO.AttachmentEntityName"/>
<Item Value="oracle.apps.model.FndDemoDeptEmpVO.AttachmentEntityName1"/>
<Item Value="oracle.apps.model.FndDemoDeptEmpVO.EmployeeId"/>
</AttrArray>
</ViewLinkDefEnd>
<ViewLinkDefEnd
Name="destEnd"
Cardinality="-1"
Owner="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO">
<AttrArray Name="Attributes">
<Item
Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.Pk1Value"/>
<Item
Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.EntityName"
/>
<Item
Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.EntityName"
/>
<Item
Value="oracle.apps.fnd.applcore.attachments.uiModel.view.AttachmentsVO.Pk1Value"/>
</AttrArray>
8.
Navigate back to the General tab and expand the Custom Properties section.
Modify the value of the OAF_ATTACHMENT_CATEGORY custom property to control the
attachments that are displayed in your page, based on category and to control the
Category droplist values.
Note:
9.
3.
Set the actionEntity property to the ENTITY_NAME of the primary business object.
By setting this property, you are allowing users to update and delete attachments
belonging to the primary business object whilst disabling the ability for users to
Implementing Attachments
19-23
update and delete attachments for the secondary and all subsequent business
objects.
mode - This property drives the UI that is rendered. It is automatically set when
you add attachments to your page and should not be changed. Mode values
include link, table, and columnLink.
repositoryMode - This property indicates whether a user is aware of the content
repository. A more advanced UI is displayed to users who are aware of the content
repository (repositoryMode=true) allowing them to perform advanced functions
such as selecting repository files and folders to attach to the business object, and
checking in and checking out attached files.
Table 191
Property
Description
Default Value
Mode
RepositoryMode
False
Not used.
N/A
AttachLatestVersion
Not used.
N/A
ApprovalEnabled
False
DeleteMessage
Rows
10
Description
Default Value
FileTypeEnabled
True
True
UrlTypeEnabled
True
NumAttachmentsDisplayed
AddAllowed
True
True
UpdateAllowed
Implementing Attachments
19-25
Description
Default Value
UpdateEnabled
True
True
True
True
True
Rendered
True
Auto-generated
Visible
True
Label
Attachment
Description
Default Value
AutoHeightRows
10
ContentDelivery
RowBandingInterval
ColumnBandingInterval
ShowCategory
UpdateCategoryList
SecondaryToolbarRendered
True
False
attachmentsTrigger
enableOrdering
False
Implementing Attachments
19-27
Description
Default Value
enablePrimaryCategory
UseResetActionListener
fieldRenderOff
Select the Page Bindings tab. In the Bindings list, select the Attachment
Model.
2.
Click on the link at the top of the page for the Page Definition File.
At the bottom of the selection, add two new attributes so that the end of
the entry looks like this:
<Item Value="SeqNum"/>
<Item Value="PrimaryCategoryFlag"/>
</AttrNames>
</nodeDefinition>
Note:
Following is a list of some of the properties that are supported by the Attachments
Carousel component. Refer to Table 192 for basic descriptions of why and how each
property is used.
The most important property to take note of is:
repositoryMode - This property indicates whether a user is aware of the content
repository. A more advanced UI is displayed to users who are aware of the content
repository (repositoryMode=true) allowing them to perform advanced functions such
as selecting repository files and folders to attach to the business object, and checking in
and checking out attached files.
Table 192
Property
Description
Default Value
id
Auto-generated
Rendered
False
True
False
True
textTypeEnabled
True
True
center
orientation
horizontal
valign
middle
Implementing Attachments
19-29
Description
Default Value
attachmentDetailsRendered
False
True
True
False
approvalEnabled
False
attachFolderAllowed
N/A
attachLatestVersion
N/A
updateCategoryList
attachmentsTrigger
autoHeightRows
10
Description
columnBandingInterval
contentDelivery
defaultCategory
label
Attachment
rows
10
True
showCategory
Default Value
auxiliaryPopOut
Implementing Attachments
19-31
Description
auxiliaryScale
controlArea
full
String. Valid Values: full, small,
compact, none; specifies how the area
where the user spins the carousel is
presented. The "full" option lets a user
spin through carousel items one at a
time, jump to a specific item, or drag
the slider thumb to continuously spin
the carousel until the mouse is let go.
The "small" option lets a user click the
next and previous buttons to spin
through carousel items one at a time.
The "compact" option is similar to
"small" but omits details such as the "x
of y" progress information. The "none"
option provides no control area at all.
displayItems
circular
String. Valid Values: circular,
oneByOne; the current carousel item
will always be shown but you can use
this attribute to specify how the
auxiliary carousel items are displayed.
Use "circular" if you want the auxiliary
items displayed near the current item
in a scaled down pattern with as many
items shown as will fit. Use
"oneByOne" if you only want the
current item shown.
emptyText
ReadOnly
Default Value
False
Description
Default Value
addAllowed
True
True
updateEnabled
True
True
True
Implementing Attachments
19-33
Description
Default Value
viewAllowed
True
True
True
carouselContentDelivery
lazy
Valid Values: immediate, lazy;
whether data should be fetched when
the component is rendered initially.
When contentDelivery is "immediate",
data is fetched and inlined into the
component chrome. If contentDelivery
is "lazy", data will be fetched and
delivered to the client during a
subsequent request.
fetchSize
25
carouselImmediate
False
Description
Default Value
carouselRows
25
RowBandingInterval
attachmentModel
CollectionModel
deleteMessage
Description
useResetActionListener
False
inlineStyle
String
width:950px
carouselStyleClass
carouselInlineStyle
width:500.0px;
String. The CSS styles to use for this
component. This is intended for basic
height:300.0px;
style changes. The inlineStyle is a set
of CSS styles that are applied to the
root DOM element of the component.
If the inlineStyle's CSS properties do
not affect the DOM element you want
affected, then you will have to create a
skin and use the skinning keys which
are meant to target particular DOM
elements, like ::label or ::icon-style.
carouselItemInlineStyle
width:200px;
String. the CSS styles to use for this
component. This is intended for basic
width:200px;
style changes. The inlineStyle is a set
of CSS styles that are applied to the
root DOM element of the component.
If the inlineStyle's CSS properties do
not affect the DOM element you want
affected, then you will have to create a
skin and use the skinning keys which
are meant to target particular DOM
elements, like ::label or ::icon-style.
Implementing Attachments
19-35
Description
Default Value
UseResetActionListener
fieldRenderOff
If the Application or Project has not already been configured to use Attachments,
follow the instructions in "Before you begin:" in Section 19.3, "Creating
Attachments."
resulting in a dead link, support for this variation of the URL type was created. To the
end-user, this link will still appear as a URL. Internally, however, this Attachment will
be created with a different Attachment type, TMURI.
There currently are no methods for attaching files that are already uploaded to the
content server (Repository File or Folder). How a required file would be located and
then added must still be determined. If the required file is already attached to another
record, use the copyAttachments method to attach the file to the required record.
Table 193 summarizes the available methods for Attachments APIs.
Table 193
Class
Method
void
AttachmentsVORowImpl
void
attachManagedUrl(AttachmentsVORowImpl row,
java.lang.String entAppShortName, java.net.URI uri)
For the given attachment row, it populates the attributes for the
attachment type AttachmentsConstants.TMURI_TYPE.
AttachmentsVORowImpl
attachManagedUrl(java.lang.String entAppShortName,
java.net.URI uri)
Creates a new row from the internal attachments view object
and calls attachManagedUrl(AttachmentsVORowImpl row,
String entAppShortName, URI uri) to populate.
void
AttachmentsVORowImpl
attachText(java.lang.String text)
Creates a new row from the internal attachments view object
and populates the attributes to attach text.
void
AttachmentsVORowImpl
attachUrl(java.lang.String url)
Creates a new row from the internal attachments view object
and populates the attributes to attach URL.
void
setAttachmentSequence(AttachmentsVORowImpl row)
Sets the sequence number for the row that is passed in. Should
be used where end user ordering has been enabled.
When end-user ordering has been enabled in the view for the attachment component,
any programmatically created rows for the entity must have their sequence value set
Implementing Attachments
19-37
The second option is to allow the method to create the Attachment row at the same
time, as shown in Example 1915.
Example 1915 Code for Creating a New Attachment Row: Option 2
// Add Managed Link
newAttachment =
attachmentServiceAMImpl.attachTopologyManagedUrl(textEntAppShortName, textURI);
newAttachment.setEntityName("FND_DEMO_DEPT");
newAttachment.setPk1Value(departmentNumber);
// Set the Category Value
newAttachment.setCategoryName("MISC");
If you use the second option, it is essential for the Entity and Primary Key values to be
set programmatically as well. Getting any of these values wrong may result in the
Attachment being lost or assigned to the wrong record. While the second type looks
like less work it would be a better practice to use the first approach for creating new
Attachments.
Warning: Assigning an Attachment to the wrong record could allow
an end-user to view a document they would not normally be able to
view.
It will also be necessary to set the Category value for the new row before committing
the transaction as shown in both examples. The value expected is the CATEGORY_NAME
from the FND_DOCUMENT_CATEGORIES table. Since the value is not validated, use the
following method to ensure that you are providing a category value that is mapped to
your Document Entity Name:
newAttachment.setCategoryName("MISC");
Class
Method
java.io.InputStream
getAttachmentInputStream(AttachmentsVORowImpl row)
This method is deprecated. Use
getInputStream(AttachmentsVORowImpl row) instead.
java.io.InputStream
getInputStream(AttachmentsVORowImpl row)
Retrieve the attachment content for the supplied attachment row
as a stream.
Unlike getAttachmentInputStream(AttachmentsVORowImpl
row), which embedded an error message in InputStream, this
method throws an exception if there is an error downloading the
data from the content server.
java.io.OutputStream
getAttachmentStream(AttachmentsVORowImpl row)
Retrieve the attachment content for the supplied attachment row
as a stream.
java.lang.String
getAttachmentUrl(AttachmentsVORowImpl row)
Retrieve URL for the attachment content for the supplied
attachment.
19-39
Note:
Table 195
Class
AttachmentsVORowImpl
Method
copyAttachments(java.util.List<AttachmentsVORowImpl>
java.util.List<Attachmen attachments, java.lang.String entityName,
tsVORowImpl>
java.lang.String pk1Value, java.lang.String pk2Value,
java.lang.String pk3Value, java.lang.String pk4Value,
java.lang.String pk5Value)
Creates copies of the supplied attachment rows assigning them
to the entity values as provided.
duplicateAttachments(java.util.List<AttachmentsVORowImp
java.util.List<Attachmen l> attachments, java.lang.String entityName,
tsVORowImpl>
java.lang.String pk1Value, java.lang.String pk2Value,
java.lang.String pk3Value, java.lang.String pk4Value,
java.lang.String pk5Value)
Creates copies of the supplied attachment rows assigning them
to the entity values as provided. Content on the content server is
also copied.
Class
Method
void
Table 197
Method
PL/SQL Implementation
attachURL
PROCEDURE ATTACH_URL (
X_ENTITY_NAME in VARCHAR2,
X_PK1_VALUE in VARCHAR2,
X_PK2_VALUE in VARCHAR2 DEFAULT NULL,
X_PK3_VALUE in VARCHAR2 DEFAULT NULL,
X_PK4_VALUE in VARCHAR2 DEFAULT NULL,
X_PK5_VALUE in VARCHAR2 DEFAULT NULL,
X_CATEGORY_NAME in VARCHAR2,
X_URL in VARCHAR2,
X_TITLE in VARCHAR2 DEFAULT NULL,
X_DESCRIPTION in VARCHAR2 DEFAULT NULL );
Updates the supplied attachments row with the information to attach a static URL.
copyAttachments
PROCEDURE COPY_ATTACHMENTS (
X_SRC_ENTITY_NAME in VARCHAR2,
X_SRC_PK1_VALUE in VARCHAR2,
X_SRC_PK2_VALUE in VARCHAR2 DEFAULT NULL,
X_SRC_PK3_VALUE in VARCHAR2 DEFAULT NULL,
X_SRC_PK4_VALUE in VARCHAR2 DEFAULT NULL,
X_SRC_PK5_VALUE in VARCHAR2 DEFAULT NULL,
X_SRC_CATEGORY_NAME in VARCHAR2 DEFAULT NULL,
X_DST_ENTITY_NAME in VARCHAR2,
X_DST_PK1_VALUE in VARCHAR2,
X_DST_PK2_VALUE in VARCHAR2 DEFAULT NULL,
X_DST_PK3_VALUE in VARCHAR2 DEFAULT NULL,
X_DST_PK4_VALUE in VARCHAR2 DEFAULT NULL,
X_DST_PK5_VALUE in VARCHAR2 DEFAULT NULL,
X_DST_CATEGORY_NAME in VARCHAR2 DEFAULT NULL );
Creates copies of the supplied attachment rows assigning them to the entity values as
provided. This utility does not copy the content on the server; it creates a copy of the
reference to the content.
Implementing Attachments
19-41
PL/SQL Implementation
copyAttachment
PROCEDURE COPY_ATTACHMENT (
X_ATTACHED_DOCUMENT_ID in VARCHAR2,
X_ENTITY_NAME in VARCHAR2,
X_PK1_VALUE in VARCHAR2,
X_PK2_VALUE in VARCHAR2 DEFAULT NULL,
X_PK3_VALUE in VARCHAR2 DEFAULT NULL,
X_PK4_VALUE in VARCHAR2 DEFAULT NULL,
X_PK5_VALUE in VARCHAR2 DEFAULT NULL,
X_CATEGORY_NAME in VARCHAR2 DEFAULT NULL );
Creates a copy of the supplied attachment row. This utility does not copy the content on the
server; it creates a copy of the reference to the content.
deleteAttachment
PROCEDURE DELETE_ATTACHMENT (
X_ATTACHED_DOCUMENT_ID in FND_ATTACHED_DOCUMENTS.ATTACHED_DOCUMENT_ID%TYPE );
Deletes an attachment from the database for the X_ATTACHMENT_DOCUMENT_ID. This does not
delete the file in the content repository.
deleteAttachments
PROCEDURE DELETE_ATTACHMENTS (
X_ENTITY_NAME in FND_ATTACHED_DOCUMENTS.ENTITY_NAME%TYPE,
X_PK1_VALUE in FND_ATTACHED_DOCUMENTS.PK1_VALUE%TYPE,
X_PK2_VALUE in FND_ATTACHED_DOCUMENTS.PK2_VALUE%TYPE DEFAULT
X_PK3_VALUE in FND_ATTACHED_DOCUMENTS.PK3_VALUE%TYPE DEFAULT
X_PK4_VALUE in FND_ATTACHED_DOCUMENTS.PK4_VALUE%TYPE DEFAULT
X_PK5_VALUE in FND_ATTACHED_DOCUMENTS.PK5_VALUE%TYPE DEFAULT
NULL,
NULL,
NULL,
NULL );
Deletes all the attachments from the database for the specified parent record. This does not
delete any files in the content repository.
Note:
A debugging utility is also included. When enabled, messages are written to the
console. This feature is not enabled by default. At runtime the same messages will be
written as log messages if logging is set to FINEST for the
applcore.db.plsql.attachments.FND_ATTACHMENTS module.
To begin writing log messages to the console, use the PROCEDURE START_DEBUG
command.
To stop writing log messages to the console, use the PROCEDURE STOP_DEBUG command.
Example 1917 displays sample code for implementing Attachments with PL/SQL
with debugging enabled.
Example 1917 Implementing Attachments with PL/SQL
SET SERVEROUTPUT ON;
DECLARE
BAD_ENTITY_NAME_EXCEPTION EXCEPTION;
PRAGMA EXCEPTION_INIT(BAD_ENTITY_NAME_EXCEPTION, -20001);
P_ENTITY_NAME VARCHAR2(40) := 'FND_DEMO_DEPT1';
P_PK1_VALUE
VARCHAR2(150) := '10';
BEGIN
BEGIN
FND_ATTACHMENTS.START_DEBUG;
FND_ATTACHMENTS.ATTACH_URL (P_ENTITY_NAME,
P_PK1_VALUE, NULL, NULL, NULL, NULL,
'MISC',
'http://www.oracle.com', 'Oracle Corportation',
NULL);
FND_ATTACHMENTS.END_DEBUG;
EXCEPTION
WHEN BAD_ENTITY_NAME_EXCEPTION THEN
DBMS_OUTPUT.PUT_LINE ('The entity name supplied, ' || P_ENTITY_NAME || ',
is not a registered document entity.');
END;
END;
Custom Actions
Approvals
19.8.2 Approvals
Approval functions are added to the Attachments component using the Custom
Actions feature, which is documented in the previous section of this chapter.
The approvalEnabled property on the Attachments component can be used to control
whether the Status column (from the FND_DOCUMENTS_TL table) is displayed in the
Attachments Table. This column indicates the status of the attachment relationship
between the business object and the file, not the status of the file in the content
repository.
Product teams are responsible for programmatically setting the status as necessary, but
are required to set this value using a lookup code provided in the FND_ATTACHMENT_
STATUSES lookup. The following table has the full list of valid values found in this
lookup table. (Null is also a valid value):
Implementing Attachments
19-43
Integrating Attachments Task Flows into Oracle Fusion Functional Setup Manager
Lookup Code
Meaning
APPROVED
Approved
REJECTED
Rejected
REVIEWED
Reviewed
SUBMITTED_FOR_APPROVAL
SUBMITTED_FOR_REVIEW
UNAPPROVED
Unapproved
Note:
Parameters
Passed
Behavior
Comments
Manage
Attachment
Entities
/WEB-INF/oracle/ap [moduleType]
ps/fnd/applcore/attac [moduleKey]
hments/publicUi/flow [pageTitle]
/ManageAttachmentE
ntities.xml#ManageAtt
achmentEntities
Search and
edit
Attachment
entities.
NA
Manage
Attachment
Categories
/WEB-INF/oracle/ap [moduleType]
ps/fnd/applcore/attac [moduleKey]
hments/publicUi/flow [pageTitle]
/ManageAttachmentC
ategories.xml#Manage
AttachmentCategories
Search and
edit
Attachment
categories.
NA
For more information about task flows, see Oracle Fusion Applications Common
Implementation Guide.
Securing Attachments
Table 199
Action
FUNCTION_NAME
USER_FUNCTION_NAME
FND_READ_APPLICATION_
ATTACHMENT_DATA
FND_DELETE_APPLICATION_
ATTACHMENT_DATA
Define the conditions (object instance sets) that identify the category or set of
categories you are securing. The CATEGORY_ID, CATEGORY_NAME, or USER_NAME
condition items can be used in your condition definitions.
2.
Ensure the Roles to which you want to assign data security have been created in
Oracle Platform Security Services (OPSS).
3.
Grant the actions that you will allow a user to perform on the set of Categories
identified by your condition in Step 2. You can grant one or more of the seeded
actions: read, update, and delete (see Table 199) to a role, but a role must be
assigned the read action to view attachments from the Attachments UI.
Implementing Attachments
19-45
(Optional) The "Applications Common Reference Data Review Duty" role (GUID:
7BC1484030A9EE43499AB0EBBE17B104) provides users with read, update, and
delete actions for all attachments that are assigned the "Miscellaneous" category.
To setup your own category data security for the "Miscellaneous" category, you
will need to follow Steps 1 to 4.
The following condition (object instance set) is seeded with Oracle Fusion
attachments and can be reused by using the "Miscellaneous" category for your
product:
5.
INSTANCE_SET_NAME: FNDDOCUMENTCATEGORIESFND214
Using the Manage Attachment Entities Setup UI, "switch on" category data
security for your attachment entity.
For more information, see Chapter 50, "Implementing Oracle Fusion Data Security."
The Shared column is only shown in the Attachments table when the repositoryMode
property is set to true. The default state for this option is Not Shared for both Text and
File type attachments.
The option is not available for all URL and Folder type
attachments, as shown in Figure 1914. By default, all Folder type
attachments are shared, and all URL type attachments are not shared.
Therefore, the check box is hidden because these default values cannot
be changed by the user.
Note:
All repository File or Folder attachments are shared by default. This is because only
shared files are visible in the Document Picker, which is used to select the Repository
Files or Folders.
If the user hovers the mouse pointer over the Shared check box, the following hint
displays: Checking this box will make this file available to other users.
If the user attempts to change a File type attachment from Shared to Not Shared, the
system checks to see if the file is attached to any other business object instances. If the
file is attached to other business object instances, the following message is displayed
and the file attachment remains shared: This change cannot be made as this file is attached
to other business objects.
Implementing Attachments
19-47
Icon
Function
File
Property
Check Out
versioncheckout_ena.png
repositoryMode = true
Check In
versioncheckin_ena.png
repositoryMode = true
versionrollback_ena.png
repositoryMode = true
The Category, Title, and Description columns in the Attachments table are
updateable.
The title and description values are kept in sync with the corresponding values
stored in the Content Server. When a user updates the title or description, the
values are updated in the Content server when the changes are saved.
If repositoryMode = true:
The Check In, Check Out, and Cancel Check Out buttons are rendered in the
Attachments table toolbar, as shown in Figure 1915.
These buttons are enabled or disabled based on the type of attachment and the
checked out status of File and Text type attachments.
Figure 1915
If repositoryMode = false:
The Check In, Check Out, and Cancel Check Out buttons are not rendered in the
Attachments table toolbar.
Figure 1916
updateAllowed = false:
None of the fields in the table are updateable when this property is set to false.
If repositoryMode = true:
The Check In, Check Out, and Cancel Check Out buttons are rendered and
disabled in the Attachments Table toolbar.
If repositoryMode = false:
The Check In, Check Out, and Cancel Check Out buttons are not rendered in the
Attachments table toolbar.
19.11.2.2 Determining the Checked Out Status of File and Text-Type Attachments
The Checked Out By column indicates the checked-out status in the Attachments table.
this column is only rendered when the repositoryMode is set to true.
This column is always empty for URL and Folder type attachments.
For File and Text attachments, this column is either:
Implementing Attachments
19-49
URL attachments
The following rules apply regardless of the repositoryMode value:
The Check Out, Check In, and Cancel Check Out functions are always disabled.
Folder attachments
If repostoryMode = true:
Go to your local file system and make the necessary updates to this file.
3.
Return to the Attachments table and highlight the checked out file. Click the
Check In button located on the toolbar to open the Check In File dialog, as shown
in Figure 1917.
Figure 1917
4.
Click Browse to browse your local file system. Select the updated file that you
want to upload.
5.
6.
Implementing Attachments
19-51
20
Organizing Hierarchical Data with Tree
Structures
20
This chapter describes how to create, edit, and delete tree structures, trees, and tree
versions, and how to develop applications using trees.
The chapter includes the following sections:
Introduction to Trees
Open metadata that can be read by any application that needs to use
tree-management hierarchies. This does the following:
Tree structures that capture the business rules the data must adhere to.
ADF Business Components view objects that are used as data sources, eliminating the
need to build new types of data sources.
Hierarchical relationships between entities that are external to the entity itself, allowing
multiple hierarchical views to be implemented for the same set of entities. Each of
these hierarchies can be used to implement a different business function.
Data flattening that improves query performance against the hierarchical data,
especially for hierarchical queries such as roll-up queries.
Business events that can be consumed by any application requiring additional
processing on specific tree operations.
Tree and node-level access control that eliminates the need for product teams to write
their own access-control code.
Well-defined APIs available for metadata and data that make it easy for the Oracle
Fusion Upgrade Office to write migration tools for existing hierarchies in
E-Business Suite, PeopleSoft, and Siebel.
As a developer, you will work mostly with tree structures. The task of working with
trees and tree versions normally will fall to customers. However, since you probably
also will be required to work with trees and tree versions, both types of tasks are
described in this chapter.
A node is a parent of another node if it is one step higher in the hierarchy and
closer to the root node.
Sibling nodes share the same parent node.
For example, in the following picture, XYZ Corp. is the parent of Marketing and
Finance, which are its children. Accounts Receivable and Accounts Payable are
siblings, and are the children of Finance.
Introduction to Trees
Term
Description
Depth
The depth of a node is the length of the path from the root to the node. The root
node is at depth zero.
Label
Allows for a storage of "tags" that can be used on each tree node in a tree. There are
three labeling schemes:
Level - Labels that are automatically assigned based on the data source that the
tree node belongs to. A level label points to a specific data source.
Group - Labels that a user can assign to tree nodes arbitrarily.
Depth - Labels that are automatically assigned based on the depth of the tree
node within the tree. No manual assignment is performed. Note that in an
unbalanced hierarchy, a level may not be equal to depth.
Labels can be stored in any table and the label data source is registered with the tree
structure.
Tree label
When a labeling scheme is used for trees, the selected labels are stored in the tree
label entity and each tree node references a tree label. See "Label."
Node
A logical term that refers to the actual data, whatever that may be. Technically, the
node may be stored either in a product-specific table or in an entity that has been
established by the Tree Management solution as the default storage mechanism.
However, since all data in Oracle Applications usually already has a storage home,
only customers should store the node in an entity.
Tree node
Description
A tree node has a node type. Node types can be any one of the following:
Tree levels
Single - Indicates that the node is a value by itself. For example, a tree node for
Employee "Larry Ellison" or Employee "Steve Jobs" in an employee hierarchy.
Range - Indicates that the node represents a range of values and possibly could
have many children. For example, a tree node representing account numbers
10000 to 99999.
Referenced Tree - Indicates that the tree node is actually another tree whose
nodes are not physically stored in this tree. For example, a geographic hierarchy
for the United States can be referenced in a World geographic hierarchy.
Provide a way to organize tree nodes. In most trees, all nodes at the same level
represent the same kind of information. For example, in a tree that reflects the
organizational hierarchy, all division nodes appear on one level and all department
nodes on another. Similarly, in a tree that organizes a user's product catalog, the
nodes representing individual products might appear on one level and the nodes
representing product lines on the next higher level.
When levels are not used, the nodes in the tree have no real hierarchy or reporting
structure but do form a logical summarization structure. Strictly enforced levels
mean that the named levels describe each node's position in the tree. This is natural
for most hierarchies.
Loosely enforced levels mean that the nodes at the same visual level of indentation
do not all represent the same kind of information, or nodes representing the same
kind of information appear at multiple levels. With loosely enforced levels, users
assign a level to each node individually; the level is not tied to a particular visual
position.
Tree access
The set of rules that control access to a particular node (and its subtree) within a
given tree version.
Effective dates
A value that determines which reference data set will be used for each reference data
object. Business units, regulatory regions, and reference data sets all can determine
which reference data sets are valid for the creation of a transaction or reference data
object.
Audit
A process that runs a series of tests against tree metadata and tree data to validate its
integrity.
Add a taskflow entry in the ADF menu as a node with the following properties:
id - tree_<jspx file>
3.
Repeat Steps 1 and 2 to create a second itemNode with the following properties:
id - tree_<jspx file>
4.
taskFlowId /WEB-INF/oracle/apps/fnd/applcore/trees/ui/taskflow/TreeSummary.xml
#TreeSummary
Repeat Steps 1 and 2 to create a third itemNode with the following properties:
id - tree_<jspx file>
5.
taskFlowId /WEB-INF/oracle/apps/fnd/applcore/trees/ui/taskflow/FndLabelSummary
.xml#FndLabelSummary
Ensure you have an itemNode for defaultRegional. If you do not, define one with
the following properties:
id - __<jspx file>_itemNode__FndTasksList
Note:
label - #{applcoreBundle.TASKS}
6.
taskFlowId /WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/Ta
sksList.xml#TasksList
Disclosed - true
7.
Click the Tree Structures link to open the Tree Structure summary page.
Click the Trees and Tree Versions link to open the Trees summary page.
Click the Central Labels link to open the Central Labels summary page.
Click the Trees Picker link to open the Trees Picker application.
The following picture shows the launch page with all applications open, and the
Tree Structure application's summary page displayed.
A flag named PROTECTED_FLAG is available for the tree structures. By default, this flag
is set to N. If you set this flag to Y, you cannot modify the tree structure. When you
want to protect a tree structure from being updated, you can set this flag to Yes. A
protected tree structure can be modified or deleted only by the SEED_DATA_FROM_
APPLICATION user.
You can create an exclusion list and tree structures to that list. Any tree structure that is
a part of the exclusion list will not be considered for export. The tree structures which
have been excluded can be populated by writing an SQL statement.
column of an ADF Faces Tree or ADF Faces TreeTable, the Application property
HierarchyDisplay is set to true.
Figure 204 View Object Attributes: HierarchyDisplay Property
Note:
The parameters will be applied when performing node operations, and the display of
the nodes in the hierarchy, for any tree version under that data source. Data source
parameters also provide an additional level of filtering for different tree structures.
Tree management supports three data source parameter types:
VIEW_CRITERIA - Used to capture the view criteria name, which will be applied
to the data source view object
BOUND_VALUE - Used to capture any bound value, which will be used as part of
the view criteria condition
VARIABLE - Used to capture and bind variable that is being used by the data
source view object, particularly for WHERE clause support
Parameter Syntax
Attribute
Syntax
Tree Structure
Tree
Tree Version
Note:
20.3.2.1.2 Basic Use Cases and Their Settings The following are examples of use cases
and settings that you can implement using the parameter infrastructure for tree
structure data sources.
Data source having a view criteria defined with a bind variable:
Figure 205 View Object Setup Wizard
20-11
Data source has a view criteria defined with a bind variable for special
parameters:
Figure 209 View Object Setup Wizard (View Criteria)
Figure 2010
Data source has a WHERE clause using a bind variable for special parameters:
Figure 2011
20-13
Figure 2012
2.
Code
Name
Status
Click Search.
All tree structures matching your search criteria appear in the Results area of the
page.
Click Advanced to perform an advanced search by specifying additional options
for search. You also can save your search criteria for future use.
Search Field
Click the down arrow to display a dropdown list that contains the available values for
that field. You can select from the list, or search for other values. For example, the
following picture shows the dropdown list that displays when you click the down
arrow associated with the Application search field found on the Create Tree Structure:
Specify Definition page.
Figure 2014
From each search field dropdown list, you can do one of the following:
Click the Search link to search for a value that does not exist in the list.
If you select a value from the list, the dropdown list closes and that value appears in
the search field.
If you click the Search link, a search-and-select window similar to the one shown in
the following picture opens:
Figure 2015
Search-and-Select Window
You now can search for a value and then click OK to select it.
20-15
2.
3.
4.
Enter the name of an appropriate application, or click the down arrow to select or
search for one.
5.
Enter a description.
6.
Enter the name of an appropriate tree node table, or click the down arrow to select
or search for one.
If you enter the name of a custom tree node table or select a tree node table other
than the FND_TREE_NODE default, the page re-displays with a new (optional) field
asking you to enter a view object definition name for that custom tree node table.
This field is shown in the following picture.
Figure 2017
7.
8.
9.
Open - indicates that the tree will be associated with all Set IDs
Set ID - indicates that the tree will be associated with a specific Set ID.
10. Select Allow Multiple Active Tree Versions to allow two or more tree versions to
The Create Tree Structure: Data Sources page, shown in the following picture,
opens.
20-17
Figure 2018
Group based - Specifies a label that the user can assign arbitrarily.
following picture, "ICs" does not have any children, making its rooted path
shorter than all the others in the hierarchy.
Figure 2020
Figure 2021
Allow Skip-Level Nodes (for Labeling Schemes Level based, Depth based, or
Group based only) - Specifies whether a hierarchy can have two nodes at the
same level with parent nodes at different levels. In Figure 2021, Washington,
DC, does not have a node at the State level.
The Add Data Source window, shown in the following picture opens.
20-19
Figure 2022
Maximum depth specifies how many levels are allowed. For example, in
Project[max depth=2] > Task[max depth=infinite], one project, one sub-project, and an
infinite number of tasks are allowed.
20. Enter the name of the label data source (for Level based, Depth based, or Group
Use non defined primary key columns - indicates that you can specify other
attributes as primary key columns. If not selected, existing primary keys
defined as primary key columns for a data source view object will be used.
If selected, the additional fields shown in the following picture display.
Figure 2024
Allow use as leaves - indicates that data from the data source can form a leaf
Allow duplicates - indicates that a data item can exist multiple times in the
same hierarchy. For example, in an "Item" hierarchy for an automobile, a
particular bolt may appear multiple times in the hierarchy.
Use as free node - indicates that this node can be used as a free node.
Use all values - Specifies that all available nodes must be included in the
tree version.
Allow range children - indicates that the hierarchy supports nodes that are a
range of values.
Allow linked foreign key children - indicates that the relationship is external
to Tree Management.
If you select this option, you also can select a View Link Accessor value from
the dropdown list that displays, as shown in the following picture.
Figure 2025
The window now displays data source parameters text-entry fields, as shown in
the following picture.
20-21
Figure 2026
When specified, a parameter applies to every version under that tree. Parameter
values also can be overridden at the tree level. For more information, see
Section 20.3.2, "How to Specify Data Source Parameters."
24. Select Mandatory if the parameter is to be required.
25. Click OK.
The Create Tree Structure: Specify Data Sources page refreshes, displaying the
view object, as shown in the following picture.
Figure 2027
Create Tree Structure: Specify Data Sources Page with View Object
The Create Tree Structure: Specify Performance Options page opens, as shown in
the following picture.
Figure 2028
20-23
27. Enter the name of an appropriate row-flattened table or click the down arrow to
Note:
The Create Tree Structure Confirmation Window opens, as shown in the following
picture.
Figure 2029
Click the Duplicate icon, or choose Duplicate from the Actions dropdown menu.
The Create Tree Structure window opens, as shown in the following picture:
Figure 2030
3.
Enter a new name for the duplicate tree structure if you want to replace the name
that already displays in the field.
4.
Enter a duplicate tree structure code if you want to replace the code that already
displays in the field.
5.
3.
Edit the appropriate data on the Edit Tree Structure: Specify Definition page.
4.
Click Next.
5.
Edit the data on the Edit Tree Structure: Specify Data Sources page.
Select an existing view object and click the Delete icon to delete it.
6.
Click Next.
7.
Edit the appropriate data on the Edit Tree Structure: Specify Performance Options
page.
8.
Click Next.
The Edit Tree Structure: Specify Access Rules page opens.
The Edit Tree Structure: Specify Access Rules page is not yet
implemented.
Note:
20-25
9.
Click Submit.
Figure 2031
3.
Draft
Active
Inactive
Setting a tree structure's status to Active automatically triggers an audit of that tree
structure. See the following section for more information about auditing.
To set the status of a tree structure:
1. Select a tree structure.
See Section 20.3.3, "How to Search for a Tree Structure," if the tree structure is not
in the current Results list.
2.
Choose the appropriate status option from the Actions > Set Status dropdown
menu.
3.
Click OK to close the Warning window. The Warning window appears only when
you want to set the status as Draft or Inactive.
4.
Validator Descriptions
Validator
Checks for...
Restrict by
If the tree structure has
SetID Validator Restrict Tree Node List
of Values Based on
SetID flag set to Yes,
each of its data source
view objects must have
a SetID attribute.
To correct...
Consult the owning developer. If
SetID restriction is desired for this
tree structure, ensure your
developer has included a SetID
attribute on all data sources. If SetID
restriction is not desired, ensure
your developer sets the flag to No.
20-27
Checks for...
Available Data
Sources
Validator
Column
Flattened Table
Name
Validator
A valid "Column
Flattened Table" should
be specified for the tree
structure on the
"Specify Performance
Options" page. It can be
the standard row
flattened table FND_
TREE_NODE_CF, or a
custom table can be
specified.
To correct...
Checks for...
Restrict by
Date Validator
To correct...
Consult the owning developer. If the
date restriction is desired for this
tree structure, ensure your
developer has included an
EffectiveStartDate and
EffectiveEndDate attribute on all
data sources. If the date restriction is
not desired, ensure your developer
sets the flag to No.
Allow Node
Level Security
Validator
Figure 2032
20-29
3.
Search
Create
Duplicate
Edit
Delete
You also can audit trees. For more information, see Section 20.5.9, "How to Audit Trees
and Tree Versions."
2.
Tree Code
Tree Name
Click Search.
All trees matching your search criteria appear in the Results area of the page.
2.
3.
4.
Enter a tree-structure name or click the down arrow to select or search for one.
If the tree structure has data sources and parameters defined for it, the Data Source
Parameters area also displays, allowing you to edit the parameter values at the
tree level.
Note: Parameter values customized at the tree level will override the
default values specified at the tree-structure level.
5.
6.
Enter an image name or click the down arrow to select or search for one.
The image appears in the Preview area.
7.
Click Next.
The Create Tree: Specify Labels page displays. The information that appears on the
page depends on whether or not a labeling scheme has been selected previously.
20-31
Figure 2034
Figure 2035
If the page shown in Figure 2034 opens, click Next and skip to Step 11.
If the page shown in Figure 2035 opens, click Add in the Specify Labels area.
The Select and Add: Labels window opens.
Figure 2036
8.
9.
Select the appropriate available labels and use the arrows to move them back and
forth between the Available Labels and Selected Labels areas.
Click Cancel to abort the operation and return to the top-level Manage Trees
and Tree Versions page.
Click Next to continue to the Create Tree: Specify Access Rules page.
The Create Tree: Specify Access Rules page is not yet
implemented.
Note:
Click Cancel to abort the operation and return to the Manage Trees and Tree
Versions page.
Click Back to return to the previous page.
Click Submit to save the tree without creating a tree version and return to the
top-level Manage Trees and Tree Versions page.
Click the down arrow next to Submit and select Submit and Add Version to
save the tree and begin creating a tree version. For more information, see
Section 20.5.1, "How to Create a Tree Version."
Figure 2037
3.
4.
20-33
5.
3.
Note:
4.
Click Next.
The Edit Tree: Specify Labels page opens. The page that displays depends on
whether or not the tree structure used while creating the tree has a labeling
scheme associated with it.
This procedure assumes that a labeling scheme is present. Skip
to Step 6 if the tree you are editing has no labeling scheme associated
with it.
Note:
5.
Click Add to open the Select and Add: Labels window and add a new label.
For more information, see Section 20.4.2, "How to Create a Tree."
6.
Click Next.
The Edit Tree: Specify Access Rules page opens.
Note:
7.
Click the arrow to the right of Submit and select Submit and Add Version
from the dropdown list to display the Create Tree Version: Specify Definition
page.
Follow the steps in Section 20.5.1, "How to Create a Tree Version," to create a
new tree version.
3.
Search
Create
Duplicate
Edit
Delete
Select the tree to which you want to add a tree version from the list of trees that
appears in the Results list.
20-35
See Section 20.4.1, "How to Search for a Tree" if the tree is not in the current Results
list.
2.
Figure 2038
3.
4.
5.
6.
Enter an effective start date or click on the calendar icon to select one.
7.
Enter an effective end date or click on the calendar icon to select one.
Since tree versions are time based, you must select a start date.
Selecting an end date is optional.
Note:
8.
Click Next.
A tree version with no nodes is created automatically at this point. Procedures for
adding nodes to the tree version are described in the following section.
9.
Figure 2039
20-37
Figure 2040
Note:
Specific Value - Indicates that a data source and label will be specified for the
node. A data source is required for all labeling schemes. A label is required
only if the labeling scheme is set to something other than None. If the labeling
scheme is None, a label is not required.
To configure this page's options, see Section 20.5.2.1, "How to Configure the
Add Tree Node: Specific Values."
Values within a range - Indicates that the node represents a range of values.
This option appears only if Children Definition: Allow range
children has been selected on the Choose Data Source and Parameters
window.
Note:
If you are adding a root node that you want to specify as range-based
node, make sure you have selected Allow Multiple Root Nodes for
the underlying tree structure on the Create Tree Structure: Data
Sources page.
If you select this option, the following window replaces the default Add Tree
Node window.
Figure 2041
To configure this page's options, see Section 20.5.2.2, "How to Configure the
Add Tree Node: Values Within a Range."
Values from referenced hierarchy - Indicates that the node is a referenced tree
node. This option creates a pointer to a tree and node that already exist.
Referenced tree nodes do not require a data source and do not allow labeling.
If you select this option, the following window replaces the default Add Tree
Node window.
Figure 2042
20-39
Each type of node has its own configuration options. In addition, you can add tree
nodes using a custom Search UI, use drag-and-drop to move nodes once they have
been added, and edit existing nodes.
The procedures used to perform these tasks are described in the sections that follow.
2.
3.
Select an option from the Node Navigator. The navigator enables you to access
other available nodes.
4.
5.
Click the single Move arrow to move the node to the Selected Nodes area.
If the tree structure allows multiple root nodes to be selected,
use the single or double Move arrows to move additional nodes.
Note:
6.
Figure 2043
7.
Root Node
Highlight the root node and click Add to add a child node, using the same
steps listed in this section.
Click Create to create a new node in the data source. For more information,
see Section 20.5.3, "How to Create a Record for a Data Source."
8.
9.
20.5.2.2 How to Configure the Add Tree Node: Values Within a Range
The following procedure explains how to configure the Add Tree Node options when
the Values within a range node type has been selected.
To configure values within a range:
This procedure assumes that the Add Tree Node window is open.
1.
2.
3.
20-41
Figure 2044
4.
5.
2.
Note:
3.
Optionally, click the Preview link to ensure you have specified the correct
referenced tree version for the selected referenced tree. Confirm the data and click
OK to close the window.
Figure 2045
4.
The Add Tree Node window closes and the Create Tree Version: Specify Nodes
page refreshes with the referenced-node data.
Figure 2046
Referenced Node
5.
6.
20-43
Figure 2047
Click Edit.
2.
Click Next on the Edit Tree Version: Specify Definition page to skip to the Edit Tree
Version: Specify Nodes page.
3.
Highlight the node you wish to edit and click Edit. The Edit Tree Node window.
Note: The window opens with the default Specific value tree node
type selected. You also can edit the node using the other tree node
types. For more information, see Section 20.5.2, "How to Add Tree
Nodes to a Tree Version."
Figure 2048
4.
Select a data source and click Edit Node. The Edit Node window opens.
Figure 2049
Note:
edited.
5.
Select Export Nodes in the Actions menu. You can also use the Export Nodes
button.
Figure 2050
2.
All the nodes in a tree version are exported to a CSV file as shown below:
20-45
Figure 2051
Figure 2052
2.
The selected nodes of the selected Tree Version are exported to a CSV file as shown
below:
Figure 2053
1.
Select the tree version for which you want to create the record and click Edit.
2.
Click Next to access the Edit Tree Version: Specify Nodes window.
3.
Highlight an existing node and click Create. The Create Tree Node window
displays.
Figure 2054
4.
Select a data source and click Continue. The Create New Record window opens.
The actual name of the window depends on the node being
created.
Note:
Figure 2055
5.
20-47
6.
Figure 2057
3.
4.
5.
Figure 2058
3.
Use the steps in Section 20.5.1, "How to Create a Tree Version" as a guide to editing
the tree version.
add_value_tree_node
This API allows you to add a primary key value based tree node.
Table 204
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_parent_tree_
node_id
VARCHAR2
Mandatory
p_data_source_id
VARCHAR2
Mandatory
p_pk1_value
Value of PK1
VARCHAR2
Mandatory
p_pk2_value
Value of PK2
VARCHAR2
Mandatory
p_pk3_value
Value of PK3
VARCHAR2
Mandatory
p_pk4_value
Value of PK4
VARCHAR2
Mandatory
p_pk5_value
Value of PK5
VARCHAR2
Mandatory
p_tree_label_id
VARCHAR2
Mandatory
20-49
Description
Datatype
Mandatory/Optional
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
x_tree_node_id
VARCHAR2
Optional
add_range_tree_node
This API allows you to add a primary key range based tree node.
Table 205
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_parent_tree_
node_id
VARCHAR2
Mandatory
p_data_source_id
VARCHAR2
Mandatory
p_pk1_start_value
VARCHAR2
Mandatory
p_pk2_start_value
VARCHAR2
Mandatory
p_pk3_start_value
VARCHAR2
Mandatory
p_pk4_start_value
VARCHAR2
Mandatory
p_pk5_start_value
VARCHAR2
Mandatory
p_pk1_end_value
VARCHAR2
Mandatory
p_pk2_end_value
VARCHAR2
Mandatory
p_pk3_end_value
VARCHAR2
Mandatory
p_pk4_end_value
VARCHAR2
Mandatory
p_pk5_end_value
VARCHAR2
Mandatory
p_tree_label_id
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
x_tree_node_id
VARCHAR2
Optional
add_tree_tree_node
This API allows you to add a reference tree-based tree node.
Table 206
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_parent_tree_
node_id
VARCHAR2
Mandatory
p_reference_tree_
code
VARCHAR2
Mandatory
p_reference_tree_
version_id
VARCHAR2
Mandatory
p_tree_label_id
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
x_tree_node_id
VARCHAR2
Optional
delete_tree_node
This API allows you to delete a node. All children of the node that is being deleted
are promoted as children of its parents node.
Table 207
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_tree_node_id
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
update_tree_node
This API allows you to update a tree node.
Table 208
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
20-51
Description
Datatype
Mandatory/Optional
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_tree_node_id
VARCHAR2
Mandatory
p_parent_tree_
node_id
VARCHAR2
Mandatory
VARCHAR2
Mandatory
p_pk1_start_value
VARCHAR2
Mandatory
p_pk2_start_value
VARCHAR2
Mandatory
p_pk3_start_value
VARCHAR2
Mandatory
p_pk4_start_value
VARCHAR2
Mandatory
p_pk5_start_value
VARCHAR2
Mandatory
p_pk1_end_value
VARCHAR2
Mandatory
p_pk2_end_value
VARCHAR2
Mandatory
p_pk3_end_value
VARCHAR2
Mandatory
p_pk4_end_value
VARCHAR2
Mandatory
p_pk5_end_value
VARCHAR2
Mandatory
p_reference_tree_
code
VARCHAR2
Mandatory
p_reference_tree_
version_id
VARCHAR2
Mandatory
p_tree_label_id
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
move_tree_node
This API allows you to move a tree node under a new parent.
Table 209
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_tree_node_id
VARCHAR2
Mandatory
Description
Datatype
Mandatory/Optional
VARCHAR2
Mandatory
p_commit_flag
VARCHAR2
Commit flag
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
move_sub_tree_node
This API allows you to move a given node along with its descendants from one
hierarchy version to another hierarchy or within the same hierarchy tree version.
The destination hierarchy can belong to same tree code or a different tree code
belonging to same tree structure. When move_sub_tree_node operation happens
across the hierarchy or within the same hierarchy, flattening logs will be reset to
ensure that next run of flattening generates accurate flattening data. A tree node id
pointing to details of new subtree in destination hierarchy will be returned.
Table 2010
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_tree_node_id
VARCHAR2
Mandatory
VARCHAR2
Mandatory
p_dest_tree_
version_id
ID of the destination
parent tree version
VARCHAR2
Mandatory
p_dest_tree_code
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
x_tree_node_id
VARCHAR2
Optional
copy_sub_tree_node
This API allows you to copy a given node along with its descendants within the
same hierarchy tree version. The tree version must allow duplicates for the copy
operation to be successful. The destination hierarchy can belong to same tree code
or a different tree code belonging to same tree structure. When copy_sub_tree_
Organizing Hierarchical Data with Tree Structures
20-53
node operation happens, flattening logs will be reset to ensure that next run of
flattening generates accurate flattening data. A tree node id pointing to details of
new subtree in destination hierarchy will be returned.
Table 2011
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_tree_node_id
VARCHAR2
Mandatory
VARCHAR2
Mandatory
p_dest_tree_
version_id
ID of the destination
parent tree version
VARCHAR2
Mandatory
p_dest_tree_code
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
x_tree_node_id
VARCHAR2
Optional
remove_sub_tree_node
This API allows you to remove a given node along with its descendants from any
hierarchy. When remove_sub_tree_node operation happens, all the descendants
will be deleted.
Table 2012
Parameter
Description
Datatype
Mandatory/Optional
p_tree_structure_
code
VARCHAR2
Mandatory
p_tree_code
VARCHAR2
Mandatory
p_tree_version_id
VARCHAR2
Mandatory
p_tree_node_id
VARCHAR2
Mandatory
p_commit_flag
Commit flag
VARCHAR2
Optional
Default value is Yes.
If commit flag is passed
as "N", the control to
commit is handed over
to the API call.
Draft
Active
Inactive
To activate a tree version, the tree version's tree structure must already be in Active
status.
Setting a tree version's status to Active automatically triggers an audit of that tree
structure.
To set the status of a tree version:
1. Select a tree version.
2.
Choose the appropriate status option from the Actions > Set Status dropdown
menu.
3.
Schedule an audit
The following table describes what each validator checks for, as well as possible
reasons why each validator might fail.
20-55
Table 2013
Validator Descriptions
Validation may have failed
because...
Validator
Checks for...
Effective Date
Validator
Root Node
Validator
To correct...
Modify the effective start and/or
end dates so that effective start date
falls before effective end date.
Allow Multiple Root Nodes flag Modify the tree version so that there
is exactly one root node.
has been set to No at the tree
structure, but the tree version has
multiple root nodes.
Table 2013
Validator
To correct...
Node
Relationship
Validator
20-57
Checks for...
To correct...
Ensure that for all nodes in the tree
version, they have date effectivity at
least for the effective date range for
the tree version.
Multiple
Active Tree
Version
Validator
If Allow Multiple
Active Tree Versions
Flag on the tree
structure has been set to
No, there should not be
more than one active
tree version under a
tree at any time.
If Allow Multiple
Active Tree Versions is
set to No, this restriction
does not apply.
Table 2013
Validator
Range Based
If Allow Range
Node Validator Children on the data
source has been set to
No, range-based nodes
are not permitted from
that data source.
To correct...
The data source has Usage Limit Add nodes to the tree version for
set to Use All Values, but there each data source value that is not yet
are values in the data source that present.
are not in the tree version.
2.
20-59
Audit Result - displays either a green check mark (success) or a red "X"
(failure)
Start Time - displays the date and time the audit began
End Time - displays the date and time the audit was completed
Name - displays the names of the tree or tree version and the audit validators
Validation Result - displays either a green check mark (success) or a red "X"
(failure)
Validation Message - when clicked, displays a validation message and a
description
Corrective Action - when clicked, opens the appropriate trees application task
flow page, allowing you to fix a validation error
To schedule an audit:
1. Click Schedule Audit.
The Schedule Audit window opens.
Figure 2060
2.
3.
/**
* Processes the audit scheduled for any tree or tree version.
* @param requestId Request ID for scheduled audit (for online can be
defaulted as -1)
* @param auditType Auditing mode wheere audit invoked for tree/tree
version(pass as TREE_AUDIT for tree and
* TREE_VERSION_AUDIT for tree version.
* @param tsCode Tree Structure Code
* @param treeCode Tree Code
* @param treeVersionId Tree Version Id
*/
public void processAudit(Long requestId, String auditType, String tsCode,
String treeCode, String treeVersionId)
20-61
Figure 2061
Tables that store flattened data are either row or column flattened. By eliminating
recursive queries, row flattening is particularly useful for efficiently performing
operations across an entire sub-tree.
Understanding Row Flattening
Row flattening is a technique where parent-child information is optimized for
run-time performance by storing additional rows in a table (as compared to just
normalized parent-child rows) to instantly find all descendants to a parent value,
without initiating a Connect By SQL statement.
Normalized data, for example, might be the following:
Corporation - Sales Division
Sales Division - Region
In a row flattened table, the above rows are still stored but one additional row is
added:
Corporation - Region
In addition, additional columns are added to store the "depth" from top parent.
Understanding Column Flattening
Column flattening is a technique where parent-child information is optimized for
run-time performance by storing additional column in a table for all parents of a child.
Normalized data, for example, might be the following:
Corporation - Sales Division
Sales Division - Region
Sales Division
In a column-flattened table, the above data is converted to rows and columns.
Table 2014
Column 1
Column 2
Column 3
Region
Sales Division
Corporation
Usually, the number of levels (possible parents) are pre-defined to a maximum number
and may also have additional "dummy" values on levels where real values are
missing.
To flatten a row or column:
The following procedure assumes the Manage Trees and Tree Versions page is open.
1.
2.
Choose Column Flattening or Row Flattening from the Actions dropdown menu.
3.
4.
The Schedule Flattening page opens. Configure the options and click Submit.
5.
Click Online Flattening or Force Flattening. Either of these actions will flatten the
row.
6.
Figure 2063
7.
Flattening Confirmation
Click Done to return to the Manage Trees and Tree Versions page.
This section describes how to use the Central Labels tab of the trees application launch
page to create, edit, and delete values in the generic label data source.
All procedures assume that the Manage Labels summary page is open in your web
browser.
Name
20-63
2.
Short Name
Click Search.
All labels matching your search criteria appear in the Results area of the page.
2.
Enter a tree structure code or click the down arrow to select or search for one.
The page refreshes and the Data Source field populates with an appropriate value.
3.
4.
5.
6.
7.
Enter an effective start date, or click the calendar icon to select one.
8.
Enter an effective end date, or click the calendar icon to select one.
9.
Enter a Set Name or click the down arrow to select or search one.
The Manage Labels summary page displays showing the new label in the Results
list.
From the Manage Labels summary page, click Edit, or choose Edit from the
Actions dropdown menu.
The Edit Label page displays.
Figure 2065
3.
4.
Click Save and Close to save your changes and exit the editing session.
From the Manage Labels summary page, click Delete, or choose Delete from the
Actions dropdown menu.
20-65
3.
You can add any JSF or ADF Faces component to these facets, even with the generated
af:tree or af:treeTable. The fnd:hierarchy tag supports the TreeCode and TreeVersionId
properties to display specific trees or tree versions.
You can create two types of Hierarchy applications: Tree and Tree Table.
From the ADF Faces page in the Component Palette, select Applications.
3.
From the Applications page in the Component Palette, select Hierarchy and drag
it to your.jspx file's visual editor.
The Initialize Applications Connection window opens:
Figure 2068
4.
Figure 2069
20-67
5.
6.
Select Tree.
7.
8.
Click OK.
The tree appears in the visual editor.
Figure 2070
9.
Figure 2072
3.
4.
5.
Click OK.
The tree table appears in the visual editor.
20-69
Figure 2073
6.
Run the .jspx from either the Application Navigator or the visual editor.
A browser window opens and the application runs.
Related Links
The following document provides more information about the topic discussed in this
section:
For more information about task flows, see "Getting Started with ADF Task Flows"
in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
The full code used to register each custom task flow in the data-source view object is
shown in the examples that follow.
Example 202
<Properties>
<SchemaBasedProperties>
<fnd:SEARCH_PAGE Value="/WEB-INF/EmpSearch.xml#EmpSearchTF"/>
...
...
Example 203
<Properties>
<SchemaBasedProperties>
<fnd:CREATE_PAGE Value="/WEB-INF/CreateEmpNode.xml#CreateEmpNode"/>
...
...
Example 204
<Properties>
<SchemaBasedProperties>
Organizing Hierarchical Data with Tree Structures
20-71
<fnd:DUPLICATE_PAGE Value="/WEB-INF/DupEmpNode.xml#DupEmpNode"/>
...
...
Example 205
<Properties>
<SchemaBasedProperties>
<fnd:UPDATE_PAGE Value="/WEB-INF/EditEmpNode.xml#EditEmpNode"/>
...
...
Example 206
<Properties>
<SchemaBasedProperties>
<fnd:DELETE_PAGE Value="/WEB-INF/DelEmpNode.xml#DelEmpNode"/>
...
...
20.8.2.1 How to Create a Search Task Flow for the Add Node Operation
The Search task flow provides a shortcut to select nodes. In the task flow, you specify
the Search page fragment, task-flow parameters, back-end Java bean, and task-flow
activities.
To create the Search task flow:
1. Define a task-flow parameter, searchHierParamBean, to pass values between the
Hierarchy component and the registered Search task flow in pageFlowScope.
<input-parameter-definition>
<name>searchHierParam</name>
<value>#{pageFlowScope.searchHierParam}</value>
<class>oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean</class>
</input-parameter-definition>
2.
Define Search task-flow return activities and use them as the ends of the task flow.
For example, to define the Submit and Cancel task-flow return activities:
<task-flow-return id="Submit">
<outcome>
<name>Submit</name>
</outcome>
</task-flow-return/>
<task-flow-return id="Cancel">
<outcome>
<name>Cancel</name>
</outcome>
</task-flow-return/>
Normally, Cancel is a free event. However, you must pass values back when Submit
is triggered. Therefore, you can have a submit() actionListener mapping to it.
3.
In your back-end bean, use the following code to get the task-flow parameter:
import oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean;
...
HierParamBean searchParam =
(HierParamBean)AdfFacesContext.getCurrentInstance().getPageFlowScope().get
("searchHierParam");
...
For the Search task flow, you do not need any input parameters from the
Hierarchy component. The only thing this task flow does is to return the search
results. Therefore, after looking up tree nodes in Search task flow, you must pass
back the primary keys of the selected nodes by calling the HierParamBean method
setSelectedNodes(List) when the Submit return activity is invoked:
public void submit(ActionEvent event)
{
// The inner list is the list of primary keys for each node. Trees supports
// up to five primary keys.
// The outer list is the list of selected nodes
List<List<String>> nodes = ...
...
searchParam.setSelectedNodes(nodes);
}
4.
In the page definition file of the page using the Hierarchy component, add the
following task-flow entry in the "executables" section:
<taskflow id="searchTaskflow"
taskFlowId="#{backingBeanScope.AddNodeBean.searchTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="searchHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.searchHierParam}"/>
<parameters>
</taskflow>
5.
A page definition file is created at design time for each JSF/jspx file created, with
the following taskflows created in it under the "executables" section:
<taskFlow id="dupTaskflow"
taskFlowId="#{backingBeanScope.DupNodeBean.dupTaskflow}"
activation="deferred" Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="dupHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.dupHierParam}"/>
</parameters>
</taskFlow>
<taskFlow id="searchTaskflow"
taskFlowId="#{backingBeanScope.AddNodeBean.searchTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="searchHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.searchHierParam}"/>
20-73
</parameters>
</taskFlow>
<taskFlow id="editTaskflow"
taskFlowId="#{backingBeanScope.EditNodeBean.editTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="editHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.editHierParam}"/>
</parameters>
</taskFlow>
<taskFlow id="createTaskflow"
taskFlowId="#{backingBeanScope.CreateNodeBean.createTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="createHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.createHierParam}"/>
</parameters>
</taskFlow>
<taskFlow id="delTaskflow"
taskFlowId="#{backingBeanScope.DelNodeBean.delTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="delHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.delHierParam}"/>
</parameters>
</taskFlow>
To capture the event of dismissing the Create popup window, define Create
task-flow return activities and use them as the ends of the task flow. For example,
to define the Submit and Cancel task-flow return activities:
<task-flow-return id="Submit">
<outcome>
<name>Submit</name>
</outcome>
</task-flow-return/>
<task-flow-return id="Cancel">
<outcome>
<name>Cancel</name>
</outcome>
</task-flow-return/>
Normally, Cancel is a free event. However, you must pass values back when Submit
is triggered. Therefore, you can have a submit() actionListener mapping to it.
3.
In your back-end bean, use the following code to get the task-flow parameter:
import oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean;
...
HierParamBean createParam =
(HierParamBean)AdfFacesContext.getCurrentInstance().getPageFlowScope().get
("createHierParam");
...
For the Create task flow, you do not need any input parameters from the
Hierarchy component. The only thing this task flow does is to return the new
node. Therefore, you must pass back its primary keys by calling the
HierParamBean method setNewPkValue() after creating the node. The Hierarchy
component will get the new node's primary keys after the Create task-flow is
dismissed. For example, in the submit() actionListener that maps to the Submit
return activity, you pass new primary keys back:
public void submit(ActionEvent event)
{
List<String> newPk = ...
...
createParam.setNewPkValue(newPk);
}
4.
In the page definition file of the page using the Hierarchy component, add the
following task-flow entry in the "executables" section:
<taskFlow id="createTaskflow"
taskFlowId="#{backingBeanScope.CreateNodeBean.createTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="createHierParam"
xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.createHierParam}"/>
</parameters>
</taskFlow>
20-75
<input-parameter-definition>
<name>dupHierParam</name>
<value>#{pageFlowScope.dupHierParam}</value>
<class>oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean</class>
</input-parameter-definition>
2.
To capture the event of dismissing the Duplicate popup window, define Duplicate
task-flow return activities and use them as the ends of the task flow. For example,
to define the Submit and Cancel task-flow return activities:
<task-flow-return id="Submit">
<outcome>
<name>Submit</name>
</outcome>
</task-flow-return/>
<task-flow-return id="Cancel">
<outcome>
<name>Cancel</name>
</outcome>
</task-flow-return/>
Normally, Cancel is a free event. However, you must pass values back when Submit
is triggered. Therefore, you can have a submit() actionListener mapping to it.
3.
In your back-end bean, using the following code to get the task-flow parameter:
import oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean;
...
HierParamBean dupParam =
(HierParamBean)AdfFacesContext.getCurrentInstance().getPageFlowScope().get
("dupHierParam");
...
For the Duplicate task flow, you need to know the selected node from the
Hierarchy component. In the Duplicate popup window, the selected node's
attributes are shown by default so that users can create another tree node. After
creating a new node, you pass back its primary key. You can perform all of these
tasks by calling HierParamBean methods.
For example, in the task-flow initializer, you can use the following code to get the
primary keys of the selected node:
List<String> pkValue = dupParam.getPkValue();
In the submit() actionListener that maps to the Submit return activity, you pass the
new primary keys back:
public void submit(ActionEvent event)
{
List<String> newPk = ...
...
dupParam.setNewPkValue(newPk);
}
4.
In the page definition file of the page using the Hierarchy component, add the
following task-flow entry in the "executables" section:
<taskflow id="dupTaskflow"
taskFlowId="#{backingBeanScope.DupNodeBean.dupTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="dupHierParam" xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.dupHierParam}"/>
<parameters>
</taskflow>
To capture the event of dismissing the Edit popup window, define Edit task-flow
return activities and use them as the ends of the task flow. For example, to define
the Submit and Cancel task-flow return activities:
<task-flow-return id="Submit">
<outcome>
<name>Submit</name>
</outcome>
</task-flow-return/>
<task-flow-return id="Cancel">
<outcome>
<name>Cancel</name>
</outcome>
</task-flow-return/>
Normally, Cancel is a free event. However, you must pass values back when Submit
is triggered. Therefore, you can have a submit() actionListener mapping to it.
3.
In your back-end bean, using the following code to get the task-flow parameter:
import oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean;
...
HierParamBean editParam =
(HierParamBean)AdfFacesContext.getCurrentInstance().getPageFlowScope().get
("editHierParam");
...
For the Edit task flow, you need to know the current node from the Hierarchy
component. In the Edit popup window, the current node's attributes are shown by
default so that users can update the tree node. After updating the node, you must
indicate whether or not the update was successful. You can perform all of these
tasks by calling HierParamBean methods.
For example, in the task-flow initializer, you can use the following code to get the
primary keys of the selected node:
Organizing Hierarchical Data with Tree Structures
20-77
In the submit() actionListener that maps to the Submit return activity, you specify
the result:
public void submit(ActionEvent event)
{
...
editParam.setUpdated(true);
}
4.
In the page definition file of the page using the Hierarchy component, add the
following task-flow entry in the "executables" section:
<taskflow id="editTaskflow"
taskFlowId="#{backingBeanScope.EditNodeBean.editTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="dupHierParam" xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.editHierParam}"/>
<parameters>
</taskflow>
To capture the event of dismissing the Delete popup window, define Edit
task-flow return activities and use them as the ends of the task flow. For example,
to define the Submit and Cancel task-flow return activities:
<task-flow-return id="Submit">
<outcome>
<name>Submit</name>
</outcome>
</task-flow-return/>
<task-flow-return id="Cancel">
<outcome>
<name>Cancel</name>
</outcome>
</task-flow-return/>
Normally, Cancel is a free event. However, you must pass values back when Submit
is triggered. Therefore, you can have a submit() actionListener mapping to it.
3.
In your back-end bean, using the following code to get the task-flow parameter:
import oracle.apps.fnd.applcore.trees.ui.managed.HierParamBean;
...
HierParamBean delParam =
(HierParamBean)AdfFacesContext.getCurrentInstance().getPageFlowScope().get
("delHierParam");
...
For the Delete task flow, you need to know the selected node from the Hierarchy
component. In the Delete popup window, delete the node and confirm the
deletion. After deleting the node, you must indicate whether or not the deletion
was successful. You can perform all of these tasks by calling HierParamBean
methods.
For example, in the task-flow initializer, you can use the following code to get the
primary keys of the selected node:
List<String> pkValue = delParam.getPkValue();
In the submit() actionListener that maps to the Submit return activity, you specify
the result:
public void submit(ActionEvent event)
{
...
delParam.setDeleted(true);
}
4.
In the page definition file of the page using the Hierarchy component, add the
following task-flow entry in the "executables" section:
<taskFlow id="delTaskflow"
taskFlowId="#{backingBeanScope.DelNodeBean.delTaskflow}"
activation="deferred"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="delHierParam" xmlns="http://xmlns.oracle.com/adfm/uimodel"
value="#{pageFlowScope.delHierParam}"/>
</parameters>
</taskFlow>
20-79
The Hierarchy component has facets and properties listed in the next tables.
Table 2015
Hierarchy Facets
Facet
Description
Values
hierarchy
af:tree or af:treeTable
toolbar
Table 2016
Hierarchy Properties
Property
Description
Values
id
string
rendered
boolean
readOnly
boolean
treeStructureCode
string
tree Code
string
treeVersionId
string
actionsMenuRendered
boolean
toolbarRendered
boolean
addVisible
boolean
addRendered
boolean
addDisabled
boolean
Table 2016
Property
Description
Values
addText
string
createVisible
boolean
createRendered
boolean
createDisabled
boolean
createText
string
duplicateVisible
boolean
duplicateRendered
boolean
duplicateDisabled
boolean
duplicateText
string
editVisible
boolean
editRendered
boolean
editDisabled
boolean
editText
string
removeVisible
boolean
removeRendered
boolean
removeDisabled
boolean
removeText
string
deleteVisible
boolean
deleteRendered
boolean
deleteDisabled
boolean
deleteText
string
registerTaskflow
boolean
For example:
<fnd:hierarchy registerTaskflow="true"
...
</fnd:hierarchy>
Since only customers create tree versions, you must use service
APIs to generate lists of tree versions or active tree versions.
Note:
The data that displays in your application depends on the tree structure you specify in
the Property Inspector. The tree structure automatically determines the following at
run time:
The tree available under this particular tree structure. If there are multiple trees,
the first one is chosen.
The active tree version (for the current date) available under the tree. If there are
multiple tree versions, the first one is chosen.
20-81
Using the Expression Builder to Bind TreeCode, TreeStructureCode, and TreeVersionId Properties
TreeCode
TreeStructureCode
TreeVersionId
TreeStructureCode expression:
#{HierarchyHandler.treeModelsList[hierarchyId].treeStructureCode}
TreeVersionId expression:
#{HierarchyHandler.treeModelsList[hierarchyId].treeVersionId}
Note:
Drag and drop the Tree Picker from Component Palette > Trees-View.jar onto
your task flow.
3.
Connect the launch page to the Tree Picker using an appropriate Control Flow
Case with from-outcome set to launch and run-as-dialog set to true.
4.
In the Property Inspector > Parameters section for the task flow, enter the
appropriate parameters for the following:
If the Tree Picker is launched as a popup window, the return value can be obtained
in the returnListener of the icon or button using:
List<TreeNode> =
selectedTreeNodes(List<TreeNode>)event.getReturnValue();
If the Tree Picker is launched in place, the return value can be obtained from the
pageFlowScope using:
Map pageFlow = AdfFacesContext.getCurrentInstance().getPageFlowScope();
List<TreeNode> selectedNodes = (List<TreeNode>) pageFlow.get("return
TreeNodes");
The following picture shows the results window that displays when you enter a
tree-structure-code value and click Select Tree Node.
Figure 2078
20-83
In JDeveloper, click on the appropriate data source view object. (Ensure that it is
highlighted in the Structure window.)
2.
Select the Query option from the Overview tab. The following picture shows the
Bind Variables and View Criteria sections after the Query option is selected.
Figure 2079
3.
Click the Bind Variables Add icon to add any necessary bind variables.
Click the View Criteria Add icon to add any necessary view criteria.
There are three service application modules that you can use to interact with the tree
management infrastructure:
TreeStructureService
TreeService
TreeNodeService.
No Service Data Objects (SDOs) are provided and these
application modules must be instantiated and invoked in a co-located
mode.
Note:
Choose the Go to Java Class... option from the Navigate dropdown menu.
The Go to Java Class window opens.
2.
3.
This application module is considered a public API to work with tree structure
metadata and exposes the APIs shown in the following table.
Table 2017
TreeStructureService APIs
API
Description
getTreeStructure
getRootDataSourceRels
getAllTreeColumns
getAllDataSources
20-85
Description
getTreeNodeTable
duplicateTreeStructure
deleteTreeStructure
3.
This application module is considered a public API to work with trees and tree
versions and exposes the APIs shown in the following table.
Table 2018
TreeService APIs
API
Description
getTreeRows
Optional
Parameters
This API returns all trees associated with a given tree structure.
getTreeCodes
findTree
createTree
treeDescription
Table 2018
API
Description
updateTree
deleteTree
getAllTreeVersions
getTreeVersions
getCurrentTreeVersi
ons
findTreeVersion
createTreeVersion
treeVersionDescri
ption,
effectiveEndDate,
treeVersionNote
This API creates a tree version and returns the ID of the created tree
version. The default values for all these parameters is NULL. The
default for the effectiveEndDate parameter is 31-DEC-4712.
20-87
Description
updateTreeVersion
Optional
Parameters
effectiveEndDate
updatedTreeVersio
nName,
updatedTreeVersio
nDescription,
updatedEffectiveS
tartDate,
updatedEffectiveE
ndDate,
updatedTreeVersio
nNote
rowFlatten
columnFlatten
value nodes
range nodes
tree-in-tree nodes.
The Java APIs are covers to the PL/SQL APIs that are provided in the FND_TREE_
UTILS PL/SQL package.
To access the Java Doc:
Choose the Go to Java Class... option from the Navigate dropdown menu.
1.
3.
This application module is considered a public API to work with tree nodes and
exposes the APIs shown in the next table.
Table 2019
TreeNodeService APIs
API
Description
addValueTreeNode
addRangeTreeNode
addTreeTreeNode
deleteTreeNode
updateTreeNode
20-89
Advanced Topics
Description
moveTreeNode
moveSubTree
copySubTree
removeSubTree
findValueTreeNodes
findRangeTreeNodes
findRefTreeNodes
PL/SQL APIs
Incremental flattening
FND_TREE_STRUCTURE
FND_TREE_STRUCTURE_TL
Advanced Topics
FND_TS_DATA_SOURCE
FND_TS_DATA_SOURCE_REL
FND_TS_DATA_SOURCE_PARAMS
FND_LABEL
FND_LABEL_TL
FND_TREE
FND_TREE_TL
FND_TREE_DATA_SOURCE_PARAMS
FND_TREE_VERSION
FND_TREE_VERSION_TL
FND_NODE
FND_NODE_TL
FND_TREE_LABEL
FND_TREE_NODE
FND_TREE_NODE_RF
FND_TREE_NODE_CF
FND_TREE_AUDIT_JOB
FND_TREE_VERSION_AUDIT_RES
FND_TREE_VERSION_AUDIT_RES_TL
FND_TREE_LOG
FND_TREE_LOG_PARAMS
FND_TREE_FLATTENING_HISTORY
Views:
FND_TREE_STRUCTURE_VL
FND_LABEL_VL
FND_TREE_VL
FND_TREE_VERSION_VL
FND_NODE_VL
FND_TREE_VERSION_AUDIT_RES_VL
Note:
20-91
Advanced Topics
Flattening Delta
FND_TREE_FLATTENING_HISTORY
FND_TREE_LOG
FND_TREE_LOG_PARAMS
FND_TREE_FLATTENING_HISTORY
Column
Data Type
Nullable?
Tree_Structure_Code (Primary
Key)
Varchar2(30)
No
Varchar2(30)
No
Varchar2(32)
No
Process_Point
Timestamp(6)
No
Varchar2(32)
No
Created_By
Varchar2(64)
No
Creation_Date
Timestamp(6)
No
Last_Updated_By
Varchar2(64)
No
Last_Update_Date
Timestamp(6)
No
Last_Update_Login
Varchar2(32)
Yes
Advanced Topics
value
range
tree node
add
move
delete
FND_TREE_LOG
Column
Data Type
Nullable?
Varchar2(32)
No
Tree_Structure_Code
Varchar2(30)
No
Tree_Code
Varchar2(30)
No
Tree_Version_ID
Varchar2(32)
No
Operation_Type
Varchar1(32)
No
Created_By
Varchar2(64)
No
Creation_Date
Timestamp(6)
No
Last_Updated_By
Varchar2(64)
No
Last_Update_Date
Timestamp(6)
No
Last_Update_Login
Varchar2(32)
Yes
20-93
Advanced Topics
FND_TREE_LOG_PARAMS
Column
Data Type
Nullable?
Varchar2(32)
No
Varchar2(64)
No
Param_Value
Varchar2(100)
No
Created_By
Varchar2(64)
No
Creation_Date
Timestamp(6)
No
Last_Updated_By
Varchar2(64)
No
Last_Udpate_Date
Timestamp(6)
No
Last_Update_Login
Varchar2(32)
Yes
Example of DISTANCE
Advanced Topics
Table 2023
Adjacency List
Node
Parent
Null
Note:
Table 2024
Node
Ancestor
Distance
IS_LEAF?
Null
Null
Null
Null
To find the path from the root of D, the query would be the following:
select *
from fnd_tree_node_rf
where tree_node_id = D order by distance
20-95
Advanced Topics
Figure 2082
Leaf-to-Root Order
Column-Flattening Results
Dep0
Dep1
Dep2
Dep3
Dep4
...
Dep31
LA
CA
USA
North America
Null
...
Null
SF
CA
USA
North America
Null
...
Null
DC
Null
USA
North America
Null
...
Null
Note:
Entity
Event Name
Condition
Payload
Tree Structure
TreeStructureCreateEvent
Create
TreeStructureCode
Tree Structure
TreeStructureUpdateEvent
Update
TreeStructureCode
Tree Structure
TreeStructureDeleteEvent
Delete
TreeStructureCode
Tree
TreeCreateEvent
Create
TreeStructureCode, TreeCode
Tree
TreeUpdateEvent
Update
TreeStructureCode, TreeCode
Tree
TreeDeleteEvent
Delete
TreeStructureCode, TreeCode
Tree Version
TreeVersionCreateEvent
Create
TreeStructureCode, TreeCode,
TreeVersionId
Tree Version
TreeVersionUpdateEvent
Update
TreeStructureCode, TreeCode,
TreeVersionId
Advanced Topics
Table 2026
Entity
Event Name
Condition
Payload
Tree Version
TreeVersionDeleteEvent
Delete
TreeStructureCode, TreeCode,
TreeVersionId
Tree Node
TreeNode Created
Tree Node
TreeNode Deleted
Tree Node
TreeNode Updated
Tree Node
TreeNode Moved
Related Links
The following document provides more information about the topic discussed in this
section:
For more information, see "Using Business Events and the Event Delivery
Network" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
The treeManagement.py Python Script defines the WLST commands that can be
executed at the WLST prompt. Each command corresponds to a method in the python
script. The python script is available at $ADE_VIEW_ROOT/atgpf/applcore/etc/wlst/.
A package oracle.apps.fnd.applcore.trees.mbean is added to the Trees
ViewController Layer. This package includes the following files:
20-97
Advanced Topics
Table 2027
File
Description
TreeFlatteningMBeanLifeCycleCallBack.java
TreeMBeanUtil.java
TreeFlatteningMBean.java
TreeFlatteningMBeanImpl.java
FlatteningBean.java
TreeFlatteningXMLReport.java
TreeMBeanUtil.java
UIModelConstants.java
UIModelMsgBundle.java
Listener Class:
<listener>
<listener-class>
oracle.apps.fnd.applcore.trees.runtime.TreeFlatteningMBeanLifeCycleCallBack
</listener-class>
</listener>
Ensure the following before you execute the WLST commands for flattening:
flattenAll
flattenTreeStructure
flattenTree
flattenTreeVersion
flattenTreeVersionAsync
flattenTreeVersionId
forceFlattenTreeVersion
auditTreeVersion
Advanced Topics
auditTreeVersionAsync
2.
Parameter
Datatype
Description
type
String
Optional
Type of flattening to be
performed. It can be COLUMN or
ROW flattening. By default, this
API triggers both types of
flattening
flattenAll(type='COLUMN')
20-99
Advanced Topics
Table 2029
Parameter
Datatype
Description
treeStructureCode
String
type
String
Type of flattening to be
Optional
performed. It can be COLUMN or
ROW flattening. By default, this
API triggers both types of
flattening
Mandatory
flattenTreeStructure(treeStructureCode='FND_DEMO_EMP_TS')
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
type
String
Optional
Type of flattening to be
performed. It can be COLUMN or
ROW flattening. By default, this
API triggers both types of
flattening
flattenTree(treeCode='FND_DEMO_EMP_T',treeStructureCode='FND_DEMO_EMP_TS')
Note:
Advanced Topics
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
treeVersionName
String
Mandatory
type
String
Optional
Type of flattening to be
performed. It can be COLUMN or
ROW flattening. By default, this
API triggers both types of
flattening
Note:
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
treeVersionName
String
Mandatory
type
String
Optional
Type of flattening to be
performed. It can be COLUMN or
ROW flattening. By default, this
API triggers both types of
flattening
20-101
Advanced Topics
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
treeVersionId
String
type
String
Optional
Type of flattening to be
performed. It can be COLUMN or
ROW flattening. By default, this
API triggers both types of
flattening
Note:
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
treeVersionName
String
Mandatory
Advanced Topics
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
treeVersionName
String
Mandatory
setActive
Boolean
Optional
Parameter
Datatype
Description
treeStructureCode
String
Mandatory
treeCode
String
Mandatory
treeVersionName
String
Mandatory
setActive
Boolean
Optional
20-103
Advanced Topics
XML report
You can redirect the details printed on the console to a file, if
required.
Note:
Advanced Topics
wls:/DefaultDomain/serverConfig>
An XML Report is generated every time you execute a WLST command. The XML
report contains all the results of the flattening APIs invoked. The following examples
illustrate the XML report generated in various scenarios.
Example 2017 Success Report
<?xml version = '1.0' encoding = 'UTF-8'?>
<TreesFlatteningReport status="SUCCESS">
<TreeStructure treeStructureCode="TEST_PLSQL_EXTN_TS" treeCodeCount="2"
success="2" error="0">
<TreeCode treeCode="TEST_PLSQL_EXTN_TR1" treeVersionCount="3" success="3"
error="0">
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V1"
treeVersionId="B7598796828D8027E040449895F14B45" flatteningType="ROW"
time="0.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V1"
treeVersionId="B7598796828D8027E040449895F14B45" flatteningType="COLUMN"
time="0.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V2"
treeVersionId="B7598796829A8027E040449895F14B45" flatteningType="ROW"
time="0.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V2"
treeVersionId="B7598796829A8027E040449895F14B45" flatteningType="COLUMN"
time="0.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V3"
treeVersionId="B7598796829F8027E040449895F14B45" flatteningType="ROW"
time="0.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V3"
treeVersionId="B7598796829F8027E040449895F14B45" flatteningType="COLUMN"
time="0.0secs" status="SUCCESS"/>
</TreeCode>
<TreeCode treeCode="TEST_PLSQL_EXTN_TR2" treeVersionCount="1" success="1"
error="0">
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR2_V1"
treeVersionId="B759879682A48027E040449895F14B45" flatteningType="ROW"
time="0.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR2_V1"
treeVersionId="B759879682A48027E040449895F14B45" flatteningType="COLUMN"
time="0.0secs" status="SUCCESS"/>
</TreeCode>
</TreeStructure>
</TreesFlatteningReport>
Example 2018 Error Report with Flattening Errors but no Exception
<?xml version = '1.0' encoding = 'UTF-8'?>
<TreesFlatteningReport status="ERROR">
<TreeStructure treeStructureCode="TEST_PLSQL_EXTN_TS" treeCodeCount="1"
success="0" error="1">
<TreeCode treeCode="TEST_PLSQL_EXTN_TR1" treeVersionCount="3" success="2"
error="1">
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V1"
treeVersionId="B7598796828D8027E040449895F14B45" flatteningType="ROW"
time="4.0secs" status="SUCCESS"/>
<TreeVersion treeVersionName="TEST_PLSQL_EXTN_TR1_V1"
treeVersionId="B7598796828D8027E040449895F14B45" flatteningType="COLUMN"
time="0.0secs" status="ERROR">
20-105
Advanced Topics
21
Working with Localization Formatting
21
This chapter describes the Oracle Fusion Applications standards and guidelines for
working with localization formatting.
21-1
Formatting Currency
You can format currency using the default formatting behavior, or by overriding the
default formatting. Alternatively, you can format currency on the fly using partial page
rendering.
Currency fields are represented by java.lang.BigDecimal in entity objects and view
objects.
A currency field should always be formatted according to the currency code chosen in
the context UI of the transaction.
For example, if the user selects JPY as the currency code from the context UI, then the
currency value should be formatted according to the Japanese Yen standard.
There are two implementations to format numerical values according to the
corresponding currency code.
Syntax of fnd:currencyPatternWithPrecisionAndSymbol
fnd:currencyPatternWithPrecisionAndSymbol(
bindingToAmountCurrencyCode, bindingToAttrNamePrecision,
bindingToAttrNameCurrencySymbol)
For example, if JPY is entered as the formatting currency code, and symbol is used
as the currency code/symbol parameter, and the number of precision digits is set
to 1, then the number would be formatted as #,##0.0 ;-#,##0.0 . The numerical
value 135.6789 retrieved from the database must be shown as 135.68$ in USD,
whereas the same number will need to be shown as 136 in JPY. (This example
considers that the currencySymbol parameter has been set to symbol). The
currencySymbol parameter can only take the values symbol, code, or none.
Currency codes are stored in the FND_Currencies table located in the Oracle Fusion
Middleware Extensions for Applications schema. The currency code determines the
format mask for the currency field, including:
Formatting Currency
Precision: Determines the use and number of decimal digits, comma placement, and
so on.
Currency symbol: Displays the standard symbol for the currency.
The Expression Language function fnd:currencyPattern() determines formatting for
the currency field using the default precision associated with the currency code. No
currency symbol or code is displayed in the user interface. The Expression Language
function fnd:currencyPatternWithPrecisionAndSymbol() determines formatting for
the currency field using an extra parameter for precision. It also uses the currency code
to show a currency symbol/code in the user interface. User preferences for grouping
and decimal separators are used to format the value in both these functions.
In Example 213, the grouping separator and decimal separator are taken from the
user's number preferences, and the number of precision digits is set to 2. Also, the
symbol shown corresponds to the currency code set in the af:convertNumber tag.
21-3
Formatting Currency
Example 213
The fields Ordered, Total Tax, and Total in Figure 211 show how currency values are
formatted in Oracle Fusion Applications.
Figure 211 Showing How Currency Values Are Formatted
As the developer, you should change the generated code according to either the
fnd:currencyPattern() Expression Language function or the
fnd:currencyPatternWithPrecisionAndSymbol() Expression Language function as
shown in Example 215.
Example 215
Formatting Numbers
1,234.56
1'234.56
1'234,56
1.234,56
1234,56
1 234.56
1 234,56
View objects and entity objects can be formatted so as to display date and number data
in accordance with local standards. The ISO standard is typically used when it is not
desirable to use local standards.
21-5
Formatting Numbers
Input decimal fields should be formatted according to the user's number preferences.
In Example 217, use the <af:convertNumber pattern... entry to retrieve the number
formatting pattern from the applCorePrefs bean.
Example 217
<af:inputText value="#{row.bindings.FromValue.inputValue}"
label="#{bindings.PerformanceThreshold21.hints.FromValue.label}"
required="#{bindings.PerformanceThreshold21.hints.FromValue.mandatory}"
columns="#{bindings.PerformanceThreshold21.hints.FromValue.displayWidth}"
maximumLength="#{bindings.PerformanceThreshold21.hints.FromValue.precision}"
shortDesc="#{bindings.PerformanceThreshold21.hints.FromValue.tooltip}"
id="inputText9"
autoSubmit="true">
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
</af:inputText>
The Threshold Start field in Figure 212 is an example of a number field that is
formatted according to the user's number formatting preferences.
Figure 212 Example of a Formatted Number Field
When a decimal number is to be shown as a part of a larger string object on the user
interface, the fnd:formatNumber and fnd:formatNumber2 Expression Language
functions provided in the applCore library is necessary to format such numbers. When
either of these functions is used, the user's number formatting preferences are
implemented according to applCorePrefs.numberFormatPattern.
The syntaxes of the two Expression Language functions are:
fnd:formatNumber(java.lang.Number decimalValueToBeFormatted)
Example 218 shows how to use these two functions for decimal number formatting.
Example 218
<af:image id="img65"
source="/images/upgreenplus_status.png"
shortDesc="#{af:formatNamed(prcponnegotiationsuiBundle3['AltTxt.IncreasedbyVALUE.F
avorablyIncreasedbyVALUE'], VALUE',
fnd:formatNumber(bindings.ActiveResponsesChangeAmt.inputValue))}"
visible="#{bindings.ActiveResponsesChange.inputValue == 'INCREASE'}"/>
Formatting Numbers
Example 219.
Example 219
<af:showDetailItem text="#{PjbWorkareaGenBundle['Header.SubmittedValues']}
(#{fnd:formatNumber2(pageFlowScope.InvoiceWorkareaBean.invoiceValueRowNum[1],2)})"
id="tabSubmitted"
disclosureListener="#{InvoiceListBean.changeStatusTab}"
partialTriggers="AT1:_ATp:menuSubmit AT1:_ATp:btnSubmit AT2:_
ATp:menuApprove AT2:_ATp:menuReject AT2:_ATp:menuRelease AT2:_
ATp:menuReturntoDraft cl1"
stretchChildren="first"
disclosedTransient="true"
disclosed="#{pageFlowScope.pageFocus == '2'}">
Here, the text attribute of the af:showDetailItem tag includes a number that must be
formatted before being displayed. Therefore, the fnd:formatNumber2 Expression
Language function has been used to format the number to be added to the
SubmittedValues string. Here, the second parameter has been set to 2 and indicates
that a maximum of two fractional digits can be shown in the decimal number. So, for
example, after formatting, the number 1234.56789 that is retrieved from the database
will be displayed as SubmittedValues: 1,234.57.
Input integer fields should be formatted according to the user's number preferences
without showing any decimal precision digits. As shown in Example 2111, use the
<af:convertNumber pattern... entry to retrieve the number formatting pattern from
the applCorePrefs bean.
Example 2111 Formatting Input Integer Fields
<af:inputText value="#{bindings.Point1.inputValue}"
label="#{bindings.Point1.hints.label}"
required="#{bindings.Point1.hints.mandatory}"
columns="#{bindings.Point1.hints.displayWidth}"
maximumLength="#{bindings.Point1.hints.precision}"
shortDesc="#{bindings.Point1.hints.tooltip}"
inlineStyle="width:100%; border-color:InactiveBorder; border-width:thin;"
id="inputText5">
<f:validator binding="#{bindings.Point1.validator}"/>
<af:validateLongRange minimum="0"/>
<af:convertNumber pattern="#{applCorePrefs.integerFormatPattern}"/>
</af:inputText>
21-7
Formatting Numbers
When an integer number is to be shown as a part of a larger string object on the user
interface, the fnd:formatNumber2 function provided in the applCore library is
necessary to format such numbers. When this function is used with the maximum
number of precision digits set to 0, the user's number formatting preferences are used
from applCorePrefs.numberFormatPattern with no precision digits.
The syntax of the fnd:formatNumber2 function is as follows:
fnd:formatNumber2(java.lang.Number integerValueToBeFormatted, int
maximumNumberOfFractionDigits)
Here, the text attribute of the af:showDetailItem tag includes a number that must be
formatted before being displayed. The fnd:formatNumber2 function is used to format
the integer to be added to the SubmittedInvoices string. The second parameter has
been set to 0 and indicates that no fractional digits can be shown in the formatted
21-8 Developer's Guide
Formatting Numbers
number. For example, after formatting, the number 1234 that is retrieved from the
database will be displayed as SubmittedInvoices: 1,234.
The field Sales Order Line in Figure 214 corresponds to the output ID field shown in
Example 2113.
Figure 214 Sample Output ID Field
Input integer fields should be formatted according to the user's number preferences
without showing any decimal precision digits or grouping separators. The
<af:convertNumber pattern entry in Example 2114 indicates that the number
formatting pattern is being retrieved from the applCorePrefs bean.
Example 2114 Formatting Input Integer Fields
<af:inputText value="#{bindings.SequenceNumber.inputValue}"
label="#{bindings.SequenceNumber.hints.label}"
required="#{bindings.SequenceNumber.hints.mandatory}"
21-9
Formatting Numbers
columns="#{bindings.SequenceNumber.hints.displayWidth}"
id="inputText1"
partialTriggers="asgStat"
helpTopicId="InvCoreSetup_755E15370133C364E040D30A688161D5V000"
contentStyle="text-align:start"
autoSubmit="true">
<f:validator binding="#{bindings.SequenceNumber.validator}"/>
<af:convertNumber pattern="#{applCorePrefs.numericCodeFormatPattern}"/>
</af:inputText>
The Sequence field in Figure 215 corresponds to the input ID field shown in
Example 215.
Figure 215 Example Input ID Field
Because af:convertNumber is not a valid child tag of af:commandLink, the best way to
format a number on a link is by making the text attribute of the af:commandLink tag
empty and then adding an af:outputText tag as a child tag that displays the
formatted numerical value. In this case, the number is an integer (java.lang.Integer), so
the pattern applCorePrefs.integerFormatPattern has been used. In cases of decimal
numbers (java.math.bigDecimal), applCorePrefs.numberFormatPattern has to be
used, while in cases of ID fields (java.lang.Long), af:convertNumber can be removed
and the field can be honored as plain text. The parent hyperlink tag can be either
af:commandLink or af:goLink.
Formatting Numbers
Similarly, numbers that are found on links represented by the af:goLink tag in Oracle
Application Development Framework (Oracle ADF) should be formatted according to
the user's number formatting preferences using the Preferences bean. The procedure to
be followed is very similar to that of the af:commandLink tag. Sample code for number
formatting in af:golink is shown in Example 2116.
Example 2116 Formatting a Number in af:goLink
<af:goLink text="" id="gl1" destination="#{row.children[0].FileUrl}">
<af:outputText id="id1" value="#{bindings.fromValue.inputValue}">
<af:convertNumber type="number"
pattern="#{applCorePrefs.numberFormatPattern}"/>
</af:outputText>
</af:goLink>
Again, af:goLink cannot have an af:convertNumber as its child tag, so the text
attribute of the goLink tag should be made empty and af:outputText should be
added as a child tag of af:goLink. The af:convertNumber then can be added as a
subtag of the outputText tag. The pattern attribute can be changed for this
af:convertNumber tag, according to whether the number is decimal or an integer. If
the number represents an ID field, no number formatting is needed.
Another way of formatting the text in af:commandLink and af:goLink is by using the
Expression Language functions fnd:formatNumber and fnd:formatNumber2 in their
text attributes. Sample code to format a number in a commandLink using the
fnd:formatNumber2 Expression Language function is shown in Example 2117.
Example 2117 Formatting a Number in a commandLink
<af:commandLink id="outputText6"text
="#{fnd:formatNumber2(row.InvPendingCount,0)}"
partialSubmit="true" immediate="true"
action="#{LocalAreaHandlerBean.showInventory}">
</af:commandLink>
Here, the second parameter has been set to 0 so that no precision digits are shown.
This is the same as using pattern="#{applCorePrefs.integerFormatPattern}" as
used in Example 2115. The only added feature in this example is that there is no need
to add a child af:outputText tag for number formatting.
Similarly, af:goLink can also be formatted using the fnd:formatNumber and
fnd:formatNumber2 Expression Language functions. An example of formatting the
af:goLink shown in Example 2116 using the fnd:formatNumber function is shown in
Example 2118:
Example 2118 Formatting af:goLink Using fnd:formatNumber
<af:goLink text="#{fnd:formatNumber(bindings.fromValue.inputValue)}" id="gl1"
destination="#{row.children[0].FileUrl}"/>
Here, the fnd:formatNumber Expression Language function has been used to format
the value in the af:goLink. This is the same as using
pattern="#{applCorePrefs.numberFormatPattern}" as shown in Example 2116.
21-11
Formatting Numbers
A percentage value in an input field generally is formatted exactly like the output
percentage field. Sample code to format input percentage fields is shown in
Example 2120.
21-13
Both the filter for the date and the date field should be formatted according to the
user's date formatting preferences.
The values for the Due Date field in Figure 217 are examples of how a date value is
formatted according to the user's preferences in Oracle Fusion Applications.
Figure 217 Example of a Formatted Date Value
A server date is calculated by truncating the time portion of the current time from the
system clock. However, it may not be appropriate to display the server date to end
users if they are not located in the server time zone. For example, when creating an
order, the order form may display with the order date filled out for the end user with
the current date. In this case, the order date must be the end user's local date rather
than the server date. A server in the US may be serving an end user in China, whose
local date may be one day ahead due to time zone differences. It is necessary to adjust
the server date to the end user's local date.
The following methods return the current date in UPTZ:
These methods can be used in JSF pages, entity object files, and Java bean classes to
retrieve a current date in UPTZ.
Example 2123 shows how to adjust the server date to the local date in the Java bean
using the getCurrentLocalDate() method.
Example 2123 Getting the Current Date in UPTZ Using java Bean Classes
import java.sql.Date;
import oracle.apps.fnd.applcore.common.ApplSessionUtil;
...
Date currentDate = ApplSessionUtil.getCurrentLocalSqlDate();
...
Example 2124 shows how to display the current date in the JSF page.
Example 2124 Displaying the Current Date in the JSF Page
<af:outputText value="#{applCorePrefs.currentLocalSqlDate}" id="ot1">
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
</af:outputText>
example shows how to set the current date in UPTZ as a value in entity object files.
Example 2125 Setting the Current Date in UPTZ as a Value in Entity Object Files
<Attribute
Name="CreationDate"
IsNotNull="true"
ColumnName="CREATION_DATE"
SQLType="TIMESTAMP"
Type="java.sql.Date"
ColumnType="DATE"
TableName="FND_TERRITORIES_B"
RetrievedOnInsert="true">
<DesignTime>
<Attr Name="_DisplaySize" Value="11"/>
</DesignTime>
<TransientExpression><![CDATA[oracle.apps.fnd.applcore.common.
ApplSessionUtil.currentLocalSqlDate]]>
</TransientExpression>
</Attribute>
21-15
The Required Date field in Figure 218 should default to the user's preferred time zone
rather than the server time zone, which, in this case, shows a date value with the
format yyyy.mm.dd.
Figure 218 Example of a Field to Default to User's Time
Note:
Pattern 1
pattern="#{applCorePrefs.UPTZPattern}"
Pattern 2
This pattern is applicable if it always needs to display the Seconds part of a
datetime value.
pattern="#{applCorePrefs.DateFormatPattern}
#{applCorePrefs.timeFormatPatternWithSeconds}"
Pattern 3
pattern="#{applCorePrefs.DateFormatPattern}
#{applCorePrefs.timeFormatPatternWithoutSeconds}"
This pattern is applicable if it does not need to display the Seconds part of a
date-time value.
Pattern 4
pattern="#{applCorePrefs.timeFormatPattern}"
Pattern 5
pattern="#{applCorePrefs.timeFormatPatternWithSeconds}"
Pattern 6
pattern="#{applCorePrefs.timeFormatPatternWithoutSeconds}"
21-17
</af:inputDate>
</af:column>
The Last Saved field at the top right of Figure 219 is an example of how a date-time is
formatted according to the user's preferences in Oracle Fusion Applications. In this
case, the date and time are displayed in the format mm.dd.yy and the time hh:mm AM.
Figure 219 Example of a Formatted Date and Time
This type of code is generated for both date and timestamp fields. For date fields, you
should add the type="date" attribute, whereas for timestamp fields, you should add
the type="both" attribute, and make the pattern attribute equal to one of the three
patterns discussed above.
21.4.3 What Happens at Runtime: How Dates and Timestamps Are Formatted
At runtime, the bindings generated at design time are executed. Dates and
Timestamps are displayed according to user preferences for date and time formatting
patterns (for example, 01/01/10 and 01/01/10 01:05:00).
The business logic of the application decides which time zone to use to calculate the
date-time value.
This is to say that nothing must be explicitly added into the automatically generated
af:convertDateTime tag.
Using the User Preferred Time Zone
Use this code sample to calculate the date-time value according to the User Preferred
Time Zone.
21-19
Use this PL/SQL API to obtain the Legal Entity Time Zone code. This API is found in
the package XLE_LE_TIMEZONE_GRP and is to be called in the following way:
Get_Le_Tz_Code(?,?)
To retrieve the current date and time in the Legal Entity Time Zone, use this PL/SQL
API to calculate the current date and time in the Legal Entity Time Zone. This is
particularly useful while creating or saving a transaction, when the legal entity date
and time is to be displayed. This API is found in the XLE_LE_TIMEZONE_GRP package
and is to be called in the following way:
Get_Le_Sysdate_Time(?,?)
This function will invoke the API (Get_DefaultLegalEntity) when the input
parameter passed is the Business Unit or the Inventory Organization.
To convert the server date and time into the LETZ, use this PL/SQL API. This is useful
while retrieving an already saved transaction and showing the already saved
21-20 Developer's Guide
timestamp in the LETZ. This API is found in the XLE_LE_TIMEZONE_GRP package and is
to be called in the following way:
Get_Le_Day_Time(?,?,?)
Here the p_trxn_date is the transaction date and time value in the server time zone.
To convert the legal entity date and time into the server time zone, use this PL/SQL
API. This API is found in the XLE_LE_TIMEZONE_GRP package and is to be called in the
following way:
Get_Server_Day_Time(?,?,?)
These PL/SQL APIs must be called in the Java entity object implementation classes for
time zone conversion. The JSF code corresponding to the date field need not be
changed.
Here is a sample of a JSF date field in the server time zone and its corresponding
conversion into the LETZ. The code in the JSF page corresponding to a date field is
shown in Example 2134.
Example 2134 Converting a Date Field into the LETZ
<af:inputDate value="#{bindings.InvoiceDate.inputValue}"
label="#{bindings.InvoiceDate.hints.label}"
required="#{bindings.InvoiceDate.hints.mandatory}"
shortDesc="#{bindings.InvoiceDate.hints.tooltip}"
showRequired="true" autoSubmit="true"
valueChangeListener="#{pageFlowScope.invoiceActionsBean.
21-21
invoiceDateValueChangeListener}"
columns="#{bindings.InvoiceDate.hints.displayWidth}"
disabled="#{pageFlowScope.matchPopupVisible}"
id="id2">
<f:validator binding="#{bindings.InvoiceDate.validator}"/>
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
</af:inputDate>
As shown, you do not need to change the date field's snippet in the JSF page, or add a
time zone attribute in the af:convertDateTime tag for this field.
The calculation of LETZ date values should be triggered when changing the value for
the Business Unit field in the user interface. The value change should invoke a method
that can calculate values according to the LETZ in the EOImpl class. In this case, this
method is the setOrgID() method, shown in Example 2135.
Example 2135 Using the setOrgID() Method
public void setOrgID(Long orgID)
{
...
// To convert the current timestamp to the LETZ, call another method
// getLEDateTime.
this.setInvoiceDate(this.getLEDateTime(orgID, this.getDBTransaction()));
}
//This method calls the PL/SQL API to get the current date and time in the LETZ.
public Date getLEDateTime(Long orgId, DBTransaction dbTransaction)
{
// 1. Define the PL/SQL block for the statement to invoke
String stmt = "begin ? := XLE_LE_TIMEZONE_GRP.Get_Le_Sysdate_Time(?,?); end;";
// 2. Create the CallableStatement for the PL/SQL block
st = (OracleCallableStatement)dbTransaction.createCallableStatement(stmt, 0);
// 3. Register the positions and types of the OUT parameters
st.registerOutParameter(1, Types.DATE);
// 4. Set the bind values of the IN parameters
st.setObject(2,"BUSINESS_UNIT_ID");
st.setObject(3,orgId);
//5. Execute Query
st.executeUpdate();
return st.getDate(1);
}
Figure 2110
In Figure 2111, the Business Unit field determines the LETZ according to which the
date fields Date and Terms Date on the right of the screenshot are converted in Oracle
Fusion Applications. Thus, the fields Date and Terms Date change according to the
Business Unit field in the Create Invoice transaction. In this case, the dates display in
the format mm/dd/yy.
Figure 2111
You need to change the tags depending on whether the field is to be calculated
according to the UPTZ or the server time zone (invariant timestamp values), for
example Default : Server Time Zone.
21-23
Formatting Numbers, Currency and Dates Using Localization Expression Language Functions
This is necessary only for invariant timestamp values. Invariant timestamp values are
timestamps in which varying time zone will not make a difference to the business logic
of the application.
Example 2137 Invariant Timestamp Values
<af:outputText label="orderDateTime" value="#{bindingToOrderDateTime}">
<af:convertDateTime pattern="#{applCorePrefs.UPTZPattern}"/>
<af:outputText>
At design time, Applications Core uses the date-time sensitive custom property to
generate bindings to the time zone attribute on the Oracle ADF Faces Date Time
Converter. The attribute is bound to the applCorePrefs managed bean.
All date time fields must be represented only by java.sql.Timestamp data types
(used by default in time zone view object attributes).
The database and middle-tier Timezone must always be the same in Oracle Fusion
Applications.
Formatting Numbers, Currency and Dates Using Localization Expression Language Functions
21.6.1 How to Format Numbers, Currency and Dates Using Expression Language
Functions
Oracle ADF Faces Expression Language functions of the type af:formatNamed and
af:format only support String objects as parameters. Consequently, other object
types such as Date and BigDecimal must be converted to the String object type.
For example, when binding the date object dateValue as shown in Example 2140, the
dateValue object must be converted to a String object by calling the toString()
method.
Example 2140 Binding a Date Object
af:formatNamed(bundle.NOTE_MESSAGE, 'BIRTHDAY', dateValue)
However, the toString() method does not support Oracle Fusion Applications user
preferences. Oracle Fusion Applications thus require the use of Expression Language
format functions to convert the following data objects to String objects:
java.math.BigDecimal
java.lang.Integer
java.lang.Long
java.sql.Date
java.sql.Timestamp
You can format numbers, currency and dates using Expression Language functions.
Returns the formatted number value using the user preferences for the number format
mask, grouping separator and decimal separator.
This function produces the tag shown in Example 2142.
Example 2142 Tag Produced by the Function fnd:formatNumber(java.lang.Number
value)
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
Returns the formatted number value using the user preferences for the number format
mask, grouping separator and decimal separator.
Working with Localization Formatting
21-25
Formatting Numbers, Currency and Dates Using Localization Expression Language Functions
Overrides the scalethe number of digits following the decimal pointof the user
preferred number format pattern using the value assigned to maxFractionDigit.
This function produces the tag shown in Example 2144.
Example 2144 Tag Produced by the Function fnd:formatNumber2(java.lang.Number
value, int maxFractionDigit)
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"
maxFractionDigits="your scale here"/>
Returns the formatted currency amount value in numeric form along with the relevant
currency code. Applications Core uses the currency code as defined in FND_
CURRENCIES to format the currencyAmount value, rather than the number format mask
preference. User preferences for grouping and decimal separators are used to format
the value.
This function produces the tag shown in Example 2146.
Example 2146 Tag Produced by the Function fnd:formatCurrency(java.lang.Number
currencyAmount, java.lang.String currencyCode)
<af:convertNumber type="currency"
currencyCode="#{bindings.quantityCurrencyCode.inputValue}"
pattern="#{fnd:currencyPattern(bindings.quantityCurrencyCode.inputValue)}"/>
fnd:formatDate(java.util.Date dateValue)
Returns the formatted date value based on the user preferred date format mask.
This function produces the tag shown in Example 2148.
Example 2148 Tag Produced by the Function fnd:formatDate(java.util.Date dateValue)
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
Use the Expression Language function shown in Example 2149 to format date time
values.
Example 2149 fnd:formatDateTime(java.util.Date dateTimeValue) Function
fnd:formatDateTime(java.util.Date dateTimeValue)
Returns the formatted date time value using the user preferences for the date and time
format masks and time zone.
This function produces the following tag as shown in Example 2150.
Example 2150 Tag Produced by the Function fnd:formatDateTime(java.util.Date
dateTimeValue)
<af:convertDateTime type="both" timeZone="#{applCorePrefs.UPTZ}"
pattern="#{applCorePrefs.UPTZPattern}"/>
Use the Expression Language function shown in Example 2151 to format date time
values with user formatting masks and the user-specified time zone.
Example 2151 fnd:formatDateTimeTZ(java.util.Date dateTimeValue, java.util.TimeZone
timeZone) Function
fnd:formatDateTimeTZ(java.util.Date dateTimeValue,
java.util.TimeZone timeZone)
Returns the formatted date time value using the user preferences for date and time
format masks and the user-specified time zone.
This function produces the tag shown in Example 2152.
Example 2152 Tag Produced by the Function fnd:formatDate(java.util.Date
dateTimeValue, java.util.TimeZone timeZone)
<af:convertDateTime type="both" timeZone="<your timezone>"
pattern="#{applCorePrefs.UPTZPattern}"/>
21.6.2 What Happens When You Format Numbers, Currency and Dates Using
Expression Language Functions
Applications Core formats the value as defined by the Expression Language function
and produces the tags described in this section.
For example, the date formatting Expression Language function produces a tag such
as the one shown in Example 2153.
Example 2153 Tag Produced by Expression Language Date Formatting Function
<af:convertDateTime pattern="#{applCorePrefs.dateFormatPattern}"/>
21.6.3 What Happens at Runtime: How Currency, Dates and Numbers and Time Zones
are Formatted Using Expression Language Functions
For more information about what happens at runtime when you format numbers,
currency and dates using Expression Language functions, see Section 21.2, Section 21.3
and Section 21.5.
21-27
placed a mirror next to your computer screen, the image in the mirror is exactly what
is expected of speakers of bi-directional languages. Some rules come into play, such as
how to correctly render English text or numerals embedded in a bi-directional script,
but this generally is handled by underlying technologies (in this case, Oracle ADF). An
example of this is that the following text, which translates to United Arab Emirates:
Here, the halign attribute for the panel group has been set to end, which means that
this component will be bi-directional compatible and will switch to its mirror image
position in the Arabic locale.
In the English locale shown in Figure 2112, the panel containing the three buttons
Advanced, Search and Reset is aligned to the right.
Figure 2112
Therefore, the expected behavior is that, in the Arabic locale shown in Figure 2113,
the panel, with the buttons' text in Arabic, is aligned to the left.
Figure 2113
21-29
Figure 2114
Figure 2115 shows how the command image link supports bi-directional behavior in
an Arabic locale. Specifically, the icon displays an arrow pointing to the left to the left
of the Search by Year field.
Figure 2115
How to use the textAndAccessKey attribute using the resource bundles is shown in
Example 2157.
Example 2157 Using the textAndAccessKey Attribute Using Resource Bundles
<af:commandButton id="commandButton2"
textAndAccessKey="#{TemporaryBundle.SAVE}"
actionListener="#{bindings.Commit.execute}"/>
Here, the resource bundle TemporaryBundle must be defined in the JSF page
containing the af:commandButton tag. Also, the textAndAccessKey has been
externalized and is read from the applCore bundle and the resource bundle , as shown
in the examples, which is the correct way to define mnemonic keys. The values for this
particular id SAVE in the resource bundles are "Save" in the English locale,
"\uC800\uC7A5(&S)" in the Korean locale (S is the access key) and
"\u062D\u0641&\u0638" (\u0638 is the access key) in the Arabic locale.
Example 2158 shows how to externalize the accessKey attribute using the
applCoreBundle.
Example 2158 Externalizing the accessKey Attribute Using the applCoreBundle
<af:commandToolbarButton text="#{applCoreBundle.SAVE_AND_CLOSE_SHORT_DESC}"
id="ctb1"
actionListener="#{BillingCycleBean.saveAndClose}"
accessKey="#{applCoreBundle.ACCESSKEY}">
Example 2159 shows how to externalize the accessKey attribute using a resource
bundle.
21-31
Here, the accessKey attribute has been externalized and is read from the Applications
Core bundle and the resource bundle as shown in the examples. Note that the
TemporaryBundle has to be defined as the viewControllerBundle in the JSF page
containing the command button. The values for this particular resource ID ACCESSKEY
are "S" in the English locale, ""\uC800" in the Korean locale and "\u0638" in the Arabic
locale, as defined in the resource bundle.
Notes:
In Figure 2116, the buttons on the top right (Run Validations, View Exceptions, Open
Target Period) are examples of buttons with soft keys that must not be hardcoded, so
that they can change for different locales.
Figure 2116
Number and date/time values are formatted based on the format pattern specified
by the styles in the Excel spreadsheets. The format pattern follows Microsoft
standard instead of Java standard.
Number separators are decided by the client operating system locale.
In ADF Faces pages, number and date/time values are formatted based on the format
patterns selected in the Oracle Fusion application's Preference UI. Number separators
are extracted from the application's number format patterns.
Right-click the style name and select Modify from the context menu.
Select the Number tab and select the Number category. Specify the number of
decimal places and the format of negative numbers according to your business
logic. If you want to see a grouping separator in the number values, select Use
1000 Separator.
Click OK and save the Excel file.
Integer Formatting
Integer formatting is the same as decimal formatting except no fractional digit should
display. This can be done by specifying 0 for Decimal places when modifying the style.
ID Formatting
An ID value is a sequence of digits, such as an Invoice Number, Service Request ID, or
Bank Account. Displaying ID values should not vary based on a user's preference or
client OS locale. That is, ID values should be printed as text instead of numbers.
In Oracle Fusion applications, the length of an ID value typically is 13 or 18. By
default, Excel formats such long numbers with Scientific Notation format, which is not
desired for Oracle Fusion applications. For instance, an Invoice Number
1234567890123 (13 digits) is displayed as 1.23457E+12. It is not a valid Invoice Number
when it is printed out.
To avoid the default formatting of Excel in such cases, developers need to customize
the styles for ID values.
Right-click the style name and select Modify from the context menu.
21-33
Click Format.
Click OK. In the Style dialog, Figure 2117 shows that @ is defined as the Number
style.
Figure 2117
Figure 2118
Define styles for each type of cells and configure the cell appearance using the Oracle
Fusion Applications UI standard.
Follow these steps to modify an existing style for formatting currency values and
apply it to the corresponding cells.
In Excel, select Home > Cell Styles, right-click the style name and select Modify
from the context menu.
Click Format.
Select the Number tab and select the Currency category. Specify the number of
Decimal places and the format of negative numbers according to your business
logic.
In Oracle Fusion Applications, display the currency symbol in a separate cell.
From the Symbol dropdown list, select None.
Click OK and save the file.
21-35
Right-click the style name and select Modify from the context menu.
Click Format.
Select the Number tab and select the Date category. Set the value of Locale
(location) to your Windows OS locale. For example, if you are using English
Windows XP, this Locale should be set to English (U.S.).
Select a type beginning with an asterisk (*), as shown in Figure 2119. There are
two such types: one is a short date format, and the other is a long date format.
Choose one according to your business requirement.
Figure 2119
Note that date formats display date and time serial numbers as date values. Date
formats that begin with an asterisk (*) respond to changes in regional date and
time settings that are specified for the operating system. Formats without an
asterisk are not affected by operating system settings.
Right-click the style name and select Modify from the context menu.
Click Format.
Select the Number tab and select the Time category. Set the value of Locale
(location) to your Windows OS locale. For example, if you are using English
Windows XP, this Locale should be set to English (U.S.).
Select the type beginning with an asterisk (*), as shown in Figure 2120.
Figure 2120
Note: With current ADF Desktop Integration support, it is impossible to display both
the date and the time part of a timestamp value in a single cell if you want to see its
format varying according to client OS locale.
Workaround
To display the date and time, formatted according to the client OS locale, you can use
two cells: One for displaying the date part and another for displaying the time part of
the timestamp. Then format each of these cells separately as described for date and
time format.
21.9.3.2 What Happens When You Format the Date and Timestamp
When dragging and dropping a binding to generate the components in an ADF
Desktop Integration spreadsheet, the framework generates default styles for those
values based on the Java type of the values. However, these styles may not be correct
for formatting number values. Therefore, you may need to refine the styles according
to business logic.
21.9.3.3 What Happens at Runtime: How Date and Timestamp Are Formatted
At runtime, ADF Desktop Integration will pass the style specified in the unpublished
spreadsheet (the design time file) to the published spreadsheet during the publication
process. When a user opens the published spreadsheet, Excel formats the date or
timestamp values according to the combination of styles and the client OS locale.
For timestamp values, time zone conversion also happens at runtime. See
Section 21.9.3.4, "Honoring Time Zones" for more details.
21-37
Applications server, called the server time zone. The other is the time zone of the client
system on which the ADF Desktop Integration spreadsheet is open, which is called the
client time zone.
At runtime, conversion between server time zone and client time zone happens
automatically for timestamp values in ADF Desktop Integration spreadsheets.
For example, if the server time zone is (GMT-8:00) Pacific Time (US & Canada) and the
client time zone is (GMT+8:00) Beijing, Chongqing, Hong Kong, Urumqi, the
timestamp value in the database 2011-05-22 20:00:00 is converted to 2011-05-23 12:00:00
at runtime and displayed as 2011-05-23 or 12:00:00 in the ADF Desktop Integration
spreadsheet, depending on the format style defined for the corresponding cells.
Note:
Figure 2121
Follow these steps to format a number value in graphs in Oracle BI Publisher reports
To set format masks for graphs, an Oracle Fusion application Oracle BI Publisher
report designer needs to change the RTF template graph code manually.
Edit the graph and change the graph definition code in the Advanced tab of the
Graph dialog in the template builder.
Use an XSLT format such as:
<xsl:value-of select="xdoxslt:xdo_format_number($_
XDOXSLTCTX,current-group()/SGT_NUMBER,'XDODEFNUM')" />
to format a currency value on the graph.
At runtime, XDODEFNUM is replaced with the number format pattern selected in the
Oracle Fusion application Preferences UI. Consequently, the number is formatted with
the Oracle Fusion application number format pattern. For example, if a user selects
-1'234,567 as the Number Format in the Preferences UI, as shown in Figure 2122, the
number 1000.8888 (one thousand point eight eight eight eight) is displayed as
1'000,889 in the Oracle BI Publisher report.
21-39
Figure 2122
When using XDODEFNUM as the format mask in format-number, the format of the
number is fully controlled by the Oracle Fusion application Number Format, including
grouping separator, decimal separator, number of fractional digit, and form of
negative numbers.
In the Oracle BI Publisher and Oracle Fusion application integration environment, if
format-number is used to format a number, whether XDODEFNUM is used as the
format mask, the grouping separator and decimal separator are always derived from
the Oracle Fusion application Number Format.
Therefore, an integer could be formatted as:
<?format-number:fieldName; '999G999'?>
In this case, if the Number Format is -1'234,567, the integer 10000 is displayed as 10'000
in the Oracle BI Publisher report.
If you do not wish to display a number with fractional digits or grouping separators
(such as PO numbers, Bank Accounts, or Invoice Numbers), enter <?fieldName?> in
step 4 of [To format numbers]. In such cases, the Number Format has no effect on the
field; it always is displayed as text.
Amount_Field takes the tag name of the XML element that holds the amount
value in your data.
CurrencyCode can be set to a static value or it can be set dynamically. If the value
will be static for the report, enter the ISO three-letter currency code in
single-quotes, such as 'USD'.
To set the value dynamically, enter the tag name of the XML element that holds the
ISO currency code. An element containing the currency code must be present in the
data.
At runtime, the Amount_Field will be formatted according to the format you set
up for the currency code in the report properties.
To use the format-currency function, the currency values in your data source must be
in a raw format, with no formatting applied (for example: 1000.00). If the value has
been formatted for European countries (for example: 1.000,00), the format will not
work.
To format your currency values with the currency code passed dynamically from a
particular business flow, you must have the currency code defined in your data source.
In the Oracle Fusion application and Oracle BI Publisher integration environment,
Currency is passed to Oracle BI Publisher through XDODEFCC. For example, if US
Dollar is selected for Currency in Preferences, as shown in Figure 2123, at runtime,
XDODEFCC is replaced with USD.
Figure 2123
Therefore, to format a currency value with the Currency selected in Oracle Fusion
application Preferences, you can use:
<?format-currency:Amount_Field; 'XDODEFCC'?>
or
<?format-currency:Amount_Field; 'XDODEFCC';'true'?>
To format currency values with the currency code selected in a particular business
flow instead of the Currency code selected in Oracle Fusion application Preferences,
you can use:
<?format-currency:Amount_Field; CurrencyCode_Field?>
or
<?format-currency:Amount_Field; CurrencyCode_Field;'true'?>
21-41
where CurrencyCode_Field is the tag name of the XML element that holds the
currency code selected in the business flow. At runtime, CurrencyCode_Field is
replaced with a currency code, such as USD, JPY, or EUR.
Note: Whether the currency code is set to a static value, such as XDODEFCC, or a
dynamic value passed from a particular business flow, the grouping separator and
decimal separator in currency values are always derived from the Number Format
selected in Oracle Fusion application Preferences. The parameter currency code in the
format-currency function controls the number of fraction digits and the placement of
the grouping separator in the output.
Example
Assume that <?format-currency:Amount_Field; CurrencyCode_Field?> is applied in
the RTF template for a currency field.
In the report properties, if the format mask for USD is 9G999D99, for JPY it is 9G999
and for INR it is 9G99G99G999D99, and if a user has set the Number Format as
-1,234.567 in Preferences (uses comma (,) as the grouping separator and dot (.) as
decimal separator), the currency value of 1234567.89 will display as shown here,
depending on the currency passed to CurrencyCode Field at runtime.
If a European user changes the Number Format to -1'234,567 in Preferences (uses the
apostrophe (') as the grouping separator and comma (,) as the decimal separator), the
currency value of 1234567.89 will display as:
Follow these steps to format a currency field in the Oracle BI Publisher RTF template.
Figure 2124
Follow these steps to format a currency value in graphs in Oracle BI Publisher reports
To set format masks for graphs, an Oracle Fusion application Oracle BI Publisher
report designer needs to change the RTF template graph code manually.
Edit the graph and change the graph definition code in the Advanced tab of the
Graph dialog in template builder.
Use an XSLT format, such as <xsl:value-of select="xdoxslt:xdo_format_
currency($_XDOXSLTCTX,current-group()/SGT_CURRENCY,'XDODEFCC')" /> to
format a currency value on the graph.
To use the format-date function, the date from the data source must be in canonical
format, which is YYYY-MM-DDThh:mm:ss+HH:MM
where:
MM is the month
DD is the day
mm is the minutes
21-43
ss is the seconds
+HH:MM is the time zone offset from Universal Time (UTC), or Greenwich Mean
Time
Note:
Figure 2126
Follow these steps to format date or timestamp values in graphs in Oracle BI Publisher
reports.
To set format masks for graphs, an Oracle Fusion application Oracle BI Publisher
report designer needs to change the RTF template graph code manually.
Edit the graph and change the graph definition code in the Advanced tab of the
Graph dialog in template builder.
Use an XSLT format such as <xsl:value-of select="xdoxslt:xdo_format_
date($_XDOXSLTCTX,current-group()/SGT_DATE,'XDODEFDATE XDODEFTIME')" />
to format a date-time value on the graph.
If you do not wish to format date or timestamps according to the Oracle Fusion
application Date or Time format, you can use Oracle abstract format masks, such as:
<?format-date:ORDER_DATE;'SHORT'?>
<?format-date:ORDER_DATE;'LONG'?>
<?format-date:xdoxslt:sysdate_as_xsdformat();'MEDIUM'?>
21-45
With using abstract format masks, date and timestamp values are formatted according
to the default format of the Oracle Fusion application user's locale.
Note:
In Figure 2127, numbers such as 20,000 and 40,000 on the Y axis and numbers such as
12,003.67 on the tooltip are examples of numbers on an area graph that should be
formatted according to the user's number preferences in graphs in Oracle Fusion
applications.
Figure 2127
Generally, an attribute on an ordinal axis (O1 axis and X1 axis) of a graph in ADF Data
Visualization is considered to be text, irrespective of its data type in the model or view
layer. A developer can add af:convertNumber to such a view attribute by first adding
dvt:attributeFormat to it, and only then will the resultant values on the x-axis and
o-axis be formatted according to the user's number preferences. The name="size" entry
refers to the categorical attribute (attribute on the ordinal/x axis). To format the
integers, use pattern="#{applCorePrefs.integerFormatPattern}", as shown in
Example 2161.
Example 2161 Area Graph O Axis Formatting
<dvt:attributeFormat id="af1" name="size">
<af:convertNumber pattern="#{applCorePrefs.numberFormatPattern}"/>
</dvt:attributeFormat>
In Figure 2128, numbers such as 2234 and 1014 are examples of numbers on the O
axis of an area graph that should be formatted according to the user's number
preferences.
21-47
Figure 2128
Using af:convertNumber for Number Formatting and dvt:attributeFormat for Text Formatting
Is dvt:attributeFormat Needed
for Number Formatting?
Graph Type
Bar Graph
<dvt:y1TickLabel>, <dvt:y2TickLabel>,
<dvt:y1Format>, and <dvt:y2Format>
Bar Horizontal
<dvt:y1TickLabel>, <dvt:y2TickLabel>
,<dvt:y1Format>, and <dvt:y2Format>
Bubble Graph
<dvt:x1TickLabel>, <dvt:y1TickLabel>,
<dvt:y2TickLabel>, <dvt:x1Format>,
<dvt:y1Format>, <dvt:y2Format> and
<dvt:zFormat>
Combination graph
<dvt:y1TickLabel>, <dvt:y2TickLabel>,
<dvt:y1Format>, and <dvt:y2Format>
Funnel Graph
<dvt:sliceLabel>
Line Graph
<dvt:y1TickLabel>, <dvt:y2TickLabel>,
<dvt:y1Format>, and <dvt:y2Format>
Pareto Graph
Pie Graph
<dvt:sliceLabel>
Gantt Chart
<af:column>
Gauge
In Figure 2129, number values such as 40,000.00 and 80,000.00 on the Y axis, and
13,344.22 on the tooltip, are examples of number fields in an area graph that should be
formatted according to the currency code for these values. Numbers on the O1 axis
should also be formatted according to the currency code. (In this case, for USD, the
format is #,##0.00.)
21-49
Figure 2129
Using af:convertNumber for Currency Formatting and dvt:attributeFormat for Text Formatting
Tags in which af:convertNumber Can
Be Added for Currency Formatting
Graph Type
Bar Graph
<dvt:y1TickLabel>, <dvt:y2TickLabel>,
<dvt:y1Format>, and <dvt:y2Format>
Yes
Bar Horizontal
<dvt:y1TickLabel>, <dvt:y2TickLabel>,
<dvt:y1Format>, and <dvt:y2Format>
Yes
Bubble Graph
<dvt:x1TickLabel>, <dvt:y1TickLabel>,
<dvt:y2TickLabel>,<dvt:x1Format>,
<dvt:y1Format>, <dvt:y2Format> and
<dvt:zFormat>
Yes
Funnel Graph
<dvt:sliceLabel>
Line Graph
<dvt:y1TickLabel>, <dvt:y2TickLabel>,
<dvt:y1Format>, and <dvt:y2Format>
Yes
Pareto Graph
<dvt:y1TickLabel>,
<dvt:y2TickLabel>,and <dvt:y1Format>
Yes
Pie Graph
<dvt:sliceLabel>
Gantt Chart
<af:column>
No
Gauge
No
<af:inputText>/<af:outputText> whose
parent tag is <dvt:dataCell>
<af:inputText>/<af:outputText> whose
parent tag is <dvt:headerCell>
21.11.4 How to Format Dates and Timestamp Values in ADF Data Visualization
All date values on a graph need to be formatted correctly when they are presented to a
user. Users expect that they can input values according to their date formatting
preferences. For instance, a value of 13th August, 2011 in the database might have to
be displayed as 08/13/2011 for a certain user. A similar example of a date-time value
is that a value of 26th July 2011, 2:00:00 PM might have to be displayed as 14:00
07/26/2011.
Notes:
21-51
This is the same as the case of ADF Faces, in which the UPTZPattern is used to format
timestamp values and dateFormatPattern is used to format date values.
In Figure 2130, dates such as 2/1/2015 on the O1 axis and 8/9/2009 on the tooltip are
examples of date fields on an area graph that should be formatted according to the
user's date formatting preferences.
Figure 2130
Graph Type
Is dvt:attributeFormat Required?
Bar Graph
Yes
Bar Horizontal
Yes
Bubble Graph
Yes
Combination Graph
Yes
Funnel Graph
Line Graph
Yes
Pareto Graph
Yes
Pie Graph
Yes
Yes
Gantt Chart
Gauge
N/A
regional or territorial number and date formats. Typically, to support a given language,
only the customer-facing components of the software (user interface, lookup tables,
online documentation, and so on) are translated. Translations are delivered via NLS
patches.
Session Attribute
Profile
Values
Comments
LANGUAGE
FND_LANGUAGE
NLS_LANG
NLS_LANGUAGE
NLS_SORT
FND_NLS_SORT
FND_DATE_FORMAT
21-53
Profile
Values
TIME_FORMAT
FND_TIME_FORMAT
Comments
from FND_LOOKUPS
where LOOKUP_TYPE = 'TIME_FORMAT'
and ENABLED_FLAG = 'Y'
and SYSDATE between START_DATE_
ACTIVE and nvl(END_DATE_ACTIVE,
SYSDATE+1);
GROUPING_
SEPARATOR
FND_GROUPING_
SEPARATOR
DECIMAL_SEPARATOR FND_DECIMAL_
SEPARATOR
CURRENCY
FND_CURRENCY
Profile
Values
Comments
TERRITORY
FND_TERRITORY
TIMEZONE
FND_TIMEZONE
CLIENT_ENCODING
FND_CLIENT_
ENCODING
Table 215 lists language and territory values used with NLS attributes.
Table 215
ISO_
LANGUA
GE_3
ar
AE
AR8ISO8859P6
ara
BULGARIA
bg
BG
CL8ISO8859P5
bul
CATALAN
CATALONIA
ca
CT
WE8ISO8859P1
cat
30
CZECH
CZECH
REPUBLIC
cs
CZ
EE8ISO8859P2
ces
GERMAN
GERMANY
de
DE
WE8ISO8859P1
deu
da
DK
DANISH
DENMARK
da
DK
WE8ISO8859P1
dan
es
11
SPANISH
SPAIN
es
ES
WE8ISO8859P1
spa
eg
EG
118
EGYPTIAN
EGYPT
eg
EG
AR8ISO8859P6
egy
el
EL
104
GREEK
GREECE
el
GR
EL8ISO8859P7
ell
es-US
ESA
29
LATIN
AMERICAN
SPANISH
AMERICA
es
US
WE8ISO8859P1
spa
fr
FRENCH
FRANCE
fr
FR
WE8ISO8859P1
fra
fr-CA
FRC
CANADIAN
FRENCH
CANADA
fr
CA
WE8ISO8859P1
fra
en-GB
GB
ENGLISH
UNITED
KINGDOM
en
GB
WE8ISO8859P1
eng
NLS_
ISO_
TERRITORY LANGUAGE
ar
AR
ARABIC
UNITED
ARAB
EMIRATES
bg
BG
101
BULGARIAN
ca
CA
102
cs
CS
de
21-55
NLS_
ISO_
TERRITORY LANGUAGE
ISO_
TERRIT
ORY
NLS_CODESET
ISO_
LANGUA
GE_3
hr
HR
103
CROATIAN
CROATIA
hr
HR
EE8ISO8859P2
hrv
hu
HU
28
HUNGARIAN
HUNGARY
hu
HU
EE8ISO8859P2
hun
it
108
ITALIAN
ITALY
it
IT
WE8ISO8859P1
ita
is
IS
106
ICELANDIC
ICELAND
is
IS
WE8ISO8859P1
isl
he
IW
107
HEBREW
ISRAEL
he
IL
IW8ISO8859P8
heb
ja
JA
15
JAPANESE
JAPAN
ja
JP
JA16EUC
jpn
ko
KO
16
KOREAN
KOREA
ko
KR
KO16KSC5601
kor
lt
LT
109
LITHUANIAN
LITHUANIA
lt
LT
NEE8ISO8859P4
lit
no
10
NORWEGIAN
NORWAY
no
NO
WE8ISO8859P1
nor
nl
NL
DUTCH
THE
NETHERLAND
S
nl
NL
WE8ISO8859P1
nld
pl
PL
110
POLISH
POLAND
pl
PL
EE8ISO8859P2
pol
pt
PT
18
PORTUGUESE
PORTUGAL
pt
PT
WE8ISO8859P1
por
pt-BR
PTB
26
BRAZILIAN
PORTUGUESE
BRAZIL
BR
WE8ISO8859P1
por
ro
RO
111
ROMANIAN
ROMANIA
ro
RO
EE8ISO8859P2
ron
ru
RU
112
RUSSIAN
RUSSIA
ru
RU
CL8ISO8859P5
rus
sv
13
SWEDISH
SWEDEN
sv
SE
WE8ISO8859P1
swe
fi
SF
FINNISH
FINLAND
fi
FI
WE8ISO8859P1
fin
sk
SK
113
SLOVAK
SLOVAKIA
sk
SK
EE8ISO8859P2
slk
sl
SL
114
SLOVENIAN
SLOVENIA
sl
SI
EE8ISO8859P2
slv
th
TH
115
THAI
THAILAND
th
TH
TH8TISASCII
tha
tr
TR
116
TURKISH
TURKEY
tr
TR
WE8ISO8859P9
tur
en
US
AMERICAN
AMERICA
en
US
US7ASCII
eng
zh-CN
ZHS
14
SIMPLIFIED
CHINESE
CHINA
zh
CN
ZHS16CGB231280
zho
zh-TW
ZHT
117
TRADITIONAL
CHINESE
TAIWAN
zh
TW
ZHT16BIG5
zho
sq
SQ
67
ALBANIAN
ALBANIA
sq
AL
EE8ISO8859P2
sqi
vi
VN
43
VIETNAMESE
VIETNAM
vi
VN
VN8MSWIN1258
vie
id
IN
46
INDONESIAN
INDONESIA
id
ID
WE8ISO8859P1
ind
The parameters TO_NUMBER, TO_DATE, TO_TIMESTAMP and TO_CHAR are used to format
and parse SQL or PL/SQL statements. These parameters are based on constant values,
the canonical format. The parameter FND_DATE for PL/SQL packages also works with
the canonical format. Formatting and parsing should be done at the presentation,
rather than the model layer.
Oracle Fusion Applications session management controls database session parameters.
As such, the database NLS session parameter values must not be altered.
Table 216 lists the following:
Table 216
Update: The ALTER SESSION updates when the session attaches, or whenever
an associated attribute value changes mid-session.
Never: An ALTER SESSION is not created, and the default database value is
unchanged.
Database Attribute
Default Value
Alter Session
Comments
NLS_CALENDAR
None
Never
NLS_COMP
None
Never
NLS_CURRENCY
None
Never
NLS_DATE_FORMAT
YYYY-MM-DD
Create
Fixed value.
NLS_DATE_LANGUAGE
Create
NLS_ISO_CURRENCY
None
Never
NLS_LANGUAGE
None
Update
NLS_TERRITORY
AMERICA
Create
NLS_LENGTH_SEMANTICS
CHAR
Create
NLS_NCHAR_CONV_EXCP
None
Never
21-57
Default Value
Alter Session
Comments
NLS_NUMERIC_CHARACTERS
,.
Create
NLS_SORT
None
Update
NLS_TIME_FORMAT
HH24:MI:SS.FF
Create
NLS_TIME_TZ_FORMAT
HH24:MI:SS.FF TZR
Create
NLS_TIMESTAMP_FORMAT
YYYY-MM-DD
HH24:MI:SS.FF
Create
Create
Never
NLS_TIMESTAMP_TZ_FORMAT YYYY-MM-DD
HH24:MI:SS.FF TZR
None
NLS_DUAL_CURRENCY
Note:
After dragging and dropping a view object onto a JSF page, the Oracle ADF tags
for that view object are set. If you change the attributes of the view object after you
create the JSF page, new Oracle ADF tags are not created. You must make these
changes manually by editing the tags.
You can change tags generated by Applications Core at design time by editing
them manually.
Part IV
Part IV
22
Getting Started with Flexfields
22
This chapter discusses the basics of using flexfields to enable customers to add custom
attributes to a business object in an Oracle Fusion application.
This chapter includes the following sections:
2.
See the Implementing Common Features guides for your product family.
Introduction to Flexfields
There are three types of flexfields, all of which enable implementors to configure
application features without programming. These configurations are fully supported
within Oracle Fusion Applications:
The number of configurable segments is not fixed. That is, the number of
segments is extensible.
Key: A key flexfield enables customers to use their own coding scheme or naming
scheme to identify their business entities by giving implementors the ability to
configure the business entities to be identified using flexible, multipart, intelligent
key codes. Each element (segment) of the key may be individually meaningful, as
well as the combination as a whole. For example, key flexfields might represent
part numbers and account numbers. Key flexfields are never optional; customers
must configure them for their Oracle Fusion applications to operate correctly.
For more information, see Section 22.1.3, "Key Flexfields."
Introduction to Flexfields
database columns on which segments are based can be reused in as many contexts
as desired. For example, an implementor can define a Dimensions context, which
uses three of the flexfield's database columns of type NUMBER for the height, width,
and depth segments. The implementor can also define a Measurements context,
which reuses those database columns for weight, volume, and density segments.
A descriptive flexfield segment that stores data that is
applicable to all entities, regardless of context, is referred to as a global
segment.
Note:
Even if implementors never change a flexfield after it has been configured, they can
take advantage of useful flexfield features such as automatic segment validation,
automatic segment cross-validation, multiple segment structures, and more.
Introduction to Flexfields
For more information about customer and developer flexfields, see Section 22.1.1,
"Descriptive Flexfields."
Participant Roles
2.
See the Implementing Common Features guides for your product family.
The owner is the developer (or development team) who determines that a particular
flexfield is needed or would be useful within a particular Oracle Fusion application,
and makes a flexfield of the appropriate design available. The owner then incorporates
the flexfield into an application. With key flexfields, the owner can be either a
producer or a consumer, or can assume both roles.
Getting Started with Flexfields 22-5
Producer: The flexfield producer is the developer who determines that a particular
flexfield is needed or would be useful within a particular application, and makes
available a flexfield of the appropriate design. With key flexfields, the producer's
product owns the combinations table for that flexfield, which is described in
Section 25.2.1.1, "Creating the Combinations Table."
Consumer: A key flexfield consumer incorporates a flexfield into an application.
The consumer typically stores a segment value or combination ID (CCID) on a
product database table, and works with the structural and seed data and the
business components that have been configured by the flexfield producer.
Implementor
2.
Create business components for the flexfield. For key flexfields, also create
business components for the key flexfield combination filters as described in
Section 26.4, "Working with Code-Combination Filters for Key Flexfields."
3.
For descriptive and key flexfields, link the flexfield business components to the
application's business components.
4.
5.
6.
Use the Tester role of the Create Flexfield Business Components wizard to create a
model that you can use to test the flexfield.
7.
Optionally, share the flexfield business components with other developers using
an Oracle Application Development Framework (Oracle ADF) library.
After you have completed the flexfield development process and delivered the
application, implementors can use the Manage Flexfields task flows to configure each
flexfield. These task flows determine how the flexfield's segments will be populated,
organized, and made available to end users within the application.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
Note:
Form layout: A typical label/prompt and either view-only data or a widget (text
field, choice list, and so on) that allows an end user to enter values.
Tabular layout: A column of information in a table, where the label of the flexfield
segment is the column header, and the values are within each cell of the column.
All segments of a single flexfield are grouped together by default. The layout of the
form or table and the positions of the flexfield segments depend on where you place
the flexfield on the page. Flexfields may also be presented in a separate section of the
page, alone in a table, or on their own page.
23
Using Descriptive Flexfields
23
This chapter discusses how to use descriptive flexfields to enable customers to add
additional attributes to business objects in their Oracle Fusion applications.
This chapter includes the following sections:
Section 23.5, "Nesting the Descriptive Flexfield Application Module Instance in the
Application Module"
Section 23.6, "Adding a Descriptive Flexfield View Object to the Application
Module"
context-sensitive segments are for custom attributes that apply to certain entity rows
based on the value of a context segment.
To learn more about flexfield basics and terms, including developer and implementor
roles, global segments, context-sensitive segments, and context segments, see
Chapter 22, "Getting Started with Flexfields."
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
As the developer, you can define multiple usages for a descriptive flexfield. For
example, you might have defined an address flexfield that the implementor may use
to add attributes related to addresses. The implementor can define context-sensitive
segments for the address that are based on a certain attribute, such as country code.
You can reuse the address flexfield with any table for which you need address
information, and the implementor needs to configure the flexfield only once.
To learn more about developer and implementor roles, see Section 22.2, "Participant
Roles".
To complete the development tasks for descriptive flexfields:
1.
Create the extension columns to store the flexfield data, and then register the
flexfield definition, usage, and parameter metadata.
See Section 23.2, "Developing Descriptive Flexfields".
2.
Tip:
Create view links between the descriptive flexfield business components and the
application's business components.
See Section 23.4, "Creating Descriptive Flexfield View Links".
4.
5.
Add an instance of the descriptive flexfield view object to the application module.
See Section 23.6, "Adding a Descriptive Flexfield View Object to the Application
Module".
6.
7.
8.
Load any necessary application seed data, such as error messages or lookup
values.
See Section 23.10, "Loading Seed Data."
After implementing a flexfield, you can define seed or test configurations for the
flexfield, and then test it. For more information, see Section 27.1, "Introduction to
Testing and Deploying Flexfields."
After you have completed the flexfield development process and delivered your
application, implementors can use the Manage Descriptive Flexfields task flows to
define context values and to configure the segments for each flexfield. These task flows
determine how the flexfield's segments will be populated, organized, and made
available to end users within the application.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
Note:
For more information about polymorphic view rows, see the "Working with
Polymorphic View Rows" section in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
Note: Because flexfield view objects are modeled as polymorphic
view objects, you can use descriptive flexfield view objects in the same
manner that you use any other polymorphic view objects, and they
will behave in the same way. This includes support for flexfields in
ADF Desktop Integration. For more information, see Section 23.15,
"Accessing Descriptive Flexfields from an ADF Desktop Integration
Excel Workbook" and the Oracle Fusion Middleware Desktop Integration
Developer's Guide for Oracle Application Development Framework.
2.
Register the flexfield and define its metadata and primary usage.
3.
Register the entity details and parameters for the primary usage.
4.
Optionally reuse the flexfield by adding the same set of extension columns to
other product tables.
5.
The context column, which is required, must be of type VARCHAR2. The context
column's length determines the maximum length of the context codes that can be
created by implementors when they configure the flexfields.
Each implementor can configure as many of the segment columns as the end user
requires and can choose whether to use the context column.
You must use the Database Schema Deployment Framework tools to create the
product table and columns. Using these tools ensures that the table and its columns
are registered in the Oracle Fusion Middleware Extensions for Applications
(Applications Core) data dictionary. For more information, see Chapter 58, "Using the
Database Schema Deployment Framework."
Descriptive Flexfields. Typically, this option is used for developer flexfields. Note
that you must use the APIs to do this step. For information, see Section 23.2.2.2,
"Using the Setup APIs To Register and Define Descriptive Flexfields."
Define the primary usage. The primary usage is the first usage that you define for
a flexfield.
Define the product table column to be used for the context segment. The product
table that is used for the primary usage is called the primary table.
Define the product table columns to be used for the flexfield segments.
There are two ways in which you can define a descriptive flexfield:
Using the Flexfield Registration Metadata wizard. If you use the wizard, you also
define the entity details for the primary usage and you define the parameters.
Using the setup APIs in the FND_FLEX_DF_SETUP_APIS PL/SQL package.
23.2.2.1 Using the Flexfield Registration Metadata Wizard To Register and Define
Descriptive Flexfields
You can use the Register new flexfield operation from the Flexfield Registration
Metadata wizard to register and define a descriptive flexfield.
Tip: To make subsequent flexfield additions and changes, you can
use the Edit flexfield operation from the Flexfield Registration
Metadata wizard.
Before you begin:
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Registration Metadata, and click OK.
3.
4.
On the Basic Information page, select Descriptive Flexfield from the Type
dropdown list, as shown in Figure 232.
5.
Application: Select the application name that has been assigned for the
product area.
Module: Select the module that owns the flexfield. This is typically the
application or logical business area (LBA) with which the flexfield is delivered.
Delimiter: Select the character to be displayed between flexfield segments,
when the segments are displayed in a concatenated format.
Enable Business Intelligence: (Optionally) Select the checkbox to enable the
flexfield for Oracle Business Intelligence. For more information, see
Section 23.13, "Preparing Descriptive Flexfield Business Components for
Oracle Business Intelligence."
6.
Click Next.
7.
On the Primary Table page, set the following values to define the primary usage
for the flexfield, as shown in Figure 233.
Base Table: Enter or select the name of the database table that contains the
columns to be used as flexfield segments.
Table Usage Code: Type a code that uniquely identifies the flexfield usage. For
the primary usage, this is typically the same code as the flexfield code.
Table Usage Name: Type a descriptive name for the flexfield usage.
8.
From the Context Column dropdown list, select the database column that you
want to map to the flexfield's context segment. The column must be of type
VARCHAR2.
Tip: The context segment database column is typically named
ATTRIBUTE_CATEGORY.
9.
In the Available list in the Segment Columns region, select the database columns
that you want to map to flexfield segments and move them to the Selected list.
based and move them to the Selected list, as shown in Figure 234.
Figure 234 Flexfield Registration Metadata Wizard Entities Page
12. Select each entity object from the Selected list and provide the following values:
Object Name Prefix: Enter a short unique name for the flexfield usage. For
example, PartsDFF. This prefix is used to derive the names of objects that are
generated for the flexfield usage.
Package Name: Specify the name of the root package to be used for the
generated business components that model the flexfield usage.
BI Flattened Fact Name: If the flexfield is enabled for Oracle Business
Intelligence and you know the Oracle Business Intelligence object that this
flexfield usage should be mapped to when the flexfield is imported into Oracle
Business Intelligence, specify the name of the object.
For more information about Oracle Business Intelligence, see Section 23.13,
"Preparing Descriptive Flexfield Business Components for Oracle Business
Intelligence."
attributes that can be used to pass external reference data to flexfield segments, as
shown in Figure 235. For information about parameters, see Section 23.2.6, "How
to Register Descriptive Flexfield Parameters."
Figure 235 Flexfield Registration Metadata Wizard Parameters Page
15. On the Summary page, optionally select Extract seed data for the flexfield to
create a seed data file for uploading the registration information into other
implementations. For more information, see Section 23.10, "Loading Seed Data."
16. If you are ready to create business components for the flexfield, select Launch
23.2.2.2 Using the Setup APIs To Register and Define Descriptive Flexfields
You can define and register a descriptive flexfield using procedures from the FND_
FLEX_DF_SETUP_APIS PL/SQL package. This package also has procedures for
updating, deleting, and querying flexfield definitions.
To learn how to access documentation about using the FND_FLEX_DF_SETUP_APIS
PL/SQL package, see Section 23.2.2.2.1, "What You May Need to Know About the
Descriptive Flexfield Setup API."
Before you begin:
1.
2.
3.
23.2.2.2.1 What You May Need to Know About the Descriptive Flexfield Setup API In the
descriptive flexfield development process, use the FND_FLEX_DF_SETUP_APIS PL/SQL
package to manage flexfield registration metadata.
You can learn about the FND_FLEX_DF_SETUP_APIS PL/SQL package by running the
following command, which stores package documentation and usage examples in the
<db_name>_<user_name>_FND_FLEX_DF_SETUP_APIS_<date>.plsqldoc file.
sqlplus <fusion_user>/<fusion_pwd>@<fusion_db> \
@/ORACLE/fusionapps/atgpf/applcore/db/sql/flex/fnd_flex_pkg_doc.sql \
FND_FLEX_DF_SETUP_APIS
23-11
There are two ways in which you can register a secondary usage:
Using the Flexfield Registration Metadata wizard. If you use the wizard, you also
define the entity details for the secondary usage.
Using the setup APIs in the FND_FLEX_DF_SETUP_APIS PL/SQL package.
2.
3.
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Business Components, and click OK.
3.
4.
On the Select Usage page, select Descriptive from the Type dropdown list, as
shown in Figure 236.
5.
To display available usages, provide a value for Application, Code, or Table. You
can use a wildcard character, such as a percent sign (%), to match on similar values.
6.
Select the primary usage of the flexfield for which you want to create the
secondary usage, and then click Next.
7.
On the Basic Information page, review the information about the primary usage,
and then click Next.
8.
On the Secondary Table page, set the following values to define the secondary
usage for the flexfield, as shown in Figure 237.
Table Usage Code: Type a code that uniquely identifies the secondary usage.
Table Usage Name: Type a descriptive name for the flexfield usage.
Column Name Prefix: If you used a prefix for the flexfield column names,
enter the prefix.
23-13
9.
Click Next.
10. On the Entities page, select the entity objects for the secondary table and move
Object Name Prefix: Enter a short unique name for the secondary usage. For
example PartsDFFIntf. This prefix is used to derive the names of objects that
are generated for the flexfield usage.
Package Name: Specify the name of the root package to be used for the
generated business components that model the secondary usage.
Note: Each usage must have a unique package name. In addition, the
package name must uniquely identify a usage. For example, if the root
package for a usage is oracle.apps.flex.hcm.payroll.dff1, then
you cannot define the oracle.apps.flex.hcm.payroll package for
another usage, because that package would then identify both usages.
Instead, you could use oracle.apps.flex.hcm.payroll.dff2.
13. On the Summary page, optionally select Extract seed data for the flexfield to
create a seed data file for uploading the registration information into other
implementations. For more information, see Section 23.10, "Loading Seed Data."
14. If you are ready to create business components for the flexfield, select Launch
The column name prefix. For example, if the primary table column is
ATTRIBUTE1, and the secondary table column is HOME_ATTRIBUTE1, then the
prefix is HOME_.
2.
2.
The full class name of the entity object for the table upon which the flexfield usage
is based.
A prefix from which to derive the names of generated objects.
The package in which to place the generated business components. Each usage
must have its own package name.
23-15
Note: Each usage must have a unique package name. In addition, the
package name must uniquely identify a usage. For example, if the root
package for a usage is oracle.apps.flex.hcm.payroll.dff1, then
you cannot define the oracle.apps.flex.hcm.payroll package for
another usage, because that package would then identify both usages.
Instead, you could use oracle.apps.flex.hcm.payroll.dff2.
If you used the Flexfield Registration Metadata wizard to define the flexfield usage,
then you have already registered the entity details. Otherwise, you can use the
Flexfield Registration Metadata wizard or the FND_FLEX_DF_SETUP_APIS PL/SQL
package to register this information for a flexfield usage.
23.2.5.1 Using the Flexfield Registration Metadata Wizard to Register Entity Details
You can use the Edit flexfield usage operation from the Flexfield Registration
Metadata Wizard to register entity details.
To register a usage using the Flexfield Registration Metadata wizard:
1.
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Business Components, and click OK.
3.
4.
To display available usages, provide a value for Application, Code, or Table. You
can use a wildcard character, such as a percent sign (%), to match on similar values.
5.
Select the flexfield usage for which you want to add entity details.
6.
7.
On the Entities page, select the entity objects for the table upon which the usage is
based and move them to the Selected list.
8.
Select each newly added entity object from the Selected list and provide the
following values:
Object Name Prefix: Enter a short unique name for the flexfield usage. For
example PartsDFF. This prefix is used to derive the names of objects that are
generated for the flexfield usage.
Package Name: Specify the name of the root package to be used for the
generated business components that model the flexfield usage.
BI Flattened Fact Name: If the flexfield is enabled for Oracle Business
Intelligence and you know the Oracle Business Intelligence object that this
flexfield should be mapped to when the flexfield is imported into Oracle
Business Intelligence, specify the name of the object.
For more information about Oracle Business Intelligence, see Section 23.13,
"Preparing Descriptive Flexfield Business Components for Oracle Business
Intelligence."
9.
10. On the Summary page, optionally select Extract seed data for the flexfield to
create a seed data file for uploading the registration information into other
implementations. For more information, see Section 23.10, "Loading Seed Data."
11. If you are ready to create business components for the flexfield, select Launch
Register the usage as described in Section 23.2.2, "How to Register and Define
Descriptive Flexfields" and Section 23.2.4, "How to Register the Reuse of a
Descriptive Flexfield."
2.
Ensure that the entity object for the usage's table exists.
2.
See the Implementing Common Features guides for your product family.
Some or all of these types of data sources can be referenced in the following ways:
23-17
Note:
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Business Components, and click OK.
3.
4.
To display available usages, provide a value for Application, Code, or Table. You
can use a wildcard character, such as a percent sign (%), to match on similar values.
5.
Select the primary usage of the flexfield for which you want to add the
parameters.
6.
7.
On the Parameters Page, optionally define parameters for the entity object
attributes that can be used to pass external reference data to flexfield segments.
8.
Click Next.
9.
On the Summary page, optionally select Extract seed data for the flexfield to
create a seed data file for uploading the registration information into other
implementations. For more information, see Section 23.10, "Loading Seed Data."
10. If you are ready to create business components for the flexfield, select Launch
Define and register the flexfield as described in Section 23.2.2, "How to Register and
Define Descriptive Flexfields."
To create a parameter using the setup APIs:
23-19
C1
C2
Primary Key
View link
BaseVO
Primary Key
G1
G2
Context
Primary Key
G1
G2
Context: v1
_v1_VO
Primary Key
G1
G2
Context: v2
_v2_VO
Primary Key
G1
G2
Context: v3
Primary Key
A1
A2
A3
A4
A5
extends
Flexfield
View Objects
Product Entity
Object
C1
C2
Fixed columns
Global segments
_v3_VO
Context-sensitive segments
Note:
Ensure that you have added the Applications Core library to your project as
described in Chapter 3, "Setting Up Your JDeveloper Application Workspace and
Projects."
Ensure that at least one customization class is included in the adf-config.xml file.
This inclusion serves to ensure correct application behavior. It does not matter
which customization class you include.
For information about customization layers, see the "Understanding
Customization Layers" section in the Oracle Fusion Applications Extensibility Guide
for Developers.
Verify that the entity object that will be used as the data source for the business
component meets the following requirements:
All flexfield columns are included in the entity object. In general, all columns
should be included.
A primary key is defined for the entity object. If an entity object is going to be
used to create new application transaction rows, a default primary key must
be programmed.
All VARCHAR2 columns used for descriptive flexfield attributes are mapped to
data type java.lang.String.
All number columns used for descriptive flexfield attributes are mapped to
data type java.math.BigDecimal.
All date columns used for descriptive flexfield attributes are mapped to data
type java.sql.Date.
All timestamp columns used for descriptive flexfield attributes are mapped to
data type java.sql.Timestamp.
Register the flexfield usage's entity object, package name, and object name prefix.
For more information, see Section 23.2.5, "How to Register Entity Details."
3.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Business Components, and click OK.
4.
On the Flexfield page of the Create Flexfield Business Components wizard, select
Descriptive from the Type dropdown list as shown in Figure 239.
5.
In the Application field, specify the full name of the application to which your
descriptive flexfield belongs.
You can browse for the name, and filter by ID, Short Name, or Name.
23-21
6.
In the Code field, specify the code of the descriptive flexfield you want to use.
You can browse for and filter by Code.
7.
In the Usage section, select the table row that contains your desired descriptive
flexfield usage. The descriptive flexfield usage can be one of two possible types:
The primary usage of the descriptive flexfield on the product table where it
was originally defined. Every descriptive flexfield has one primary usage.
A secondary usage of the descriptive flexfield on a product table, including
the one on which it was originally defined. Zero or more secondary usage
instances can be defined for a given flexfield, each one potentially on a
different product table. You can identify secondary usage instances by the
presence of the prefix (Reuse) in the Description field.
8.
Click Next.
9.
On the Path page, select the path of the directory structure in which to create the
flexfield business components and click Next.
10. On the Entity Object page, select the entity object to use as the data source for the
The entity object you select must include all of the attributes representing the
columns that are reserved for the descriptive flexfield.
If you select a polymorphic entity object, ensure that the
InheritPersonalization property for every subtype entity is set to
true.
Note:
Descriptive flexfield attributes will be validated by the entity object along with its
other attributes.
11. If the entity object for the descriptive flexfield has attributes that are defined as
transient (not based on database table columns), then select The names of the
flexfield attributes match the names of registered columns exactly; do not check
the underlying columns.
When an attribute of a descriptive flexfield entity object is transient, there is no
matching underlying column name. When you select this option, the system will
match the entity object attribute names to the descriptive flexfield column names,
and use the matching attributes to access the flexfield data. Ensure that the entity
object has a full set of attributes with matching names before you select this
option.
This entity object must be registered under the primary usage. There is no need to
register another table for this purpose, even if the entity object is based on some
other table. For more information, see Section 23.2.5, "How to Register Entity
Details."
If the entity object with transient descriptive flexfield
attributes is not based on the primary usage, the transient attributes
must be named using the same prefix as the other attributes of that
entity object (and the corresponding table columns). For more
information, see Section 23.2.3, "How to Reuse a Descriptive Flexfield
on Another Table."
Note:
you registered for the usage, as described in Section 23.2.5, "How to Register Entity
Details." Click Next.
14. On the Parameters page shown in Figure 2311, map each flexfield parameter to
the entity object attribute that will be the data source for the parameter.
Parameters are not a requirement for descriptive flexfields. If no parameters are
defined for the descriptive flexfield that you are working with, the Parameters
page will display a message to that effect. However, if any parameters are defined
and associated with a descriptive flexfield, you must map each parameter to an
entity object attribute before you can use the flexfield in your application.
23-23
Figure 2311
The names in the Parameter Code column represent parameters that have been
defined for the descriptive flexfield. For each parameter listed, select the entity
object attribute from the Entity Attribute Name dropdown list to use as the data
source for that parameter.
The entity attributes in the dropdown list include the following:
Attributes that are part of the entity object you selected as the flexfield data
source.
Attributes that are part of any entity object that is directly associated with the
flexfield entity object through an accessor.
Attributes that are part of any entity object that is indirectly associated with
the flexfield entity object through a chain of accessors and entity objects.
An entity attribute is available on this list only if all the
accessors in the chain to the attribute have an underlying association
cardinality of 1-to-1 or many-to-1.
Note:
The path through the chain of accessors to each available entity attribute is
displayed using the following notation:
[accessorname1.[accessorname2.]...]attributename
Although it is not visible, the name of the previously selected flexfield entity object
is implied as the first element in the chain, followed by zero or more accessor
names, then the target entity attribute name. The names of the entity objects in this
chain are also implied.
Cautions:
15. When all of the defined parameters are mapped, click Next.
16. On the Summary page, click Finish.
Note:
17. Refresh the project to see the newly created flexfield business components in the
Application Navigator. The components are in the package that you registered for
the flexfield usage and are named using the registered prefix.
Create the flexfield business components for the descriptive flexfield as described
in Section 23.3.1, "How to Create Descriptive Flexfield Business Components".
In the New Gallery, go to Business Tier > ADF Business Components and select
Flexfield View Link.
23-25
3.
Figure 2312
4.
On the Name page, from the Package dropdown list, specify a package for the
view link.
Caution: You cannot move the view link to a different package after
you create it. Instead, you must delete the view link and re-create it
with the new package name.
5.
6.
Click Next. The View Objects page appears, as shown in Figure 2313.
Nesting the Descriptive Flexfield Application Module Instance in the Application Module
Figure 2313
7.
In the Select Source View Object tree, expand the available objects from your
current project and select the master view object.
8.
In the Select Destination Flexfield tree, expand the application and select a
destination flexfield usage.
9.
In the View Link Accessor Name field, enter an appropriate name for the view
link accessor.
For descriptive flexfields, the Source Attributes page is informational only. The
wizard uses the primary key attributes of the source view object to define the view
link.
Note: You can skip the Properties page because view link-specific
properties are not supported.
12. On the Summary page, click Finish.
23-27
Nesting the Descriptive Flexfield Application Module Instance in the Application Module
23.5.1 How to Nest the Descriptive Flexfield Application Module Instance in the
Application Module
You use the overview editor for your application module to nest the descriptive
flexfield application module instance. The descriptive flexfield application module
instance that you nest in the product application module shares the same transaction
and entity object caches as the application module.
Before you begin:
1. You should have already created the product application module. For information
about creating application modules, see the "Implementing Business Services with
Application Modules" chapter in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
2.
Create the master view object, which contains only nonflexfield attributes.
3.
3.
On the Data Model Components page, expand the Application Module Instances
section, as shown in Figure 2314.
Figure 2314
4.
In the Available tree, find and expand the applicationModule instance under the
flexfield usage's package. This is the package that you specified when you defined
the entity details, as described in Section 23.2.5, "How to Register Entity Details."
5.
Select the application module for the descriptive flexfield and move it to the
Selected tree.
This application module was created when you created the flexfield business
component and was named using the prefix that you specified when you defined
the usage's entity details, as described in Section 23.2.5, "How to Register Entity
Details." For example, if you registered the CasesDFF prefix, the application
module name is CasesDFFAM.
The New App Module Instance field under the list shows the name that will be
used to identify instance. You can change this name.
23.6.1 How to Add a Descriptive Flexfield View Object Instance to the Application
Module
Edit the product application module to add the flexfield view object.
Before you begin:
1. You should have already created the product application module. For information
about creating application modules, see the "Implementing Business Services with
Application Modules" chapter in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
2.
Create the master view object, which contains only nonflexfield attributes.
3.
Create the flexfield business components for the descriptive flexfield usage as
described in Section 23.3.1, "How to Create Descriptive Flexfield Business
Components".
4.
Create the flexfield view link as described in Section 23.4.1, "How to Create
Descriptive Flexfield View Links."
1.
2.
3.
In the View Object Instances section, select the master view object from the
Available View Objects tree and click the right arrow to add it to the Data Model
tree. Next, select the child view object for the flexfield view link and click the right
arrow to add it to the Data Model tree, as shown in Figure 2315.
Figure 2315
23-29
Note:
To add a descriptive flexfield UI component, you add the component to a page in the
one of the following configurations:
If your ADF Table is in an Applications Table component, you must add the following
functionality to the UI:
Create Row and Delete Row functionality if you are using your own CreateInsert
button to create new rows.
Empty table handling if you are using a custom createInsert method.
Dynamic refresh of the context-sensitive segment columns whenever the
Applications Table component is refreshed by another component, such as a
button or a search query.
The following procedures assume that you are using the
data-first approach of adding flexfields to your application. The
UI-first approach is also available, but is not documented here. For
more information, see the "Introduction to Placeholder Data Controls"
section in the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework
Note:
Create the view link as described in Section 23.4.1, "How to Create Descriptive
Flexfield View Links".
3.
4.
3.
In the Data Controls panel, expand the master view object and find the flexfield
view object, as shown in Figure 2316.
Caution: You must use the flexfield view object that is the child of
the master view object. Do not use the flexfield view object from the
flexfield's application module data control.
Figure 2316
4.
Drag the flexfield view object onto a form, and select the appropriate flexfield UI
component.
23-31
Tips:
5.
If you place the flexfield in its own tab, header, or subheader, and
you cannot provide a specific label for the region, consider using
the label "Additional Information," which is the standard generic
label in such a case for Oracle Fusion Applications.
If a descriptive flexfield is in a region, such as a header, subheader,
or tab, that does not contain nonflexfield fields, there is a
possibility that the implementor will not use the flexfield
segments and the region will be empty. To avoid the display of an
empty region on the page, add controlling logic to hide the region
if the implementor has not defined the segments that appear in
the region. For information about how to determine if a segment
has been defined, see Section 23.11.2, "How to Determine Whether
Descriptive Flexfield Segments Have Been Defined." For
information about using an EL expression to hide the region, see
the "Creating EL Expressions" section in the Oracle Fusion
Middleware Web User Interface Developer's Guide for Oracle
Application Development Framework
You can place the segments in a multiple-column layout. Use a
multiple-column layout when the number of segments that will be
added by the implementor is unknown and you anticipate that a
large number of segments will be used. Otherwise, a flexfield with
several segments will take up a large amount of space and the end
user will have to scroll to see any fields that appear below the
flexfield.
Optionally, to add Create Row and Delete Row functionality to the UI, drag the
appropriate operation of the master view object from the Data Controls panel onto
the page.
Tip: You can configure the descriptive flexfield UI component to
present multiple descriptive flexfield rows using the Panel Form
Layout component, with each row's content based on a different
context value. For more information, see the "Arranging Content in
Forms" section of the Oracle Fusion Middleware Web User Interface
Developer's Guide for Oracle Application Development Framework.
Create the view link as described in Section 23.4.1, "How to Create Descriptive
Flexfield View Links".
3.
4.
When prompted, select ADF Table or Applications > Table. You must select the
Row Selection option, and set the appropriate width.
3.
In the Data Controls panel, expand the master view object and find the flexfield
view object.
Caution: You must use the flexfield view object that is the child of
the master view object. Do not use the flexfield view object from the
flexfield's application module data control.
4.
Drag the flexfield view object onto the table on the design tab, as shown in
Figure 2317, and select Oracle Descriptive Flexfield Column as the UI
component. This creates the base flexfield column in the table that the global
segments will render.
Figure 2317
Create a detail region (detailStamp facet) if the table does not have one, as shown
in Figure 2318.
23-33
Figure 2318
6.
Add a panel layout control to the detailStamp facet if you do not already have
one.
7.
Drag and drop the same flexfield view object into the detail region on the Source
tab or the structure view as shown in Figure 2319; this creates fields for the
context-sensitive segments.
Figure 2319
However, if you can guarantee that a given context segment in every row of the table
will always contain the same value for a given application page, the resulting
combination of corresponding context-sensitive segments in each row will remain
constant. In this circumstance the context-sensitive segments can be displayed as table
columns.
For example, if the context segment is a country code, and the purpose of this
application page is to manage only Italian tax data, then the context value should
always be IT. The table columns for the context-sensitive segments will always be
displayed in the configuration appropriate to the Italian tax system.
Before you begin:
Create the descriptive flexfield view object as described in Section 23.3.1, "How to
Create Descriptive Flexfield Business Components".
1.
2.
Create the view link as described in Section 23.4.1, "How to Create Descriptive
Flexfield View Links".
3.
4.
When prompted, select ADF Table or Applications > Table. You must select the
Row Selection option, and set the appropriate width.
3.
In the Data Controls panel, expand the master view object and find the flexfield
view object.
Caution: You must use the flexfield view object that is the child of
the master view object. Do not use the flexfield view object from the
flexfield's application module data control.
4.
Drag the flexfield view object onto the table on the design tab as shown in
Figure 2317, and select Oracle Descriptive Flexfield Column as the UI
component. This creates the base flexfield column in the table.
Caution: Do not drop the flexfield view object into an existing
column. The displaying of descriptive flexfields in the cell of a table
column is not supported.
5.
Edit the JSP source code for this page, and remove the following attribute from the
<fnd:descriptiveFlexfield> tag:
mode="global"
23-35
6.
Add a WHERE clause or view criteria to the master view object to enforce the same
predetermined context value for all rows of the table.
If the context segment will be visible on the page, you must configure the segment
to be read-only so end users cannot modify it. For more information, see
Section 23.8.2, "How to Configure Segment-Level UI Properties".
23.7.4 How to Add Create Row and Delete Row Functionality to the Page
If your ADF Table is wrapped in an Applications Table component, and if you are
using your own Create Insert button to create new rows, you must complete the
following steps.
You do not need to complete these steps if new rows are created using the
Applications Table's New button or the New option on the Actions menu.
Caution: If you enable end users to add new flexfield rows to the UI
table, you can permit them to enter their own unique key values for a
new row. However, you must provide a programmatically generated
primary key value for the new row, otherwise it will generate an error.
Delete the newly created button, but not its pageDef entry. Example 231 shows an
example of the pageDef entry.
Example 231
<executables>
<iterator Binds="Dff1RefInstance" RangeSize="25"
DataControl="Dff1RefAMDataControl" id="Dff1RefInstanceIterator"/>
<iterator Binds="Dff1Instance" RangeSize="25"
DataControl="Dff1RefAMDataControl" id="Dff1InstanceIterator"/>
</executables>
3.
4.
In the Property Inspector for the button, expand the Common section and set the
ActionListener to the EL expression for the method binding. For example,
#{myBean.customCreateInsert}.
Example 231 shows how the executables element of the page definition might
look. Dff1RefInstanceIterator is the iterator of the master view object.
5.
To ensure that new descriptive flexfield rows appear in the UI, add code to the
application page (in the Invoke Application phase or just before the Render
Response phase) to set the state of each newly created row to STATUS_NEW, as
demonstrated in Example 232.
Example 232
If you enable end users to add new flexfield rows to the UI table,
you must ensure that the default value of the new row's context
segment is your predetermined value, matching the existing rows.
You can permit end users to enter their own unique key values for
a new row. However, you must provide a programmatically
generated primary key value for the new row, otherwise it will
generate an error.
The context segment value in any existing row must not change at
runtime. You must enforce this by hiding the context segment or
by configuring it as read-only. For more information, see
Section 23.8.1, "How to Configure Flexfield-Level UI Properties"
and Section 23.8.2, "How to Configure Segment-Level UI
Properties".
if (FirstRowInTable &&
BindingUtil.getCustomProperty(table, "flexenabled") != null)
{
List<UIComponent> columns = table.getChildren();
if (columns != null)
{
for (UIComponent column: columns)
{
if (column.getChildCount() > 0)
{
UIComponent c1 = column.getChildren().get(0);
Using Descriptive Flexfields
23-37
Flexfield Listener
<af:query id="qryId1"
headerText="#{applcoreBundle.QUERY_SEARCH_HEADER_TEXT}"
disclosed="true"
value="#{bindings.criteriaQuery.queryDescriptor}"
model="#{bindings.criteriaQuery.queryModel}"
queryListener="#{backingBeanScope.dffBean.customDffSearchQueryListener}"
queryOperationListener="#{bindings.DffCriteriaQuery.processQueryOperation}"
resultComponentId="::AT2:_ATp:ATt2"/>
Note:
Note:
23-39
Select the descriptive flexfield's UI component on the page and modify its
properties in the Property Inspector, as shown in Figure 2322.
Figure 2322
The significant properties on the Common, Data, Style and Behavior property tabs are
listed in Table 231.
Table 231
Description
Common > Id
Description
For a descriptive flexfield that was added as table columns, you cannot control this property on a
row-by-row basis. It must be set to apply to the entire column.
Rendered: This boolean property indicates whether the segment is visible on the
application page. You can set this property with a literal value or an EL expression.
Required: This boolean property indicates whether the segment must have a
value. You can set this property with a literal value or an EL expression.
ReadOnly: This boolean property indicates whether end users can modify the
segment. You can set this property with a literal value or an EL expression.
Visible: This boolean property specifies whether the segment is displayed in the
page or is hidden. You can set this property with a literal value or an EL
expression.
23-41
Columns: This integer property specifies the width of the control in terms of the
default font size of the browser. You can set this property with a literal value or an
EL expression.
The default values of these properties are derived from the flexfield metadata, but you
can override them by inserting the following flexfield hint components from the
Applications page of the Component Palette:
Flexfield Context Segment Hints: Use this component to configure the context
segment.
Flexfield Segment Hints: Use this component to configure all global segments or
to configure all context-sensitive segments. Also use this component as a container
for Flexfield Segment Hint.
Flexfield Segment Hint: Nest this component in a Flexfield Segment Hints
component to configure an individual global or context-sensitive segment.
If you set a segment's Required property to True, for
validation purposes you cannot override this by resetting it to False in
the flexfield hint component. You can, however, do the reverse:
Change a nonrequired segment to required in the flexfield hint
component.
Note:
For information about using EL expressions, see the "Creating ADF Data Binding EL
Expressions" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
Before you begin:
Add the descriptive flexfield to the page as described in Section 23.7, "Adding
Descriptive Flexfield UI Components to a Page".
In the Property Inspector, set the Visible, ReadOnly, Rendered, and Required
properties.
3.
3.
1.
2.
3.
23-43
3.
Add the descriptive flexfield to the page as described in Section 23.7, "Adding
Descriptive Flexfield UI Components to a Page".
In the Behavior section of the Property Inspector for the descriptive flexfield UI
component, add the UI component ID to the list in the PartialTriggers field.
In the previously introduced example, you would add customerInputText to the
PartialTriggers list. Example 236 shows the source view of the partialTriggers
attribute.
Example 236
<fnd:descriptiveFlexfield value="#{bindings.Dff1Iterator}"
partialTriggers=customerInputText>
23-45
Update the context value on the flexfield, not the master view row. Otherwise, the
structure will not change. Do not update the entity object directly. The flexfield's
structure logic is in the setter of the view row, so do not bypass it.
23.11.2 How to Determine Whether Descriptive Flexfield Segments Have Been Defined
Your application might require information about any global or context-sensitive
segments that exist in a descriptive flexfield's metadata before it invokes a UI that
includes the flexfield.
There is a view attribute in the descriptive flexfield view object, _FLEX_NumOfSegments,
that contains the combined total number of global segments and context-sensitive
segments in the flexfield. Its value is in the java.lang.Integer data format. This value
may vary depending on the context.
The value of this view attribute is the number of segments defined in the metadata.
For a given descriptive flexfield view row, a value of 0 means that only the context
segment is available. Whether a segment is displayed is not taken into consideration.
Specify the handler method as UI metadata on the flexfield's value change listener
property (described in Table 231). In the Property Inspector, click the Edit button
for the value change listener property, and a wizard appears to help you select an
existing event listener or create a new listener. Example 238 is an example of the
<fnd:descriptiveFlexfield value="#{bindings.PJCDFF1Iterator}"
valueChangeListener=
"#{managed_DFFHeaderTablePropHandler.dffChangeListener}"
autoSubmit="true">
For more information about handling value change events, see the "Using Input
Components and Defining Forms" chapter in Oracle Fusion Middleware Web User
Interface Developer's Guide for Oracle Application Development Framework.
getFlexfieldViewUsageConfiguration Method
@Override
protected Map<String, Object>
getFlexfieldViewUsageConfiguration(String accessorName)
{
if ("Parts1".equals(getName()) &&
"FndCrmPartsDFFVL".equals(accessorName))
{
Map<String, Object> map = new HashMap<String, Object>(1);
map.put(
FlexfieldViewObjectImpl.CONF_BYPASS_VALIDATION_REQUIRED, Boolean.TRUE);
return map;
}
else
{
return super.getFlexfieldViewUsageConfiguration(accessorName);
}
}
23-47
2.
a.
Enter a name for the view criteria definition and select the view accessor
attribute from the master view object. The attributes of the view-linked
descriptive flexfield view object appear.
b.
Select the context segment (the discriminator) and use it as the attribute in the
view criteria definition.
c.
3.
In the Data Control panel, select the named view criteria that you created
previously.
4.
Drag and drop the view criteria onto the page as an ADF Query Panel with Table
component, as shown in Figure 2324.
Figure 2324
5.
6.
If the descriptive flexfield appears on the page as a column in a table, perform the
following substeps to enable the execution of a saved search when the page is
loaded for the first time:
a.
From the Property Inspector for the table in which the flexfield is displayed,
obtain the TableId value.
b.
In the Property Inspector for the Query component, set the value of the
ResultComponentId property to the TableId value.
Run the new search form page and click the Advanced button. When you click
Add Fields, only the attributes associated with the base descriptive flexfield view
object (global segments) are available as additional criteria. To include the
context-sensitive attributes for a context, select the equal to operator for the
Context Value criteria item and select a context. The Add Fields list refreshes to
include the context-sensitive attributes from the subtype view object for the
selected context, as shown in Figure 2325.
Note: Figure 238 illustrates the attributes associated with the base
descriptive flexfield view object (global segments) and the
context-sensitive attributes.
23-49
Figure 2325
For more information about working with search forms, see the "Creating ADF
Databound Search Forms" chapter of Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
Edit the flexfield from the Flexfield Registration Metadata wizard as described in
Section 23.2.2.1, "Using the Flexfield Registration Metadata Wizard To Register and
Define Descriptive Flexfields," and select the Enable Business Intelligence
checkbox.
You can optionally provide flattened fact names for the flexfield's entity details, as
described in Section 23.2.5, "How to Register Entity Details." This helps to automate
the process for importing the descriptive flexfield into Oracle Business Intelligence. If
you are using fnd_flex_df_setup_apis, you provide the flattened fact name by
setting the BI_FLATTENED_FACT_NAME value.
When a descriptive flexfield is business intelligence-enabled, implementors use the
Manage Descriptive Flexfields task to enable the descriptive flexfield's segments for
business intelligence. Only the segments that are business intelligence-enabled are
included in the flattened view object. Administrators must then import the changes
into the Oracle Business Intelligence repository to make them available for Oracle
Business Intelligence.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
If you have defined trees on any of the value sets that are referenced by the
flexfield, ensure that the flattened tree view objects are already in your project.
Otherwise, the Create Flexfield Business Components wizard that you use to
create the flexfield business components will report the missing view objects as
errors.
For more information about flattened tree view objects, see Section 61.8.1,
"Designing a Column-Flattened View Object for Oracle Business Intelligence."
For information about implementing your specific product family, do the
following:
1.
2.
See the Implementing Common Features guides for your product family.
Using Descriptive Flexfields
23-51
Create a view link using the procedure described in Section 23.4, "Creating
Descriptive Flexfield View Links". Keep the following in mind:
The master view object that you create with the standard wizard can be the
same master view object that you create for the core descriptive flexfield
model.
Create the view link from the master view object to the business
intelligence-enabled flexfield base view object. The business
intelligence-enabled flexfield is distinguished from the core flexfield by the
prefix "BI:" as shown in Figure 2326.
Figure 2326
3.
On the Data Model page of the Create Application Module wizard, when you
create an instance of the master view object, there is no need for a child view
object.
b.
Note:
4.
Define the custom properties required to link the master view object instance to
the default view instance inside the nested flexfield Oracle Business Intelligence
application module instance.
This is done on the General tab of the nested business intelligence-enabled
flexfield application module instance definition, as shown in Figure 2327.
Figure 2327
As you define the custom properties, keep the following points in mind:
23-53
the flexfield definition, such as the customer-defined segment codes and context codes.
For example, the name of the service data object for the customer-defined context
"Product Type" might be called "CasesDFFProduct_Type." These utility methods help
customers quickly identify a service data object or a property of the object by the
identifiers with which the customers are familiar.
When you generate a flexfield business component, the descriptive flexfield business
components and other artifacts are developed based on the information in the flexfield
metadata. As illustrated in Figure 238, a base view object is created for the context
and global segments. If any contexts have been configured, subtype view objects are
generated for each configured context.
The example in Figure 2328 shows a Business Component Browser view of a
descriptive flexfield.
Figure 2328
2.
2.
3.
4.
Add utility methods for the flexfield to the product application module. These
utility methods, which are exposed to client applications, provide access to
information from the FlexfieldSdoSupport object, which is not exposed to clients.
You can then deploy the service and run Java client programs to test the service as
described in Section 23.14.2, "How to Test the Web Service."
For more information about service-enabling an application module, see "Integrating
Service-Enabled Application Modules" in Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
Note:
2.
Create a flexfield view link between the master view object, which contains only
nonflexfield attributes, and the flexfield business component for the flexfield
usage as described in Section 23.4.1, "How to Create Descriptive Flexfield View
Links."
3.
4.
In the overview editor, expand the Custom Properties section and add a
SERVICE_PROCESS_CHILDREN property set to true, if one does not already
exist.
3.
Open the master view object, which is the view object that contains only the
nonflexfield attributes.
4.
5.
In the Java Classes section, click the Edit icon to generate and configure Java
implementation classes.
6.
In the Select Java Options dialog, select Generate Service Data Object Class, as
shown in Figure 2329.
23-55
Figure 2329
Generating a Service Data Object Class for the Master View Object
7.
Click OK.
8.
9.
10. If the Add icon is enabled, complete the following steps to service-enable the
Click the Add icon to enable the application to support the service interface.
b.
In the Create Service Interface wizard, click Next three times to go to the
Service View Instances page.
c.
Move the view instance for the master view object to the Selected list.
d.
Select the master view object from the Selected list as shown in Figure 2330,
select all the operations in the Basic Operations list, and click OK.
Figure 2330
e.
Click Finish.
11. If the Add icon is disabled, the application is already service enabled. Complete
In the Service Interface View Instances section, click the Edit icon.
b.
Move the view instance for the master view object to the Selected list.
c.
Select the master view object from the Selected list as shown in Figure 2330,
select all the operations in the Basic Operations list, and click OK.
12. Expand the Generated Files for Service Interface section, and make a note of the
name of the remote server class for the product application module. This is the
class that has a name ending with ServiceImpl.java.
13. In the overview editor for the product application module, click the Java
navigation tab and click the link for the Application Module Class.
14. Add the utility methods for the flexfield service data objects to the product
application module. Include methods that return the namespace and name of the
service data object for a given context. Optionally, include methods that return the
path of an attribute that is associated with a given segment in the service data
object. Use self-explanatory names that reflect the name of the flexfield and what is
returned. Example 2310 shows example utility methods for the CasesDFF
flexfield. Example 2311 shows an example of the methods being invoked in a
client application. The self-explanatory utility method names make it easy to
understand the client code.
Example 2310 Utility Methods for Cases DFF Flexfield Service Data Object Support
// A private method to retrieve a FlexfieldSdoSupport object
// from the flexfield application module.
23-57
return r;
}
Example 2311 Client Application for Updating CasesDFF in a CaseList Row
// Obtain the service definition for product type "Office Chair."
List<String> chairObjInfo=
caseListService.getCasesServiceNamespaceAndName("Office Chair");
// Create a service data object for "Office Chair."
DataObject chairObj = dataFactory.create(chairObjInfo.get(0),
chairObjInfo.get(1));
// Set the product type, so the product type matches the object type
chairObj.set(caseListService.getCasesProductTypeServicePropertyPath(),
"Office Chair");
// Obtain the element names of the segments and set the values.
List<String> segmentPaths =
caseListService.getCasesServicePropertyPaths("Office Chair",
Arrays.asList("Broken Part"));
// Update the segment "Broken Part."
chairObj.set(segmentPaths.get(0), "Chair Back");
15. In the overview editor for the product application module, click the Web Service
navigation tab and click the Edit icon in the Service Interface Custom Methods
section.
16. In the Service Custom Methods dialog, move the newly added methods to the
Selected list to make them available for clients and click OK.
The application module's remote server implementation class will be modified to
expose these methods.
Ensure that the BC4J Service Client and BC4J Service Runtime libraries are
included in your project.
1.
2.
Locate the Reference element for the product application module's service
(DFF1MasterApplicationModuleService in this example).
3.
Add the StringRefAddr elements that are shown in bold in Example 2312 to the
Reference element for the product application module's service. Modify the host
23-59
Run the remote server class for the product application module to deploy the
service to Integrated WebLogic Server and to manually test the web service.
The remote server class was generated when you exposed the
descriptive flexfield as a web service in Section 23.14.1, "How to
Expose a Descriptive Flexfield as a Web Service." This class has a name
that ends with ServiceImpl.java.
Note:
5.
Optionally, create and run Java client programs to test invoking the web service:
The following examples demonstrate how to write programs to test the web
service.
Example 2313 shows how to get a data row. The XML payload output of this
program is shown in Example 2314.
23-61
Example 2314 Example XML Payload Output of Web Service Get Operation
<?xml version="1.0" encoding="UTF-8"?>
<ns2:MasterDff
xmlns:ns2="http://xmlns.oracle.com/apps/fnd/applcore/flex/test/dff1/model/"
xmlns:ns1="http://xmlns.oracle.com/apps/fnd/applcore/flex/test/dff1/flex/dff1/"
xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:MasterDff">
<ns2:CreatedBy>0</ns2:CreatedBy>
<ns2:CreationDate>2009-12-03T23:39:25.0-08:00</ns2:CreationDate>
<ns2:LastUpdateDate>2009-12-03T23:39:25.0-08:00</ns2:LastUpdateDate>
<ns2:LastUpdateLogin>0</ns2:LastUpdateLogin>
<ns2:LastUpdatedBy>0</ns2:LastUpdatedBy>
<ns2:PrimaryKeyCode>VS_IND_COC_DEP_DAT_ON_DAT05</ns2:PrimaryKeyCode>
<ns2:ProductContext xsi:nil="true"/>
<ns2:ProductDate xsi:nil="true"/>
<ns2:ProductNumber xsi:nil="true"/>
<ns2:ProductVarchar2 xsi:nil="true"/>
<ns2:dff1 xsi:type="ns1:Dff1VS_5FIND_5FCOC_5FDEP_5FDAT_5FON_5FDAT">
<ns1:PrimaryKeyCode>VS_IND_COC_DEP_DAT_ON_DAT05</ns1:PrimaryKeyCode>
<ns1:_FLEX_ValidationDate>2009-12-03</ns1:_FLEX_ValidationDate>
<ns1:_GlobalSegment1>05</ns1:_GlobalSegment1>
<ns1:_GlobalSegment2>Value05</ns1:_GlobalSegment2>
<ns1:_GLOBAL_STATE_ID_NUM xsi:nil="true"/>
<ns1:_GLOBAL_STATE_ID_NUM_Display xsi:nil="true"/>
<ns1:_FLEX_Context>VS_IND_COC_DEP_DAT_ON_DAT</ns1:_FLEX_Context>
<ns1:_FLEX_NumOfSegments>5</ns1:_FLEX_NumOfSegments>
<ns1:_State>RI</ns1:_State>
<ns1:_State_Holiday>2007-08-12</ns1:_State_Holiday>
</ns2:dff1>
</ns2:MasterDff>
Example 2315 Web Service Create Operation
...
public void createMasterDffRow() {
try {
DFF1MasterApplicationModuleService dff1Service =
(DFF1MasterApplicationModuleService)
ServiceFactory.getServiceProxy(
DFF1MasterApplicationModuleService.NAME);
DataFactory dataFactory =
ServiceFactory.getDataFactory(dff1Service);
MasterDffImpl dffMaster =
(MasterDffImpl)dataFactory.create(MasterDff.class);
dffMaster.setPrimaryKeyCode(PK1);
final String contextValue = "MY_CONTEXT";
List<String> dffInfo =
dff1Service.getMyFlexfieldSdoNamespaceAndName(contextValue);
System.out.println(dffInfo);
DataObject dffSubType =
dataFactory.create(dffInfo.get(0), dffInfo.get(1));
System.out.println(dff1Service.getMyFlexfieldTypeSdoPath());
dffSubType.set(dff1Service.getMyFlexfieldTypeSdoPath(), contextValue);
dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,
Arrays.asList("GLOBAL_STATE_ID_NUM")).get(0),
new BigDecimal(100));
dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,
Arrays.asList("Date_On_Date")).get(0),
java.sql.Date.valueOf("2011-04-18"));
dffMaster.setDff1(dffSubType);
dff1Service.createMasterDff1(dffMaster);
MasterDffImpl masterVOSDO =
(MasterDffImpl)dff1Service.getMasterDff1(PK1);
String updatedXML =
DFFTester.extractXMLFromDataObject(dff1Service, masterVOSDO);
System.out.println("<<<--------Updated XML output-------------->");
System.out.println("");
System.out.println(updatedXML);
} catch (Exception e) {
e.printStackTrace();
}
}
...
23-63
dffMaster.setDff1(dffSubType);
dff1Service.updateMasterDff1(dffMaster);
dffMaster = (MasterDffImpl)dff1Service.getMasterDff1(PK1);
String updatedXML =
DFFTester.extractXMLFromDataObject(dff1Service, dffMaster);
System.out.println("<<<--------Updated XML output-------------->");
System.out.println("");
System.out.println(updatedXML);
} catch (Exception e) {
e.printStackTrace();
}
}
...
Preparing your Excel workbook to access the column containing the flexfield.
The Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application
Development Framework does not make explicit reference to flexfields. In addition to the
standard implementation steps covered in that guide, you must modify your
implementation to accommodate flexfields.
There are two ways to access a descriptive flexfield in Excel:
Using a static column in a popup dialog associated with a single cell. Use this
approach for either of the following reasons:
You do not want descriptive flexfield segments to occupy too much space in
the worksheet.
In addition to using the popup dialog, end users can enter values directly into the
segment field, with the values separated by an appropriate delimiter that you
specify.
A static column is any column for which the DynamicColumn
property is set to False.
Note:
2.
If using a dynamic column descriptive flexfield where the end user can control the
context value, modify the application to update the descriptive flexfield structure
whenever user-initiated context value changes occur in the dynamic column
descriptive flexfield.
3.
Create a custom method to process updates or inserts for descriptive flexfield data
row and add code to invoke the method.
23.15.1 How to Configure ADF Desktop Integration with a Dynamic Column Descriptive
Flexfield
When you configure the ADF Desktop Integration Table, make the following changes:
Add the ADF Desktop Integration Model API library to your data model project.
In your page definition for the worksheet, add the descriptive flexfield that you
want to access to the master worksheet view object as a child node. Do not add
any display attribute to the child node that expands as a dynamic column in the
worksheet.
For more information about how to create a page definition file for an ADF
Desktop Integration project, see the "Working with Page Definition Files for an
Integrated Excel Workbook" section of the Oracle Fusion Middleware Desktop
Integration Developer's Guide for Oracle Application Development Framework.
23-65
a column that is bound to a tree binding or tree node binding whose attribute
names are not known at design time. A dynamic column can expand to more than
a single worksheet column at runtime.
For more information about the binding syntax for dynamic columns, see the
"Adding a Dynamic Column to Your ADF Table Component" section of the Oracle
Fusion Middleware Desktop Integration Developer's Guide for Oracle Application
Development Framework.
Inputtext
OutputText
ModelDrivenColumnComponent
For the subcomponent's Value property, access the Expression Builder, expand the
Bindings node and your tree binding for the table, and select the flexfield node.
For the subcomponent's Label property, access the Expression Builder, expand the
Bindings node and your tree binding for the table, and select the flexfield node.
23.15.3 How to Configure ADF Desktop Integration with a Static Column Descriptive
Flexfield
If the structure of your descriptive flexfield varies from row to row in a given result
set, you cannot implement the flexfield as a dynamic column it will produce errors.
You must use a static column with a popup dialog.
Note:
Note:
When you configure the popup dialog, make the following changes:
You can use the column's action set properties to make the descriptive flexfield
web page available for editing. Include the attributes used in the web page in the
table's cached attributes unless the row will be committed immediately.
You must choose a fixed attribute (a descriptive flexfield global segment attribute)
to represent the flexfield in the worksheet. Add a Dialog action to the
DoubleClickActionSet component action of an InputText or OutputText
component, then connect the Dialog action to JSPX page that will display the
descriptive flexfield.
For more information about how to create a page definition file for an ADF
Desktop Integration Table project, see the "Working with Page Definition Files for
an Integrated Excel Workbook" section of the Oracle Fusion Middleware Desktop
Integration Developer's Guide for Oracle Application Development Framework.
The context value should be set before calling the application module method, which
gets called in the doubleclickactionset component action of the table's
UpdateComponent or InsertComponent properties. This is applicable for both
Using Descriptive Flexfields
23-67
dynamic column and static column display of descriptive flexfields. Setting the context
value appropriately is important because this controls the structure of the flexfield.
The following examples demonstrate the code needed to accomplish these tasks.
Example 2317 and Example 2318 apply to an ADF Desktop Integration
implementation with the descriptive flexfield exposed as a static column.
Example 2319 presents the isSegmentDisplayable() method that is used in the other
two examples.
Example 2317 Updating or Inserting a Row with a Static Column Descriptive Flexfield
//Retrieve your worksheet view object
myworksheet_VOImpl srcVO = myVO
//Retrieve the current row from your view object.
//That is the row that is being processed by ADF Desktop Integration.
myworksheet_VO_Row_Impl srcRow = myworksheet_VO_Row_Impl srcVO.getCurrentRow();
//This gives the transient attribute value from your worksheet.
Object dffAttributeValue = srcRow.getAttribute(mytransientattribute);
//Get the descriptive flexfield row based on the descriptive flexfield view
accessor.
DFFViewRowImpl dffRow = (DFFViewRowImpl)srcRow.getAttribute(mydff_viewaccessor);
//Check if the single cell value is null.
if (dffAttributeValue != null && !("").equals(dffAttributeValue)) {
//Getting DFF metadata information
FlexfieldViewDefImpl dffImpl =
(FlexfieldViewDefImpl)dffRow.getFlexfieldViewDef();
String delim = dffImpl.getDelimiter();
//Parse the DFF string into tokens
StringTokenizer token =
new StringTokenizer(dffAttributeValue.toString(), delim);
while (token.hasMoreTokens()) {
prjValues.add(token.nextToken());
}
}
//Get the descriptive flexfield segment information.
ListAttributeDef listSeg =
dffRow.getFlexfieldViewDef().getFlexfieldAttributes();
Iterator listSegIterator = listSeg.iterator();
AttributeDef seg = null;
ListString segDisplay = new ArrayListString();
while (listSegIterator.hasNext()) {
seg = (AttributeDef)listSegIterator.next();
if (isSegmentDisplayable(seg, dffRow)) {
segDisplay.add(seg.getName());
}
}
//Get the size of the segment.
int segValueSize=0;
if (dffAttributeValue != null && !("").equals(dffAttributeValue))
segValueSize = prjValues.size();
else
segValueSize = segDisplay.size();
Add this code as an application module method that will be invoked by clicking the
OK button of a popup dialog. This method can also be used to populate transient
attribute values used for single cell display upon opening the worksheet, if the
worksheet is intended to display existing records from the database.
//Retrieve the DFF row through the DFF view accessor.
DFFViewRowImpl dffRow =
(DFFViewRowImpl)row.getAttribute(
"DFF_viewaccessorattribute_from_worksheetVO");
//Get the delimiter information for your DFF.
FlexfieldViewDefImpl dffImpl =
(FlexfieldViewDefImpl)dffRow.getFlexfieldViewDef();
String delim = dffImpl.getDelimiter();
//Get the segment information for your DFF.
ListAttributeDef listSeg =
dffRow.getFlexfieldViewDef().getFlexfieldAttributes();
//Your DFF will have many segments, but not all of them will be used for display.
//This code loops through DFF segments and obtains the name and type
//of each displayable segment.
Iterator listSegIterator = listSeg.iterator();
AttributeDef seg = null;
Liststring segDisplay = new ArrayListstring();
Listinteger segDisplayType = new ArrayListinteger();
while (listSegIterator.hasNext()) {
seg = (AttributeDef)listSegIterator.next();
if (isSegmentDisplayable( seg,dffRow)) {
segDisplay.add(seg.getName());
segDisplayType.add(new Integer(seg.getSQLType()));
}
}
int segDisplaySize = segDisplay.size();
StringBuffer segmentString = new StringBuffer();
//
23-69
//
//
//
//
If the segment type is date, remove the time from the date.
For the first segment (i=0), you need to handle it differently
to construct the string correctly.
for (int i = 0; i < segDisplaySize; i++) {
if (dffRow.getAttribute(segDisplay.get(i)) != null) {
if (i == 0) {
if (segDisplayType.get(i) == 91) {
StringTokenizer stTime =
new
StringTokenizer(dffRow.getAttribute(segDisplay.get(i)).toString(), " ");
segmentString.append(stTime.nextToken());
} else {
segmentString.append(dffRow.getAttribute(segDisplay.get(i)));
}
} else {
segmentString.append(delim);
if (segDisplayType.get(i) == 91) {
if (dffRow.getAttribute(segDisplay.get(i)) != null) {
StringTokenizer stTime =
new
StringTokenizer(dffRow.getAttribute(segDisplay.get(i)).toString(), " ");
segmentString.append(stTime.nextToken());
} else {
segmentString.append(
dffRow.getAttribute(segDisplay.get(i)));
}
} else {
segmentString.append(dffRow.getAttribute(segDisplay.get(i)));
}
}
}else {
if (i==0)
segmentString.append(" ");
else {
segmentString.append(delim);
segmentString.append(" ");
}
}
}
row.setyour_transient_attribute(segmentString)
Example 2319 isSegmentDisplayable() Helper Method Used in the Previous Examples
The input parameters for this method are the segment attribute definition and the
descriptive flexfield row.
public boolean isSegmentDisplayable(AttributeDef seg,
DFFViewRowImpl dffRow) {
if (seg.getProperty("FND_ACFF_DisplayAttributeName") == null) {
if (seg.getProperty(seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT) ==null ||
!seg.getProperty(
seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT).equals("Hide")) {
return true;
} else {
return false;
}
} else {
int attrIndex =
dffRow.getFlexfieldViewDef().getAttributeIndexOf(
seg.getProperty("FND_ACFF_DisplayAttributeName").toString());
AttributeDef displayAttrDef =
dffRow.getFlexfieldViewDef().getAttributeDef(attrIndex);
if (displayAttrDef.getProperty(
seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT) == null ||
!displayAttrDef.getProperty(
seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT).equals("Hide")) {
return true;
} else {
return false;
}
}
}
23-71
24
Using Extensible Flexfields
24
This chapter discusses how to use extensible flexfields to enable customers to add
additional attributes to application business objects in Oracle Fusion Applications.
This chapter includes the following sections:
24-1
Implementors can combine and arrange the segments into attribute groups that are
tailored to a customer's specific needs. For example, they can group related segments
so that they appear together on the page. An attribute group is referred to as a context.
You can optionally set up an extensible flexfield to enable implementors to group
contexts into categories.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
To learn more about flexfield basics and terms, including developer and implementor
roles, segments, and contexts, see Chapter 22, "Getting Started with Flexfields." For
more details about the differences between descriptive flexfields and extensible
flexfields, see Section 24.1.2, "The Benefits of Extensible Flexfields."
Context-sensitive segments
Logical pages
Categories
Category hierarchies
Usages
Figure 242 and Figure 243 show UI pages for the Parts business object. The
developer has enabled multiple categories for the Parts flexfield, so the page displays
the category to which the part shown belongs. In Figure 242, the part belongs to the
All-in-One Printers category, and in Figure 242, the part belongs to the Fax category.
In these pages, the Parts flexfield is embedded in the Additional Information region.
For the All-in-One Printers category in Figure 242, the Additional Information region
contains the Copy, Fax, and Scan contexts for the Parts flexfield, while on the Parts
page for the Fax category in Figure 243, the region contains just the Fax context.
A flexfield region is empty until the implementor configures
the extensible flexfield that is embedded in it.
Note:
24-3
Figure 242 Parts User Interface Page for the All-in-One Printers Category
Figure 243 Parts User Interface Page for the Fax Category
Logical pages have several layout options. For example, in Figure 241, the developers
chose to hide the entire left-hand section because their customers will add attributes to
a single page that is known at the time of development. However, in Figure 244,
developers chose to display the list of logical pages in the left-hand pane. For more
information about layout options, see Section 24.9, "Employing an Extensible Flexfield
on a User Interface Page."
24-5
The Positions flexfield in Figure 241 has a single category. The same flexfield
segments appear in the Additional Position Details region regardless of which position
is displayed. In this page, the developer has hidden the name of the category, because
there is only one category.
In Figure 242 and Figure 243, the segments that the region displays depend on
which category the part belongs to. In Figure 242, the part belongs to the All-in-One
Printers category and the UI displays fields related to copying, faxing, and scanning.
In Figure 243, the part belongs to the Fax category and the UI displays fields related
to only faxing.
Each child category inherits the contexts and pages from its parent categories. For
example, the Printers category contains the Print, Printer Functions, and Supported
Operating Systems contexts. The All-in-One Printers category inherits these contexts
from the Printers category. It also inherits all logical pages that are defined for its
parent categories. Additional contexts can be assigned directly to the
All-in-One-Printers category, such as Copy and Scan, which are relevant only to
All-in-One printers.
When you have several objects in the application that should be extended using the
same extensible flexfield, you must create multiple usages for the flexfield. For
example, in the case of an Items application, there might be different data levels, such
as items and item revisions. In this case, you create one usage per data level. By
defining separate usages for each set of tables, you enable your implementors to reuse
the same extensible flexfield configuration for all data levels.
Access control: Implementors can define who can view and edit the attributes in a
context.
24-7
Interface tables: Extensible flexfields support the use of interface tables for loading
extensible flexfield data.
Parallel Sets: Extensible flexfields can generate parallel sets of extensible flexfield
artifacts for different uses, such as public view objects and private view objects.
Another advantage of using extensible flexfields is that you can create your own
custom modeler classes for adding application-specific logic for generating ADF
Business Components and UI task flows, as described in Section 24.13, "Customizing
the Extensible Flexfield Modelers."
Identify the business object and related product table for which you are
implementing the extensible flexfield. For example, you might want to enable
implementors to create custom attributes for the Parts business object, which
corresponds to the FND_CRM_PARTS table.
2.
Decide if you want customers to be able to store translated values for one or more
segments. For example, for a Parts flexfield, customers might want to store
translations for the attributes in the Catalog Information context so they can print
the catalog in different languages.
3.
Decide if you want to enable customers to store the information for a context at
different levels (also referred to as flexfield usages). For example, implementors
might choose to set up a context for a Parts flexfield that has both a part supplier
level and a part level. The same context segments appear in both the supplier UI
and the part UI, but the end user would enter different values. Take, for example, a
lead-time segment. At the part level, the end user would supply the average lead
time. At the supplier level, the end user would enter the actual lead time required
for that supplier.
4.
Decide if you need more than one set of artifacts generated for a flexfield usage.
For example, you might need both private user interfaces that are based on
updatable (entity-based) view objects and public user interfaces that are based on
read-only view objects. When you have more than one set of artifacts, you will
need to define multiple groups at the entity-usage level for the flexfield usage,
such as a Private group and a Public group, when you register the flexfield's
business components.
5.
Determine whether you need to customize the generated model to add additional
product-specific logic or customize the generated user interface, or both.
Create a base extension table for each flexfield usage. If you want to enable
customers to store translations on a locale-by-locale basis, create a translation
extension table and a view of the translation extension table for each usage as well.
See Section 24.3, "Creating Extensible Flexfield Data Tables."
2.
3.
Create entity objects for the flexfield's extension tables. In this step, you create an
entity object and a view object from the base extension table, and, if they exist, the
translation extension table and view.
See Section 24.5, "Creating and Configuring Extensible Flexfield Entity Objects."
4.
Create view objects for the extension tables, create a view object to support
categories, and create a view object to support searching.
See Section 24.6, "Creating and Configuring Extensible Flexfield View Objects."
5.
6.
7.
8.
24-9
9.
Load any necessary application seed data, such as error messages and lookup
values.
See Section 24.12, "Loading Seed Data."
10. Optionally, customize the generated model or the generated UI artifacts, or both.
2.
See the Implementing Common Features guides for your product family.
An extensible flexfield is not displayed at runtime unless at
least one context and context-sensitive segment has been configured
and associated with a category.
Note:
Note: The steps in this section assume that the product table that the
flexfield is extending already exists.
Column
Type
Nullable?
EFF_LINE_ID
NUMBER(18)
No
No
CONTEXT_CODE
VARCHAR2(80)
No
CATEGORY_CODE
VARCHAR2(80)
No
CREATED_BY
VARCHAR2(64)
No
CREATION_DATE
TIMESTAMP
No
LAST_UPDATED_BY
VARCHAR2(64)
No
LAST_UPDATE_DATE
TIMESTAMP
No
LAST_UPDATE_LOGIN
VARCHAR2(32)
Yes
ATTRIBUTE_CHAR1
VARCHAR2(150)
Yes
ATTRIBUTE_CHAR40
VARCHAR2(150)
Yes
ATTRIBUTE_NUMBER1
NUMBER
Yes
ATTRIBUTE_NUMBER1_UOM
VARCHAR2(9)
Yes
...
....
24-11
Table 241 (Cont.) Extensible Flexfield Base Extension Table (_B) Specification
Column
Type
Nullable?
ATTRIBUTE_NUMBER20
NUMBER
Yes
ATTRIBUTE_NUMBER20_UOM
VARCHAR2(9)
Yes
ATTRIBUTE_TIMESTAMP1
TIMESTAMP
Yes
...
TIMESTAMP
Yes
ATTRIBUTE_TIMESTAMP10
TIMESTAMP
Yes
Table 242
Column
Type
Nullable?
EFF_LINE_ID
NUMBER(18)
No
No
CONTEXT_CODE
VARCHAR2(80)
No
CATEGORY_CODE
VARCHAR2(80)
No
CREATED_BY
VARCHAR2(64)
No
CREATION_DATE
TIMESTAMP
No
LAST_UPDATED_BY
VARCHAR2(64)
No
LAST_UPDATE_DATE
TIMESTAMP
No
LAST_UPDATE_LOGIN
VARCHAR2(32)
Yes
SOURCE_LANG
VARCHAR2(4)
No
LANGUAGE
VARCHAR2(4)
No
ATTRIBUTE_CHAR1
VARCHAR2(1000)
Yes
...
VARCHAR2(1000)
Yes
ATTRIBUTE_CHAR40
VARCHAR2(1000)
Yes
Note:
select
ROWID ROW_ID,
EFF_LINE_ID,
CONTEXT_CODE,
CATEGORY_CODE,
ATTRIBUTE_CHAR1,
...
ATTRIBUTE_CHAR40
from MYEFF_TL
where LANGUAGE = userenv('LANG');
Using Extensible Flexfields
24-13
Note:
3.
4.
5.
Note:
Ensure that the Applications Core library has been added to the data model
project, as described in Section 3.3, "Adding Necessary Libraries to Your Data
Model Project."
3.
Verify that at least one customization class is included in the adf-config.xml file.
This serves to ensure correct application behavior. It does not matter which
customization class you include.
For information about defining the customization layers, see the "Understanding
Customization Layers" section in the Oracle Fusion Applications Extensibility Guide
for Developers.
24.5.1.1 Creating and Configuring an Entity Object from the Base Extension Table
Use the Create Entity Object wizard to create an entity object from the base extension
table that is described in Table 241, but apply the changes described in the following
procedure to support the extensible flexfield. For information about the Create Entity
Object wizard, see the "How to Create Single Entity Objects Using the Create Entity
Wizard" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
To create and configure an entity object from the base extension table:
1.
On the Attributes page of the wizard, include only the following columns as
attributes in your new entity object:
EFF_LINE_ID
OBJECT_VERSION_NUMBER
Using Extensible Flexfields
24-15
2.
CONTEXT_CODE
CATEGORY_CODE
CREATED_BY
CREATION_DATE
LAST_UPDATED_BY
LAST_UPDATE_DATE
LAST_UPDATE_LOGIN
3.
On the Java page, confirm that the objectnameBEOImpl entity object class to be
generated extends the oracle.apps.fnd.applcore.oaext.model.OAEntityImpl
class.
4.
After creating the entity object, click the Attributes navigation tab and complete
the following steps:
5.
a.
Select the EFF_LINE_ID attribute and, on the Applications tab of the Property
Inspector, set Application Unique ID to true to generate a globally unique id.
b.
On the UI Hints tab of the Property Inspector for each attribute, set the
Display Hint property to Hide
Note:
a.
b.
c.
d.
In the Define Alternate Key dialog, type EFF_ALT_KEY in the Alternate Key
Name field.
e.
Select the primary key columns of the product table that the extensible
flexfield extends and move them to the Selected list.
f.
Select the contextCode attribute, move it to the Selected list, and click OK.
24.5.1.2 Creating and Configuring an Entity Object from the Translation Extension
Table
If you created a translation extension table for the flexfield usage, as described in
Table 242, use the Create Entity Object wizard to create an entity object from the
24-16 Developer's Guide
translation extension table, but apply the changes described in the following
procedure to support the extensible flexfield.
For more information about creating entity objects, see the "Creating a Business
Domain Layer Using Entity Objects" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
To create and configure an entity object from the extensible flexfield translation
extension table:
1.
2.
On the Attributes page of the wizard, include only the following columns as
attributes in your new entity object:
EFF_LINE_ID
OBJECT_VERSION_NUMBER
CONTEXT_CODE
CATEGORY_CODE
SOURCE_LANG
LANGUAGE
CREATED_BY
CREATION_DATE
LAST_UPDATED_BY
LAST_UPDATE_DATE
LAST_UPDATE_LOGIN
3.
On the Java page, confirm that the objectnameTlEOImpl entity object class to be
generated extends the oracle.apps.fnd.applcore.oaext.model.OAEntityImpl
class.
4.
After creating the entity object, click the Attributes navigation tab and complete
the following steps:
5.
a.
Select the EFF_LINE_ID attribute and, on the Applications tab of the Property
Inspector, set Application Unique ID to true to generate a globally unique id.
b.
On the UI Hints tab of the Property Inspector for each attribute, set the
Display Hint property to Hide
Configure all of the non-key attributes that are of type String to be translatable.
On the Applications tab of the Property Inspector for each non-key, String type
attribute, set the OA Translatable property to True.
6.
24-17
Note:
a.
b.
c.
d.
In the Define Alternate Key dialog, type EFF_ALT_KEY in the Alternate Key
Name field.
e.
Select the primary key of the product table that the extensible flexfield extends
and move it to the Selected list.
f.
Select the contextCode attribute, move it to the Selected list, and click OK.
24.5.1.3 Creating and Configuring an Entity Object from the Translation Extension
View
If you created a translation extension table and view for the flexfield usage, use the
standard wizard to create an entity object from the translation extension view that is
described in Section 24.3.3, "How to Create a Translation Extension View," but apply
the changes described in the following procedure to support the extensible flexfield.
To create and configure an entity object from the extensible flexfield translation
extension view:
1.
2.
On the Attributes page of the wizard, include only the following columns as
attributes in your new entity object:
EFF_LINE_ID
CONTEXT_CODE
CATEGORY_CODE
3.
On the Java page, confirm that the objectnameVlEOImpl entity object class to be
generated extends the oracle.apps.fnd.applcore.oaext.model.OAEntityImpl
class.
4.
After creating the entity object, click the Attributes navigation tab and complete
the following steps:
5.
a.
Select the EFF_LINE_ID attribute and, on the Applications tab of the Property
Inspector, set Application Unique ID to true to generate a globally unique id.
b.
On the UI Hints tab of the Property Inspector for each attribute, set the
Display Hint property to Hide
On the Applications tab of the Property Inspector for the entity object General
tab, set the OA Base Table property to the name of the view underlying this entity
object.
To support contexts for the extensible flexfield, create one view object from the
base extension table entity object and, if the flexfield has a translation extension
table, one view object from the translation extension view entity object.
Note:
object.
To support categories for the flexfield, create a view object from the product table
entity object for which you are developing this extensible flexfield.
To support searching, create a declarative SQL-based view object.
For more information about creating view objects, see the "Defining SQL Queries
Using View Objects" chapter in the Oracle Fusion Middleware Fusion Developer's Guide
for Oracle Application Development Framework. For more information about declarative
SQL-based view objects, see the "How to Create Declarative SQL View Objects" section
in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
Before you begin:
1. Create and configure entity objects from the base extension table, translation
extension table, and view as described in Section 24.5.1, "How to Create and
Configure Extensible Flexfield Entity Objects."
Use the Create View Object wizard to create the view objects from the base
extension table entity object and, if you created a translation extension table for the
usage, from the translation extension view entity object.
2.
On the Java page for each view object, ensure that the view object classes to be
generated extend base classes as follows:
24-19
Use the Create View Object wizard to create a view object from the product table for
which you are implementing the extensible flexfield in the usual manner. For example,
in Figure 242, the product table is the Parts table that stores the base attributes for the
Parts entity, such as Part Number, Description, and Unit Cost.
This view object must include an attribute called CategoryCode, which is used to
identify the category to which each row of data belongs. This attribute must be an
entity-based attribute of type VARCHAR2 with a maximum of 80 characters.
Set the CategoryCode attribute to be a discriminator, with a default value of 0.
You must ensure that the correct category code is returned for this attribute at runtime.
In the Application Navigator, right-click the project in which you want to create
the view object and choose New.
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then View Object, and click OK.
3.
On the Name page, enter a package name and a view object name. Keep the
default setting Updatable access through entity objects enabled to indicate that
you want this view object to manage data with its base entity object. Click Next.
4.
On the Entity Objects page, select the entity object that was used for the base
category view object and move it to the Selected tree.
The view object can contain additional entity objects, but it must include the entity
object that was used for the base category view object.
5.
Click Next.
6.
On the Attributes page, select all the attributes for which you want to enable
search and move them to the Selected tree.
You must include the CategoryCode attribute and the primary key attributes.
7.
Select the other attributes to include in the view criteria, move them to the
Selected tree, and click Next.
8.
a.
On the Attribute Settings page, select CategoryCode from the Select Attribute
dropdown list.
b.
Select Discriminator.
c.
Note:
9.
Configure the attribute settings for the remaining attributes as required, and click
Next.
10. On the Query page, select Declarative in the SQL Mode dropdown list if it is not
oracle.apps.fnd.applcore.oaext.model.EFFCategoryViewObjectImpl.
The EFFCategoryViewObjectImpl class adds the additional WHERE clause that
provides security.
14. In the Definition field, type
fully qualified name of the search view object or execute the following SQL
statement to register it. Replace search-view-object with the fully qualified name for
the search view object. Replace product-table with the name of the product table
that the flexfield extends.
UPDATE FND_DF_ADFBC_USAGES
SET EFF_SEARCH_VIEW_OBJECT = 'search-view-object'
WHERE TABLE_NAME='product-table'
AND ENTITY_OBJECT='product-table-entity-object';
The name of the product table for which the flexfield is implemented (the primary
table), and the view object and application module for that table.
The name of the base extension table that contains the columns to be used as
flexfield segments. This name should have a suffix of _B.
The name of the context column in the base extension table. This should be
CONTEXT_CODE.
Using Extensible Flexfields
24-21
The names of the columns in the base extension table that are to be used as
flexfield segments.
If the flexfield is enabled for translations, the name of the translation extension
table, which should have a suffix of _TL, and the translation extension view, which
should have a suffix of _VL.
Flexfield ADF Business Component usage information, including the Oracle
Metadata Services (MDS) root packages for its usage the name of the root
package for all business components that model the flexfield. Each usage must
have its own package name.
If the flexfield has custom modelers, the names of the custom modeler. For
information about custom modelers, see Section 24.13.1, "How to Customize the
Runtime Business Component Modeler for Extensible Flexfields" and
Section 24.13.2, "How to Customize the Runtime User Interface Modeler for
Extensible Flexfields."
After the implementors configure the flexfield, the definition of an extensible flexfield
also contains the following information:
A complete list of the ContextCode values that can appear in the flexfield context
segment.
Information about the segments that are associated with the ContextCode values.
Each ContextCode value is associated with its own set of these segments.
A complete list of the CategoryCode values that belong to the extensible flexfield,
and the contexts that are associated with each category, page, and usage.
Validation rules that are associated with the segments. Each segment can have its
own LOV or validation rules.
Setup APIs
24.7.1.1 Using the Flexfield Registration Metadata Wizard to Register and Define
Extensible Flexfields
Use the Register new flexfield operation to register and define an extensible flexfield
from the Flexfield Registration Metadata wizard. To make subsequent additions and
changes to the flexfields, you use the Edit flexfield operation.
Before you begin:
Create entity objects for the extensible flexfield tables as described in Section 24.5,
"Creating and Configuring Extensible Flexfield Entity Objects."
Create view objects for the extensible flexfield tables as described in Section 24.6,
"Creating and Configuring Extensible Flexfield View Objects."
Ensure that entity objects exist for the primary table (the product table that the
extensible flexfield extends).
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Registration Metadata, and click OK.
3.
4.
On the Basic Information page, select Extensible Flexfield from the Type
dropdown list.
5.
Application: Select the application name that has been assigned for the
product area.
Module: Select the module that owns the flexfield. This is typically the
application or logical business area (LBA) with which the flexfield is delivered.
6.
Click Next.
7.
On the Product Table page, set the following values to define the flexfield usage.
24-23
Provide the search view object, if it exists. This is an SQL-based view object
that is based on the entity object that was used for the base category view
object as described in Section 24.6.1.3, "Creating a Declarative SQL-Based View
Object to Enable Searching."
You need a search view object only if the flexfield is enabled
for business intelligence or there is a need to expose the flexfield's
segments in the search user interface for the product table that the
flexfield is extending, as described in Section 24.10, "Incorporating
Extensible Flexfields into a Search Form."
Note:
The name of the root package to be used for the generated business
components that model the flexfield usage.
The object name prefix for the flexfield usage. For example, PartsEFF. This
prefix is used to derive the names of objects that are generated for the flexfield
usage.
8.
Click Next.
9.
From the Extension Table page, specify the name of the base extension table for the
flexfield, and the table's entity object and view object.
10. Select the database columns in the Available list that you want to use for the
b.
c.
Provide the names of the entity object and view object for the translation
extension table, and the name of the entity object for the translation extension
view. These are the objects that you created in Section 24.5.1, "How to Create
and Configure Extensible Flexfield Entity Objects."
d.
e.
Select the database columns in the Available list that you want to map to
flexfield segments and move them to the Selected list.
component modeler and custom user interface modeler if you have created these
modelers for the flexfield.
15. Click Next.
16. On the Summary page, optionally select Launch Flexfield Business Components
Wizard if you are ready to create business components for the flexfield.
17. Click Finish.
for the root category code. Set the PARENT_CATEGORY_CODE to null to indicate
that it is the root category.
An extensible flexfield requires at least one entry in the FND_EF_CATEGORIES_B
table and, if one exists, the FND_CATEGORIES_TL table. Add additional entries
only if you are shipping your application with some categories already defined.
Note:
24.7.1.2 Using the Setup APIs to Register and Define Extensible Flexfields
In addition to using the Flexfield Registration Metadata wizard, you can use the FND_
FLEX_EF_SETUP_APIS PL/SQL API package to register new extensible flexfield usages
and to add the flexfield metadata.
You can learn about the FND_FLEX_EF_SETUP_APIS PL/SQL package by running the
following command, which stores package documentation and usage examples in the
<db_name>_<user_name>_FND_FLEX_EF_SETUP_APIS_<date>.plsqldoc file.
sqlplus <fusion_user>/<fusion_pwd>@<fusion_db> \
@/ORACLE/fusionapps/atgpf/applcore/db/sql/flex/fnd_flex_pkg_doc.sql \
FND_FLEX_EF_SETUP_APIS
After you register the flexfield, you must add entries for the root category code to the
FND_EF_CATEGORIES_B and FND_EFF_CATEGORIES_TL tables. Set the PARENT_
CATEGORY_CODE to null to indicate that it is the root category.
An extensible flexfield requires at least one entry in the FND_EF_CATEGORIES_B
table and, if one exists, the FND_CATEGORIES_TL table. Add additional entries only
if you are shipping your application with some categories already defined.
Note:
24-25
C3_EO
EFF
Line ID
EFF
Line ID
Primary
Key
Primary
Key
Context
C2
Context
C3
C2_EO
Context
C1
A1
Primary
Key
Context
EFF
Line ID
Primary
Key
C1_EO
Extends
EFF
Line ID
Base Extension Table
Entity Object
A2
A3
A4
Context-Sensitive
Attributes
A5
C3_VO
EFF
Line ID
EFF
Line ID
Primary
Key
Primary
Key
Context
C2
Context
C3
C2_VO
Context
C1
A1
Primary
Key
Context
EFF
Line ID
Primary
Key
C1_VO
Extends
EFF
Line ID
A2
A4
A5
Primary
Key
Primary
Key
Category:
B1
Category:
B2
Category:
B3
B2_VO
Primary
Key
Category
B3_VO
B1_VO
Primary
Key
Category
Category
Other Application
Attributes
Primary
Key
Extends
Category to Context
View Links
A3
Context-Sensitive
Attributes
Primary
Key
24-27
Create the flexfield entity objects as described in Section 24.5.1, "How to Create
and Configure Extensible Flexfield Entity Objects."
Create the flexfield view objects and the declarative SQL-based view object as
described Section 24.6.1, "How to Create and Configure Extensible Flexfield View
Objects."
Register the flexfield as described in Section 24.7.1, "How to Register Extensible
Flexfields."
Build your project to ensure that the entity objects are available in classes. The
modeler relies on what is in your classes.
Ensure that you have added the Applications Core library to your project as
described in Chapter 3, "Setting Up Your JDeveloper Application Workspace and
Projects."
Ensure that at least one customization class is included in the adf-config.xml file.
This inclusion serves to ensure correct application behavior. It does not matter
which customization class you include.
For information about customization layers, see the "Understanding
Customization Layers" section in the Oracle Fusion Applications Extensibility Guide
for Developers.
In the New Gallery, expand Business Tier, select ADF Business Components,
select Flexfield Business Components, and click OK.
3.
In the Flexfield page of the Create Flexfield Components wizard, select Extensible
from the Type dropdown list as shown in the following figure.
4.
In the Application field, specify the full name of the application to which your
extensible flexfield belongs.
You can browse for the name, and filter by ID, Short Name, or Name.
5.
In the Code field, specify the code of the extensible flexfield you want to use.
You can browse for and filter by Code.
6.
In the Usage section, select the table row that contains your desired extensible
flexfield usage.
7.
Click Next.
8.
The Overview page displays the tasks that must be completed before the wizard
can generate the business components, as shown in the following figure. The
wizard will complete the necessary tasks. Click Next.
If you created a declarative SQL-based view object as
described in Section 24.6.1.3, "Creating a Declarative SQL-Based View
Object to Enable Searching," then the wizard will create a stub search
view object, which you can use to expose the extensible flexfield's
attributes in a table and to incorporate the extensible flexfield in a
search form. Make a note of the fully qualified path that is shown in
on the Overview page for the stub search view object so that you can
locate the view object and add it to an application module. If a path is
not shown for the view object, then the declarative SQL-based view
object was not registered in the FND_DF_ADFBC_USAGES table.
Note:
24-29
9.
If the wizard needs to implement any uncompleted tasks from the Overview page,
the wizard displays the automated code changes, as shown in the following figure.
Review the code and click Next.
Figure 2410
Note:
11. Refresh the project to see the newly created flexfield business components in the
Application Navigator. The components are in the package that you registered for
the flexfield usage and are named using the registered prefix.
As a single task flow for multiple contexts for a single usage in one of the
following layouts:
Single page layout: A single task flow that presents a set of contexts associated
with a specified logical page, which is identified before the UI page initializes.
Figure 241 is an example of this variation.
Panel splitter layout: A list of the extensible flexfield logical pages for a single
usage, combined with the contexts for the selected logical page, and integrated
into a single task flow. Figure 242 is an example of this variation.
As a single task flow that presents a context, which is identified before the UI page
initializes.
As a complete list of the usages and pages for a given extensible flexfield in one
task flow, with contexts for the selected page in a separate task flow.
As columns in a table that displays the attributes for a specific category. The
attributes from all the contexts that are associated with the category are displayed.
The attributes are grouped in a column span and are labeled context:segment.
Notes:
If there is only one usage and only one logical page, use a single
task flow that presents a set of contexts associated with a specified
logical page, which is identified before the UI page initializes. Do
not display a list of usages or pages on the left-hand side of the
task flow.
If the extensible flexfield will never have more than one usage and
will never have more than one logical page, and if you do not
need any features that are unique to extensible flexfields as
discussed in Section 24.1.2, "The Benefits of Extensible Flexfields,"
consider using a descriptive flexfield instead.
Unless you know that the extensible flexfield will contain only a
small amount of information, do not embed the flexfield in the
middle of a region that has other content.
For more information about task flows, see the "Creating a Task Flow" section in the
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
24-31
24.9.1 How to Expose an Extensible Flexfield Usage as a Single Task Flow for Multiple
Contexts
You can easily incorporate an extensible flexfield into the UI in one of the following
layouts by dragging the view object for the flexfield-enabled object from the Data
Controls panel and dropping it onto the page:
Single page layout: The extensible flexfield is incorporated as a single task flow
that presents a set of contexts associated with a specified logical page and usage as
shown in Figure 241.
Panel splitter layout: The extensible flexfield is incorporated as a list of the logical
pages for a specified usage, combined with the contexts for the user-selected
logical page, and integrated into a single task flow, as shown n Figure 242.
Execute the following SQL query to obtain the name of the view object for the
flexfield-enabled object:
SELECT VIEW_OBJECT FROM FND_DF_ADFBC_USAGES WHERE TABLE_NAME IN
(SELECT TABLE_NAME FROM FND_DF_TABLE_USAGES TBL WHERE
DESCRIPTIVE_FLEXFIELD_CODE = flexfield-code AND
TBL.APPLICATION_ID = application-id AND
TABLE_TYPE = 'BASE' AND FLEXFIELD_USAGE_CODE = flexfield-usage-code)
From the Data Controls panel, drag the view object for the flexfield-enabled object
onto the page or Structure window.
3.
4.
In the User Interface region in the Create Extensible Flexfield dialog, select Panel
Splitter or Single Page, as shown in Section 2411, "Create Extensible Flexfield
Dialog"
Figure 2411
5.
6.
If you selected the single page layout, enter the page code for the logical page to be
displayed at runtime.
7.
8.
In the Object Keys region, specify the values to use for the category code and the
primary keys.
9.
Click Apply.
10. (Optional) Complete the following steps to modify the ReadOnly and _eff_
b.
In Executables section in the page definition, select taskFlow ExtensibleFlexfieldRruntimeUI1 and click the Edit icon.
c.
In the Input Parameters region in the Edit Task Flow Binding dialog, set
ReadOnly to Y if the page should render all segments as read-only fields.
Otherwise, set to N or leave the parameter value blank.
d.
11. If you have not done so already, complete the following substeps:
a.
Open the Databindings.cpx file and add the following EFFRuntimeAM data
control:
<BC4JDataControl
id="EFFRuntimeAMDataControl"
Package="oracle.apps.fnd.applcore.flex.eff.
runtime.applicationModule"
FactoryClass="oracle.adf.model.bc4j.
DataControlFactoryImpl"
24-33
SupportsTransactions="true" SupportsFindMode="true"
SupportsRangesize="true" SupportsResetState="true"
SupportsSortCollection="true" Configuration=
"EFFRuntimeAM"
syncMode="Immediate"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"/>
b.
Add the following code to the Application tag at the top of the
Databindings.cpx file to enable the application to find the page definitions for
the generated UI artifacts:
PageMapClass="oracle.jbo.uicli.mom.DynamicPageMapImpl"
BasePageDefPackageName="pageDefs"
24.9.2 How to Expose the Complete Set of an Extensible Flexfield's Usages, Logical
Pages, and Associated Contexts
To expose the complete set of usages, logical pages, and associated contexts, build a UI
page that includes a splitter with two task flows: one containing the list of extensible
flexfield usages and their associated logical pages on the left, and the other containing
the contexts associated with the selected logical page on the right.
To build the UI page:
1.
Create a task flow for the extensible flexfield usages and a task flow for the
associated contexts.
2.
3.
2.
Name: ContainerBean
Class:
oracle.apps.fnd.applcore.flex.eff.runtime.EffCategoryPagesBean
Value: #{pageFlowScope.ContainerBean}
3.
4.
Add a parameter that is the same as the one you added in Step 2 to the task flow.
Create the page-list task flow and context container task flow as described in
Section 24.9.2.1, "Creating the Task Flows".
To create the fragments:
1.
2.
3.
4.
Drag and drop the page list fragment onto the page-list task flow.
5.
Drag and drop the context page fragment onto the context task flow.
24-35
1.
Create the page-list task flow and context container task flow as described in
Section 24.9.2.1, "Creating the Task Flows."
2.
2.
Add the page-list and context page task flows to the left and right facets of the
splitter.
3.
4.
Open the Databindings.cpx file and add the following EFFRuntimeAM data
control:
<BC4JDataControl
b.
id="EFFRuntimeAMDataControl"
Package="oracle.apps.fnd.applcore.flex.eff.
runtime.applicationModule"
FactoryClass="oracle.adf.model.bc4j.
DataControlFactoryImpl"
SupportsTransactions="true" SupportsFindMode="true"
SupportsRangesize="true" SupportsResetState="true"
SupportsSortCollection="true" Configuration=
"EFFRuntimeAM"
syncMode="Immediate"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"/>
Add the following code to the Application tag at the top of the
Databindings.cpx file to enable the application to find the page definitions for
the generated UI artifacts:
PageMapClass="oracle.jbo.uicli.mom.DynamicPageMapImpl"
BasePageDefPackageName="pageDefs"
3.
Create a fragment, for example PageListFrag.jsff, and drag and drop the
EffCatPageListContainer task flow from the ViewController FlexModeler-View
library on the fragment.
4.
5.
Place the task flow on any page on which you want the page list to appear.
6.
7.
8.
Access the page on which you would like your contexts to appear. This could
possibly be the same page as in Step 5, but is likely the second facet of a splitter.
9.
Drag and drop ContextsTF.xml as a dynamic region onto this page at the correct
location.
10. When prompted for a backing bean, enter a new bean name, class, and package,
24-37
This setting provides the callback and the conditions for the refresh of the contexts
region.
When you run the page and click the page link, the callback to refreshRegion will
look up the ID for the contexts task flow and enable a refresh condition of the
dynamic region.
14. If you have not done so already, complete the following substeps:
a.
Open the Databindings.cpx file and add the following EFFRuntimeAM data
control:
<BC4JDataControl
b.
id="EFFRuntimeAMDataControl"
Package="oracle.apps.fnd.applcore.flex.eff.
runtime.applicationModule"
FactoryClass="oracle.adf.model.bc4j.
DataControlFactoryImpl"
SupportsTransactions="true" SupportsFindMode="true"
SupportsRangesize="true" SupportsResetState="true"
SupportsSortCollection="true" Configuration=
"EFFRuntimeAM"
syncMode="Immediate"
xmlns="http://xmlns.oracle.com/adfm/datacontrol"/>
Add the following code to the Application tag at the top of the
Databindings.cpx file to enable the application to find the page definitions for
the generated UI artifacts:
PageMapClass="oracle.jbo.uicli.mom.DynamicPageMapImpl"
BasePageDefPackageName="pageDefs"
If you have not done so already, add the stub search view object that was created
when you ran the Create Flexfields Business Components wizard to an application
module. The stub search view object is in the view folder in the package that you
registered for the extensible flexfield usage in the FND_DF_ADFBC_USAGES
table.
The Create Flexfields Business Components wizard creates the
stub search view object based on the flexfield's declarative SQL-based
view object that was registered for the flexfield usage. If no declarative
SQL-based view object was registered, then a stub search view object
will not exist. You must create and register the SQL-based view object
as described in Section 24.6.1.3, "Creating a Declarative SQL-Based
View Object to Enable Searching" and then run the Create Flexfield
Business Components wizard as described in Section 24.8.1, "How to
Create Business Components For an Extensible Flexfield's Usage."
Note:
Drag the stub search view object and drop it on the page.
3.
4.
Rearrange the columns and select table options as required. If you choose the
filtering option, the table will be a filtered table.
5.
6.
In the source editor for the page definition, remove the AttrNames tag and its
nested tags from the nodeDefinition tag in the tree tag. The tags shown in bold
in Example 245 are examples of the tags to remove.
Example 243
<tree
IterBinding="j_ExtendedDeclarativePublic1Iterator"
id="j_ExtendedDeclarativePublic1">
<nodeDefinition
DefName="oracle.apps.fnd.applcore.flex.eff.test.genjbo.base.model.view.
j_ExtendedDeclarativePublicVO" Name="j_ExtendedDeclarativePublic10">
<AttrNames>
<Item Value="Description"/>
<Item Value="ItemType"/>
<Item Value="Name"/>
<Item Value="CategoryCode"/>
</AttrNames>
</nodeDefinition>
</tree>
7.
8.
In the source editor for the search page, add the following <af:column> tag to the
<af:table> tag. Change iter-binding to the IterBinding value for the tree tag in
the page definition. This is the value that you noted in Step 7.
<af:column headerText="header-text">
<fnd:extensibleFlexfieldColumn
value="#{bindings.iter-binding}"
readOnly="true"/>
</af:column>
9.
Open the source code in which you will call the executeQuery method for the
view object.
prepareEFFDeclarativeVOForCategory API
24-39
If you have not done so already, add the stub search view object that was created
when you ran the Create Flexfields Business Components wizard to an application
module. The stub search view object is in the view folder in the package that you
registered for the extensible flexfield usage in the FND_DF_ADFBC_USAGES
table.
The Create Flexfields Business Components wizard creates the
stub search view object based on the flexfield's declarative SQL-based
view object that was registered for the flexfield usage. If no declarative
SQL-based view object was registered, then a stub search view object
will not exist. You must create and register the SQL-based view object
as described in Section 24.6.1.3, "Creating a Declarative SQL-Based
View Object to Enable Searching" and then run the Create Flexfield
Business Components wizard as described in Section 24.8.1, "How to
Create Business Components For an Extensible Flexfield's Usage."
Note:
If the desired view criteria for the stub search view object does not exist, create it.
The view criteria must contain the flexfield's CategoryCode attribute. The operator
for the CategoryCode attribute must be set to Equals.
From the Data Controls panel, expand the stub search view object, expand Named
Criteria, and drag the desired view criteria onto the page or Structure window.
3.
Use the stub search view object to create a results panel and a query panel as
described in the "Creating Query Search Forms" section in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
4.
5.
In the source editor for the page definition, remove the AttrNames tag and its
nested tags from the nodeDefinition tag in the tree tag. The tags shown in bold
in Example 245 are examples of the tags to remove.
Example 245
<tree
IterBinding="j_ExtendedDeclarativePublic1Iterator"
id="j_ExtendedDeclarativePublic1">
<nodeDefinition
DefName="oracle.apps.fnd.applcore.flex.eff.test.genjbo.base.model.view.
j_ExtendedDeclarativePublicVO" Name="j_ExtendedDeclarativePublic10">
<AttrNames>
<Item Value="Description"/>
<Item Value="ItemType"/>
<Item Value="Name"/>
<Item Value="CategoryCode"/>
</AttrNames>
</nodeDefinition>
</tree>
6.
7.
In the Structure window for the search page, select the af:query component.
8.
In the Property Inspector, expand Behavior and set the QueryListener property to
FlexEFFSearchUtilBean.effQueryListener.
9.
In the source editor for the search page, add the following <af:column> tag to the
<af:table> tag. Change iter-binding to the IterBinding value for the tree tag in
the page definition. This is the value that you noted in Step 6.
<af:column headerText="header-text">
<fnd:extensibleFlexfieldColumn
value="#{bindings.iter-binding}"
readOnly="true"/>
</af:column>
24-41
object for business intelligence alongside the standard extensible flexfield polymorphic
view object.
At runtime, the implementor can select which individual flexfield segments to make
available for use with Oracle Business Intelligence. Those segments are included in a
flattened view object that is generated from the stub view object. Administrators must
then import the flexfield into the Oracle Business Intelligence repository to make it
available for Oracle Business Intelligence.
3.
Ensure that the declarative SQL-Based view object was registered for the flexfield,
either by using the Register Flexfield Metadata wizard to provide the fully
qualified name of the search view object or by executing the following SQL
statement to register it. Replace search-view-object with the fully qualified name for
the search view object. Replace product-table with the name of the product table
that the flexfield extends.
UPDATE FND_DF_ADFBC_USAGES
SET EFF_SEARCH_VIEW_OBJECT = 'search-view-object'
WHERE TABLE_NAME='product-table'
AND ENTITY_OBJECT='product-table-entity-object';
4.
Enable the flexfield and the desired segments for Oracle Business Intelligence as
described in Section 24.11.1, "How to Enable an Extensible Flexfield for Oracle
Business Intelligence."
Complete the following steps to link the stub view object to the business
intelligence view object for the product table.
1.
2.
In the New Gallery, go to Business Tier > ADF Business Components and
select Flexfield View Link.
3.
4.
On the Name page, from the Package dropdown list, specify a package for the
view link.
Caution: You cannot move the view link to a different package after
you create it. Instead, you must delete the view link and re-create it
with the new package name.
5.
6.
Click Next.
7.
In the Select Source View Object tree, expand the available objects from your
current project and select the master view object, which is the business
intelligence view object for the product table.
8.
In the Select Destination Flexfield tree, expand the application and select the
destination flexfield usage, which is the stub view object.
9.
In the View Link Accessor Name field, enter an appropriate name for the
view link accessor.
For extensible flexfields, the Source Attributes page is informational only. The
wizard uses the primary key attributes of the source view object to define the
view link.
Note: You can skip the Properties page because view link-specific
properties are not supported.
12. On the Summary page, click Finish.
24-43
After you complete the registration process described in Section 24.7.1, "How to
Register Extensible Flexfields," your flexfield seed data consists of the information that
you registered for your flexfield, such as the tables and columns reserved for your
flexfield. For a customer flexfield, the seed data contains only this registration data.
If your flexfield is a developer flexfield, you also serve as the implementor. In addition
to the registration data, your flexfield seed data might include contexts, segments, and
value sets that you have defined for your flexfield. You can use the Oracle Fusion
Middleware Extensions for Applications (Applications Core) Setup application, as
described in Section 27.5, "Deploying Flexfields in a Standalone WebLogic Server
Environment," to configure a flexfield.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
Use the Manage Extensible Flexfields and Manage Value Sets tasks or use the PL/SQL
APIs to create contexts, segments, and value sets, and then use the seed data loader to
extract your seed data. To protect flexfield seed data from customer edits, use the
Manage Extensible Flexfields task to set flags to mark flexfield pages and contexts as
protected. Use the Manage Value Sets task to set the flag to protect a value set.
Only the user with the SEED_DATA_FROM_APPLICATION_USER user name can
modify protected flexfield pages, contexts, and value sets from the setup tasks, such as
the Manage Extensible Flexfields and Manage Value Sets tasks.
For information about extracting and loading seed data, see Chapter 57, "Initializing
Oracle Fusion Application Data Using the Seed Data Loader."
24.13.1 How to Customize the Runtime Business Component Modeler for Extensible
Flexfields
To extend the runtime business component modeler for extensible flexfields, override
the EFFBCModelerFactory.getCustomEFFBCModeler method, shown in Example 246,
in the custom runtime business component modeler factory for extensible flexfields.
Example 246
/**
*
*
*
*
*
*
*
*
*
*
*
*
getCustomEFFBCModeler Method
PIMBCModelerFactory.java Override
24.13.2 How to Customize the Runtime User Interface Modeler for Extensible Flexfields
If the UI artifacts that are generated for an extensible flexfield business component do
not fulfill application requirements, you can create wrapper implementation classes
for the framework's customizer interfaces. These wrapper implementation classes
enable some control over the XML code that the modeler generates for the UI artifacts
just before it persists the generated task flows and JavaServer Faces (JSF) page
fragments. The implementation classes are in the
oracle.apps.fnd.applcore.flex.uimodeler.customizers package.
To customize an extensible flexfield business component's generated UI artifacts:
Using Extensible Flexfields
24-45
1.
2.
3.
Register the metadata provider wrapper class in the metadata for the flexfield's
business component.
24.13.2.1.1 How to Customize the Context JSF Page Fragment To customize the JSF page
fragment for a single row context, create a wrapper class for the
SingleRowContextRegionCustomizerImpl implementation class and override the
customizeGeneratedSingleRowContextFragment method.
To customize the JSF page fragment for a multiple row context, create a wrapper class
for the MultiRowContextRegionCustomizerImpl implementation class and override
the customizeGeneratedMultiRowContextFragment method.
24.13.2.1.2 How to Customize the Segment Components in the Generated Context Task Flow To
customize which segment components in the generated context task flow will be
read-only for single and multirow contexts, create a wrapper class for the
ContextComponentsCustomizerImpl implementation class and override the
getAtributeComponentReadonlyELExpression method. This method returns the value
of the readOnly property for a given segment component in the context task flow, as
shown in Example 248.
Example 248
24.13.2.1.3 How to Customize the Page Links in the Generated Links Task Flow To customize
which page links in a generated links task flow will be rendered, create a wrapper
class for the PageListCustomizerImpl implementation class and override the
getPageLinkRenderedProperty method. This method returns the value of the
rendered property for a page link.
24.13.2.1.4 How to Customize the Page Task Flow To customize which context task flows
will be rendered in a page task flow, create a wrapper class for the
24-46 Developer's Guide
Customization
Method to Override
Notes
getSearchManagedBeanClass
Alter properties in
the product table
component for
search results.
getApplicationsTablePropertie
sMap
Customize the
query panel
properties.
getQueryPanelPropertiesMap
Customize the
getResultsTableColumnComponen
readOnly property tReadOnlyELExpression
for a component in
search results table
column.
24-47
Table 243 (Cont.) Methods to Override to Customize the Search Task Flow
Customization
Method to Override
Notes
Customize the
getResultsTableColumnProperti
properties on the
esMap
search results table
column for an
attributeDef.
getSearchTaskFlowDataControlS
cope
Add custom
toolbar
components.
getAdditionalToolbarComponent
Definitions
Use the
AdditionalToolbarComponentDef
inition inner class to provide
metadata for the required
component. You can add
components of type CHOICELIST,
BUTTON, SPACER, and SEPARATOR.
getDefaultSearchCriteriaName
NA.
Customize the
generated search
task flow XML.
customizeGeneratedSearchTaskf
low
Example 249
24.13.2.1.6 How to Create a Metadata Provider Implementation Class If you have created
customizer wrapper classes for a flexfield business component, you must create a
wrapper of the default UIModelerMetadataProviderImpl implementation class for that
business component. This class is in the oracle.apps.fnd.applcore.flex.uimodeler
package.
Override the appropriate methods in the following list to return the names of the
custom wrapper classes. For example, if you created a custom wrapper class to
customize the search task flow, you would override the
getSearchRegionCustomizerClassName method, as shown in Example 2410. Override
only the methods that correspond to the classes for which you have created custom
wrappers. In the case of a SearchRegionCustomizerImpl custom wrapper, the method
that you override depends on whether the wrapper customizes the interface search UI
or the regular search UI. If the wrapper customizes the interface search UI, override
the getInterfaceSearchRegionCustomizer method. Otherwise, override the
getSearchRegionCustomizerClassName method.
24-48 Developer's Guide
getContextComponentCustomizerClassName
getContainerPageCustomizerClassName
getPageListCustomizerClassName
getSearchRegionCustomizerClassName
getInterfaceSearchRegionCustomizer
getSingleRowContextRegionCustomizerClassName
getMultiRowContextRegionCustomizerClassName
24.13.2.1.7 How to Register the Metadata Provider Class for the Business Component For the
user interface modeler to use your custom wrapper classes at runtime, you must
register the metadata provider class. To register the class, set the ADFUI_MODELER
column for the business component's row in the FND_DF_FLEXFIELDS_B table to the
name of the UIMetadataProviderImpl implementation class that you created for the
business component.
24-49
Ensure that a stub search view object exists for the flexfield usage. The stub search
view object is in the view folder in the package that you registered for the
extensible flexfield usage in the FND_DF_ADFBC_USAGES table. The name of the
stub search view object begins with j_ and ends with the name of the usage's view
object. You can use the following SQL statement to determine the package name
and view object name for the flexfield usage.
SELECT PACKAGE_NAME, VIEW_OBJECT
FROM FND_DF_ADFBC_USAGES
WHERE TABLE_NAME IN
(SELECT TABLE_NAME FROM FND_DF_TABLE_USAGES TBL WHERE
DESCRIPTIVE_FLEXFIELD_CODE = flexfield-code AND
TBL.APPLICATION_ID = application-id AND
TABLE_TYPE = 'BASE' AND
FLEXFIELD_USAGE_CODE = flexfield-usage-code)
Note:
A service-backed view object must exist for the product table that the flexfield
extends, as described in the "Creating View Objects Backed by SDO Services"
section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
On the View Objects page, in the Select Source Attribute tree expand the
service-based view object in the desired package. In the Select Destination
Attribute tree expand the stub search view object.
For entity-based view objects, notice that in addition to the view object
attributes, relevant associations also appear in the list.
b.
Select the primary key and CategoryCode attributes in both Source and
Destination trees. Then click Add to add the association to the table that is
below the trees.
c.
Click Finish.
2.
In the Application Navigator, double-click the view link that you just created.
3.
In the overview editor, expand the Custom Properties section and add a
SERVICE_PROCESS_CHILDREN property set to true, if one does not already
exist.
4.
5.
6.
In the Java Classes section, click the Edit icon to generate and configure Java
implementation classes.
7.
In the Select Java Options dialog, select Generate Service Data Object Class and
click OK.
Context entity association between base and extension entity objects: Use
getCategoryContextAssocName, which is shown in Example 2413.
Context entity/view object attribute for a given segment code: Use
getContextAttributeName, which is shown in Example 2414.
Categories: Use the various methods shown in Example 2415.
Search view object attributes: Use getSearchVoAttributeNames, which is shown in
Example 2416.
Example 2411
/**
* @param appId - application id
* @param flexCode - flexfield code (e.g. EGO_ITEM_UDA)
* @param flexUsageCode - flexfield usage code (e.g. EGO_ITEM_DL)
* @param txn - DB transaction
* @param contextCode - context code (e.g Voltage)
* @param tableType - table type (e.g. EXTENSION)
* @param effGroup - eff grouping entity name (public / private)
* @return
*/
public static String getContextEoName(Long appId, String flexCode,
String flexUsageCode,
DBTransaction txn,
String contextCode,
String tableType,
String effGroup)
Example 2412
/**
24-51
static
static
static
static
static
static
static
static
static
static
static
static
String
String
String
String
String
String
String
String
String
String
String
String
getCategoryAmNameForWebServices()
getCategoryAmNameForDataEntry()
getCategoryAmNameForInterfaceGeneric()
getCategoryAmNameForInterfaceCategory()
getCategoryAmNameForSearchGeneric()
getCategoryAmNameForSearchCategory()
getCategoryVoNameForDataEntry()
getCategoryVoNameForWebServices()
getCategoryVoNameForInterfaceGeneric()
getCategoryVoNameForInterfaceCategory()
getCategoryContextViewLinkNameForInterfaceGeneric()
getCategoryContextViewLinkNameForInterfaceCategory()
public
public
public
public
public
public
public
static
static
static
static
static
static
static
String getCategoryContextViewLinkNameForSearchCategory()
String getCategoryContextViewLinkNameForSearchGeneric()
String getCategoryContextViewLinkNameForWebService()
String getCategoryContextViewLinkNameForDataEntry()
void useServiceProvider()
String getCategoryVoNameForSearchCategory()
String getCategoryVoNameForSearchGeneric()
Example 2416 Method to Get Hash Map of View Object Attribute Names for EFF Search
View Object
/**
* Get a map of segment codes to search view object attribute names
* @param flexUsageCode - flexfield usage code (e.g. EGO_ITEM_DL)
* @param contextCode - context code (e.g Voltage)
* @param segmentCodeList - segment codes for the map.
* @return map of attribute names with key of segment codes
*/
public static HashMap<String, String> getSearchVoAttributeNames(
String flexUsageCode,
String contextCode,
ArrayList<String> segmentCodeList)
Column
Value
ENTERPRISE_ID
TABLE_NAME
TABLE_USAGE_CODE
APPLICATION_ID
DESCRIPTIVE_
FLEXFIELD_CODE
FLEXFIELD_USAGE_CODE The code for the flexfield usage (the save value as the table
usage code).
24-53
Value
TABLE_TYPE
COLUMN_NAME
Null
DESCRIPTION
Table 245
Column
Value
TABLE_NAME
TABLE_USAGE_CODE
ENTITY_OBJECT
EFF_GROUP_NAME
"Private"
PACKAGE_NAME
OBJECT_NAME_PREFIX
DEPLOYMENT_STATUS
Null
DEPLOYMENT_ERROR_MESSAGE Null
APPLICATION_MODULE
VIEW_OBJECT
ENTITY_OBJECT_TL
EFF_SEARCH_VIEW_OBJECT
24.17.2 How to Support Parallel Sets of Extensible Flexfield Artifacts for Different Uses
If you require parallel sets of extensible flexfield artifacts generated for different uses
(for example, public view objects and private view objects), replicate the entries in the
FND_DF_ADFBC_USAGES table for that flexfield and use a different group name.
When the business components are generated for the flexfield, a separate set of
components is generated for each group name.
The following figure shows example entries for a flexfield usage. The FND_DF_
TABLE_USAGES table contains rows for the product table (USGA_BASE), the usage
base extension table (USGA_EFF_B), and the usage translation extension table (USGA_
EFF_TL). The FND_DF_ADFBC_USAGES table contains two entries for each entry in
the FND_DF_TABLE_USAGES table one for the Private group and one for the
24-54 Developer's Guide
Public group. Each row names the entity object and the view object. The rows for the
translation extension table also name the entity object from the translation extension
table. Note that not all columns are shown.
In this example, the Public group is necessary because the
product that is using the flexfield usage requires a parallel set of
extensible flexfield artifacts generated for public view objects.
Note:
Figure 2412
FND_DF_TABLE_USAGES
DESCRIPTIVE_FLEXFIELD_CODE FLEXFIELD_USAGE_CODE TABLE_NAME
TABLE_TYPE
TABLE_USAGE_CODE
ABC_EFF
ABC_USG_A
USGA_BASE
BASE
ABC_USG_A
ABC_EFF
ABC_USG_A
USGA_EFF_B
EXTENSION
ABC_USG_A
ABC_EFF
ABC_USG_A
FND_DF_ADFBC_USAGES
EFF_GROUP_NAME TABLE_USAGE_CODE TABLE_NAME
Private
ABC_USG_A
USGA_BASE
BaseEO
Private
ABC_USG_A
USGA_EFF_B
EFFBEO
Private
ABC_USG_A
USGA_EFF_TL EFFVLEO
Public
ABC_USG_A
USGA_BASE
BasePEO
Public
ABC_USG_A
USGA_EFF_B
EFFBPEO
Public
ABC_USG_A
USGA_EFF_TL EFFVLPEO
BaseVO
EFFBVO
EFFTLEO
EFFVLVO
BasePVO
EFFBPVO
EFFTLPEO
EFFVLPVO
24-55
25
Using Key Flexfields
25
This chapter discusses how to use key flexfields in Oracle Fusion applications to access
data that is presented by different customers using different combinations of fields,
and to customize the presentation of that information to customers in a way that is
most appropriate for them.
This chapter includes the following sections:
Section 25.3, "Completing the Consumer Tasks for Key Flexfields in Reference
Mode"
Section 25.4, "Employing Key Flexfield UI Components on a Page."
to meet that different need. Key flexfields let developers satisfy different customers
without having to reprogram the applications.
You can use key flexfields in many applications. For example, you could use a Part
flexfield in an inventory application to uniquely identify parts. Your Part flexfield
could contain such segments as product class, product code, size, color and packaging
code. You could define valid values for the color segment, for example, to range from
01 to 10, where 01 means red, 02 means blue, and so on. You could even specify
cross-validation rules to describe valid combinations of segment values. For example,
products with a specific product code may be available only in certain colors.
25.1.2 How Key Flexfields Are Modeled in Oracle Application Development Framework
Flexfields are modeled as a collection of Oracle Application Development Framework
(Oracle ADF) polymorphic view rows, as described in the "Working with Polymorphic
View Rows" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
In a polymorphic collection, each view row can have its own set of attributes, and all
rows have at least one common attribute, the discriminator. The discriminator
determines which view row type is used. Given a collection of polymorphic view
rows, each row can be a different type. When a polymorphic collection of rows is
created, Oracle ADF selects the correctly-typed view definition for the row to be added
based on the value of the discriminator attribute.
Key flexfield segments are exposed as view row attributes in the order that they are
defined in the flexfield's metadata. The code combination ID (CCID) and structure
instance number (SIN) segments are exposed as attributes in the base view object of
the polymorphic collection. Every code combination structure is modeled as an
extended view object of the base view object. That is, an extended view object is
created for every structure instance number. These extended view objects, which are
referred to as subtype view objects, expose the key flexfield segments as
subtype-specific view attributes. The structure instance number is exposed as the
discriminator attribute of the polymorphic view rows. For more information about
code combination IDs and structure instance numbers, see Section 25.2.1.1, "Creating
the Combinations Table."
You use the Create Entity Objects wizard to generate the base view object that is based
on the key flexfield definition, then create a view link to connect the reference view
object (the view object for the database table that the key flexfield extends) and the
base view object. You can then use the base view object to add the flexfield to a user
interface page. For more information about the generation of base and subtype view
objects, see Section 25.2.4, "How to Create Key Flexfield Business Components."
Because flexfield view objects are modeled as polymorphic view objects, you can use
key flexfield view objects in the same manner that you use any other polymorphic
view objects, and they will behave in the same way. This includes support for
flexfields in ADF Desktop Integration. For more information, see the Oracle Fusion
Middleware Desktop Integration Developer's Guide for Oracle Application Development
Framework.
secondary table. When you work with a primary usage you are working in reference
mode. When you work with a secondary usage, you are working in secondary mode.
Note:
All-segment secondary usage: In this mode, the secondary table has columns for
all of the key flexfield segments.
Single-segment secondary usage: In this mode, the secondary table has only one
key flexfield segment column.
If you have determined that a particular key flexfield is needed or would be useful
within a particular application, and there is not yet a combinations table to
support it, see the producer development tasks covered in Section 25.1.5.3,
"Understanding the Key Flexfield Producer Development Tasks."
If there is already a combinations table for the key flexfield that you want to
implement, see the consumer development tasks covered in Section 25.1.5.4,
"Understanding the Key Flexfield Consumer Development Tasks."
To incorporate key flexfield secondary usages into your application, see Section 26.3,
"Completing the Development Tasks for Key Flexfields in Secondary Mode."
To employ key flexfield code-combination filters in your application, see Section 26.4,
"Working with Code-Combination Filters for Key Flexfields."
Figure 251 provides an overview of producer and consumer roles as they apply to the
creation and configuration of the necessary key flexfield business components and
associated artifacts. Section 25.1.5.3, "Understanding the Key Flexfield Producer
Development Tasks" and Section 25.1.5.4, "Understanding the Key Flexfield Consumer
Development Tasks" define the producer phases and summarize the steps for creating
the components and artifacts shown in Figure 251.
Consumer
Figure 251 Key Flexfield Development Roles, Business Components and Supporting
Artifacts
Producer Phase 2
Flexfield
View Link
Polymorphic
ViewFlexfield
Objects
Reference
Reffere
Reference
encceKey
K
Ke
Key
ey Fle
Flexfield
Flexfiel
lex
exfie
xffie
eld
ld
for
the Key Flexfields
Polymorphic
cicVOs
Polyymo
Polymorphic
orp
phic
VO
VO
Os
VOs
Reference Model
Reference Table
(Product Table with a
Foreign Key
Reference to the
Combinations Table)
Combinations
Table
Producer Phase 1
Flexfield
View Link
Polymorphic
View
Objects for the
Maintenance
M
Mainten
Maintenance
nan
nce
eKey
Key
Ke
K
eyyFlexfield
Flexfiel
Flexfield
Fle
exf
xfiel
fiel
ielld
Flexfields
Maintenance Model
Polymorphic
VOs
Polymorph
Polymorphic
y rphicVOs
VOs
VO
Note:
The key flexfield producer builds the appropriate models to support maintenance
mode and dynamic combination insertion.
A cross-validation rule applies a pair of filters to new code combinations that are
proposed for a key flexfield by implementors.
At registration time, you must enable the key flexfield for cross-validation. Then you
create a maintenance user interface that administrators of your application can
subsequently use to define each cross-validation rule as a pair of code-combination
filters: one to establish the condition for evaluating the rule, and the other to specify
which code combinations are valid under that condition.
Custom Validation Callouts
There are two PL/SQL custom validation callout procedures that can be defined for a
given key flexfield: one for application development use, and one reserved for
customers. These callouts can be used to enforce any custom validation logic that you
want to apply to new code combinations beyond what has been defined for
cross-validation rules.
You define custom validation logic with a standard signature for the customer callout.
You then register your callout with the key flexfield. The custom validation callout will
automatically be called before any new combination is inserted using dynamic
insertion in C and PL/SQL.
2.
Tip:
3.
Optionally, share your key flexfield business components with other developers
using an ADF library.
For more information, see Section 25.2.5, "How to Share Key Flexfield Business
Components."
4.
5.
6.
If your product table already has a foreign-key reference to the key flexfield's
combinations table, and the flexfield producer who owns that metadata has provided
you with the appropriate business components, you can proceed to incorporate the
flexfield into your application. You should have already created an entity object and
view object for the product table, which is referred to as the reference table.
To complete the consumer development tasks:
1.
As shown in Figure 251, create a view link between the view object for the
reference table and the polymorphic view objects for the key flexfield's reference
model.
See Section 25.3.1, "How to Create Key Flexfield View Links."
2.
Nest the key flexfield application module instance in the product application
module.
See Section 25.3.2, "How to Nest an Instance of the Key Flexfield Application
Module in the Product Application Module."
3.
Add a key flexfield view object instance to the product application module.
See Section 25.3.3, "How to Add an Instance of a Key Flexfield View Object to the
Product Application Module."
4.
5.
After completing these tasks, you can test specified flexfields from JDeveloper using
the Run with Flexfields dialog or the Debug with Flexfields dialog. You can also test
the flexfields by running the application from an Integrated WebLogic Server instance.
For more information, see Section 27.4, "Testing Flexfields."
After you have completed the key flexfield development process and delivered your
application, implementors can use the Manage Key Flexfields task flow to define and
configure the structures, structure instances, segments, and segment instances for each
key flexfield. This will determine how the flexfield's segments will be populated,
organized, and made available to end users within the application.
To make the Manage Key Flexfields task flow available to application implementors
and administrators, you register it with Oracle Fusion Functional Setup Manager. For
more information, see Section 27.8, "Integrating Flexfield Task Flows into Oracle
Fusion Functional Setup Manager."
Note:
2.
Create foreign key columns to associate a product table with the combinations
table. The product table is referred to as the reference table.
3.
Optionally, include the key flexfield segments in product tables for secondary
usages.
4.
Optionally, create filter columns for defining which key flexfields the user can
filter.
5.
6.
7.
8.
9.
Note:
The combinations table must have a code combination ID (CCID) column (type
NUMBER) that identifies each data row.
The combinations table can have an optional structure instance number (SIN) column
(type NUMBER) with generated values that identify different validation sources for a
given structure. These generated values are unique within a given flexfield. Multiple
SIN values exist for a key flexfield if you elect to define the flexfield with multiple
alternate structure instances.
A given structure (arrangement of segments) can have several structure instances. The
structure instances share the same arrangement of segments, but use different value
sets to validate the segments (for example, one group of value sets for the United
States. and another for France). Each structure instance is identified by a SIN.
The combinations table might also have a data set number (DSN) column (type
NUMBER), but only if you have elected to data set-enable your key flexfield code
combinations. A DSN column enables you to tag sets of combination codes with your
own numeric IDs. For example, you can use it to stripe (partition) the data into subsets
by ORGANIZATION_ID. ADF Business Components supports the DSN by including
it as part of the table's primary key. Your SQL code can then select code combinations
from this table using a more qualified primary key.
Data sets are used by specific application-development teams.
If your team does not use data sets, you can ignore the references to
DSNs in this guide.
Note:
A DSN is not the same thing as a set ID. Set ID partitioning is not
supported by flexfields. For information about set IDs, see Chapter 8,
"Managing Reference Data with SetIDs."
The table's primary key is composed of a combination of the CCID, SIN, and DSN
columns depending on the conditions listed in Table 251.
Table 251
Column
CCID
Always
SIN
DSN
The combinations table must include the columns listed in Table 252. These columns
indicate whether a combination is enabled and active. The column names and data
types must match exactly.
Table 252
Column
Data Type
Description
ENABLED_FLAG
VARCHAR2(1)
NOT NULL
START_DATE_ACTIVE
DATE
END_DATE_ACTIVE
DATE
Include one column for each flexfield segment that you or your customers might wish
to customize. You need at least as many columns as the maximum number of
segments an end user would ever want in a single key flexfield structure. The columns
must be of type VARCHAR2 or NUMBER. If the type is VARCHAR2, the length must be at least
30 characters.
Tip: There are no constraints on how to name the segment columns.
However, these columns are typically named using the patterns
SEGMENTn_VARCHAR2 and SEGMENTn_NUMBER. This
convention makes it easy to identify the key flexfield segments. It also
makes it easier to name the columns for secondary usages of the key
flexfield.
If the key flexfield defines value attributes, you must include one derived value
attribute column of type VARCHAR2 for each value attribute. For more information
about value attributes, see Section 25.2.2, "How to Implement Key Flexfield Segment
Labels."
Note: The combinations table may contain other columns than those
described here. If the key flexfield is dynamic insert-enabled, these
other columns should either allow null values or they should have
default database values.
flexfield. The product tables that contain the foreign key references are referred to as
reference tables.
A page whose underlying entity objects contain a foreign key
reference to the combinations table is referred to as a
code-combination reference page, while a page whose underlying
entity objects use the combinations table itself is referred to as a
combination maintenance page.
Note:
25.2.1.5 Registering and Defining Key Flexfields Using the Setup APIs
Before you can use a key flexfield in an application, you must first define and register
the flexfield using procedures from the FND_FLEX_KF_SETUP_APIS PL/SQL package.
This package also has procedures for updating, deleting, and querying flexfield
definitions.
The definition of a key flexfield includes the following information:
25-11
1.
2.
3.
25.2.1.6 What You May Need to Know About the Key Flexfield Setup API
In the key flexfield development process, you use the FND_FLEX_KF_SETUP_APIS
PL/SQL package to manage flexfield registration data.
You can learn about the FND_FLEX_KF_SETUP_APIS PL/SQL package by running the
following command, which produces package documentation and usage examples to
the <db_name>_<user_name>_FND_FLEX_KF_SETUP_APIS_<date>.plsqldoc file.
sqlplus <fusion_user>/<fusion_pwd>@<fusion_db> \
@/ORACLE/fusionapps/atgpf/applcore/db/sql/flex/fnd_flex_pkg_doc.sql \
FND_FLEX_KF_SETUP_APIS
25.2.1.7 Enabling Multiple Structure, Multiple Structure Instance, and Data Set
Features
To enable the multiple structure, multiple structure instance, or data set features for a
registered key flexfield, you must run the enable_feature(...) procedure from the
FND_FLEX_KF_SETUP_APIS PL/SQL package. To enable the multiple structure feature
or multiple structure instance feature, you provide the SIN column name. To enable
the data set feature, you provide the DSN column name.
To learn how to generate documentation about using the enable_feature(...)
procedure, see Section 25.2.1.6, "What You May Need to Know About the Key Flexfield
Setup API."
The full class name of the entity object. For the primary usage, this is the entity
object that was defined for the combinations table. For a secondary usage, this is
the entity object that was defined for the secondary table.
A prefix from which to derive the names of generated objects.
The package in which to place the generated business components. Each usage
must have its own package name.
You register entity details using the create_adfbc_usage(...) procedure from the
FND_FLEX_KF_SETUP_APIS PL/SQL package.
Register the usage as described in Section 25.2.1.5, "Registering and Defining Key
Flexfields Using the Setup APIs."
2.
Ensure that the entity object for the usage's table exists.
25-13
Note:
Global
Flag
Required
Flag
Unique
Flag
Result
For example, in the Oracle General Ledger Accounting flexfield, the Account segment
label is required and unique because Oracle General Ledger requires one and only one
account segment.
You create segment labels using the create_segment_label(...) procedure from the
FND_FLEX_KF_SETUP_APIS PL/SQL package.
Before you begin:
Define the key flexfield as described in Section 25.2.1.5, "Registering and Defining Key
Flexfields Using the Setup APIs."
To learn how to generate documentation about using the create_segment_
label(...)procedure, see Section 25.2.1.6, "What You May Need to Know About the
Key Flexfield Setup API."
To define key flexfield segment labels:
Define the key flexfield as described in Section 25.2.1.5, "Registering and Defining
Key Flexfields Using the Setup APIs."
2.
Define the segment label as described in Section 25.2.2.1, "Defining Key Flexfield
Segment Labels."
Cross-validation rules
2.
3.
25-15
Before you can build a user interface for maintaining a key flexfield's cross-validation
rules, you must first have created and configured the business components for the key
flexfield.
For more information, see Section 25.2.4, "How to Create Key Flexfield Business
Components."
To learn how to generate documentation about using the FND_FLEX_KF_SETUP_APIS
PL/SQL package, see Section 25.2.1.6, "What You May Need to Know About the Key
Flexfield Setup API."
To implement cross-validation rules:
1.
To enable a key flexfield to use cross-validation rules, set the value of the flexfield's
CVR_ENABLED_FLAG column in the FND_KF_FLEXFIELDS_B table to Y. This
flag is a required VARCHAR2(1).
Note: Setting the value of CVR_ENABLED_FLAG to Y enables
support for any cross-validation rules you define for the flexfield.
Support for cross-validation is somewhat resource-intensive, so assess
each key flexfield to determine if cross-validation is really necessary.
For example, if the creation of new code combinations for a given key
flexfield will be a tightly controlled process that requires
organizational oversight, cross-validation might be redundant.
2.
Table 254
Column
Type
Null
Allowed?
ENTERPRISE_ID
NUMBER(18)
No
STRUCTURE_INSTANCE_ID
NUMBER(18)
No
RULE_CODE
VARCHAR2(30)
No
DESCRIPTION
VARCHAR2(240)
Yes
Rule description.
CONDITION_FILTER
XMLTYPE
Yes
Description
Type
Null
Allowed?
VALIDATION_FILTER
XMLTYPE
Yes1
ERROR_MSG_APPLICATION_
ID
NUMBER(18)
Yes
Message application.
ERROR_MSG_NAME
VARCHAR2(30)
Yes
ENABLED_FLAG
VARCHAR2(1)
No
START_DATE_ACTIVE
DATE
Yes
END_DATE_ACTIVE
DATE
Yes
WHO columns2
Description
Although the validation filter column must allow null values in the data model, it is still a required value
that is logically necessary for cross-validation to work.
For more information about WHO columns, see Section 9.3, "Using WHO Column Features."
The primary key for this table is the combination of the ENTERPRISE_ID,
STRUCTURE_INSTANCE_ID, and RULE_CODE columns.
The cross-validation rule itself is the combination of a condition filter (when to
apply the rule) and a validation filter (how to validate the code combination) in
the corresponding XMLType columns of the repository table. These filters are
compatible with, and supported by the same infrastructure that supports
code-combination filters, as described in Section 26.4, "Working with
Code-Combination Filters for Key Flexfields."
The value of each of these filters should be a logical combination of boolean
expressions. At runtime, all filters from the repository table that match the
application, key flexfield, and SIN of the newly submitted code combination are
retrieved, converted into SQL fragments, and used to validate the proposed code
combination.
The condition filter establishes the condition that a proposed new code
combination must fulfill to qualify for validation. If it qualifies, the code
combination is evaluated against the validation filter. This is demonstrated by
Example 251.
Example 251
25-17
If the proposed code combination is three segments with the following values, the
validation will succeed:
segment1 = '8'
segment2 = '30'
segment3 = '70'
If the proposed values are as follows, the condition is not met, and the code
combination will not be subject to the validation filter:
segment1 = '12'
segment2 = '40'
segment3 = '70'
This means that even though this combination would have failed the validation
filter, it is still considered valid because the validation filter was not applied. A
code combination fails cross-validation only if it passes the condition filter, but
fails the validation filter.
Note: There are no artificial restrictions on what each filter can
contain. If you set the condition filter to a null value, all new code
combinations for the flexfield will qualify to be evaluated with the
validation filter.
2.
Register the procedure as the customer callout along with the key flexfield to
which it will apply.
The PL/SQL validation procedure must have the signature shown in Example 252.
Example 252
my_comb_table is the name of the combinations table for this key flexfield. When
passed, every column in the NEW_CODE_COMBINATION record will be populated with the
values of the combination that is about to be inserted. Payload columns (columns that
are not part of the primary key) in the combinations table that are not related to the
flexfield will be passed as null values.
Column
Type
Description
DEVELOPER_VAL_CALLOUT
VARCHAR2(80) Yes
CUSTOMER_VAL_CALLOUT
VARCHAR2(80) Yes
25-19
If the combinations table has other fixed (nonflexfield) columns, then they are not
included in these view objects.
No Java implementation classes are generated for key flexfield view objects. The
product view object may or may not have Java implementation classes.
When you create and configure your key flexfield business components, you can
decide whether to support maintenance mode (for administrators) or dynamic
combination insertion (for end users). For most implementations of a key flexfield,
there are two major tasks that you will typically need to complete:
1.
2.
These entity objects are directly modeled on the combinations tables; hence they
contain the fixed (nonflexfield) columns, if any, along with all of the flexfield
columns. In general, all columns should be included.
The package name and the object name prefix for each entity object are registered
with the ADF Business Components usage to which it will provide data, as
described in Section 25.2.1.9, "Registering Entity Details Using the Setup APIs."
2.
3.
4.
25.2.4.1.1 How to Create Key Flexfield Business Components for a Maintenance Model The
first element in a writable maintenance model is a set of business components.
To implement this model, you must select the Maintenance Mode checkbox when you
encounter it on the Usage Settings page, as described in the following procedure.
Before you begin:
1. Create an updatable entity object for the combinations table and add it as an ADF
Business Components usage for your key flexfield, as described in Section 25.2.1.9,
"Registering Entity Details Using the Setup APIs."
The entity object that you select must allow maintenance operations such as
Update or Insert. The entity object class must extend the
oracle.apps.fnd.applcore.oaext.model.KFFMEntityImpl class, and the entity
definition class must extend the
oracle.apps.fnd.applcore.oaext.model.KFFMEntityDefImpl class.
25-21
Create a master view object for the combinations table based on the same
updatable entity object.
This view object typically contains your payload attributes, and should not
include flexfield attributes.
In the master view object, ensure that the CCID attribute's Display control hint is
set to Hide.
3.
Build the project to ensure that the entity objects are available in the project's
classes. The Create Flexfield Business Components wizard relies on what is in the
project's classes.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Business Components, and click OK.
3.
On the Flexfield page of the Create Flexfield Business Components wizard, select
Key from the Type dropdown list, as shown in Figure 253.
4.
In the Application field, specify the full name of the application to which your key
flexfield belongs.
You can browse for the name, and filter by ID, Short Name, or Name.
5.
In the Code field, specify the code of the key flexfield you want to use.
You can browse for and filter by Code.
6.
In the Usage section, select the table row that contains the primary usage of the
key flexfield as it is defined on its combinations table. Every key flexfield has
exactly one primary usage.
To identify the primary usage, the Usage Code field for this type is typically the
same as the flexfield code. The Table Name field displays the name of the
combinations table, and the text in the Description field does not contain the
prefix (Partial) or (Partial Single) in parentheses.
You must select the primary usage in this procedure because you are generating
key flexfield business components for the combinations table for your
maintenance model.
7.
On the Path page, select the path of the directory structure in which to create the
flexfield business components and click Next.
8.
On the Entity Object page shown in Figure 254, select the entity object for the
combinations table. It must allow maintenance operations such as update or insert,
and include all of the attributes that will be referenced by the flexfield. For the key
flexfield primary usage, this includes attributes that represent the CCID, SIN, and
segment columns, and the DSN column if it exists in the combinations table.
If you select a polymorphic entity object, ensure that the
InheritPersonalization property for every subtype entity is set to
true.
Note:
Figure 254 Create Flexfield Business Components Wizard Entity Object Page
9.
You might wish to select an entity object for which the key flexfield attributes are
defined as transient (not based on database table columns). If you need to do this,
then select The names of flexfield attributes match the names of registered
columns exactly; do not check the underlying columns.
When a key flexfield entity object attribute is transient, there is no matching
underlying column name. When you select this option, the system will match the
entity object attribute names to the key flexfield column names, and use the
25-23
matching attributes to access the flexfield data. Ensure that the entity object has a
full set of attributes with matching names before you select this option.
This entity object must be registered under the primary usage. There is no need to
register another table for this purpose, even if the entity object is based on some
other table. See Section 25.2.1.9, "Registering Entity Details Using the Setup APIs,"
for more information about registering ADF Business Components usage.
Caution: The Create Flexfield Business Components wizard is
case-sensitive. All column names and the names of the flexfield
entity object attributes associated with them must be uppercase.
10. Click Next. The Usage Settings page appears.
Because you specified the primary usage of the key flexfield on the Flexfield page
of this wizard, this page contains a Maintenance Mode checkbox.
Select Maintenance Mode to build your maintenance model.
11. Click Next. The Naming page displays the entity object's package name and object
name that you registered for the usage, as described in Section 25.2.1.9,
"Registering Entity Details Using the Setup APIs." Click Next.
12. On the Summary page, review your choices and click Finish.
The business components generated will replace any existing ones that are based
on the same flexfield.
This wizard might fail with a "ClassNotFound" exception
message. This indicates that one or more required libraries have not
been automatically included in your project, notably the BC4J
Service Runtime, Java EE 1.5 and Java EE 1.5 API libraries. You
can resolve this issue by manually adding any missing libraries; then
you can complete this procedure successfully.
Note:
13. Refresh the project to see the newly created flexfield business components in the
Application Navigator.
25.2.4.1.2 How to Link the Master View Object to the Maintenance Model Key Flexfield Business
Components You must create a flexfield view link from the master view object for the
combinations table to the maintenance key flexfield business components. This enables
your maintenance user interface to access all of the combinations table columns using
the linked view objects for the combinations table entity object.
The master view object and the key flexfield's base view object are linked through the
combination of a CCID, and SIN, and if present, a DSN.
To create a view link for the key flexfield maintenance model:
1. In the Application Navigator, right-click the project and choose New.
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield View Link, and click OK.
3.
In the Create Flexfield View Link wizard, on the Name page, provide a package
name and a view link name, and click Next.
4.
In the Select Source View Object tree, expand the available objects from the
current project and select the master view object for the combinations table, as
shown in Figure 255.
Figure 255 Create Flexfield View Link Wizard View Objects Page
5.
In the Select Destination Flexfield tree, expand the available flexfield view objects
from your project and select your maintenance key flexfield view object as the
destination.
6.
In the View Link Accessor Name field, enter an appropriate name for the view
link accessor.
7.
Note:
If you see any controls on this page for selecting source attributes, you
are not using maintenance mode business components. Return to
Section 25.2.4.1, "Building a Writable Maintenance Model" and
re-create your maintenance mode business components according to
the instructions.
8.
9.
25.2.4.1.3 How to Create the Maintenance Application Module You must create the
maintenance application module for the key flexfield. The application module contains
the combination view object, the maintenance model view link, and the key flexfield's
application module that was created when you created the business components in
Section 25.2.4.1.1, "How to Create Key Flexfield Business Components for a
25-25
Maintenance Model."
For more information about creating application modules and nesting application
model instances, see the "Implementing Business Services with Application Modules"
chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
Before you begin:
1. Create the business components as described in Section 25.2.4.1.1, "How to Create
Key Flexfield Business Components for a Maintenance Model."
2.
Create the view link as described in Section 25.2.4.1.2, "How to Link the Master
View Object to the Maintenance Model Key Flexfield Business Components."
In the New Gallery, expand Business Tier, select ADF Business Components and
then Application Module, and click OK.
3.
In the Create Application Module wizard, on the Name page, provide a package
name and an application module name, and click Next.
4.
In the Data Model page, move the master view object for the combinations table
and the maintenance model view link to the Data Model list, as shown in
Figure 256.
Tip: The object name prefix and package name are used to name the
flexfield business components, and are defined in the database along
with the key flexfield.
5.
6.
On the Application Modules page, in the Available tree, move the appropriate key
flexfield application modules to the Selected list, as shown in Figure 257. Include
the key flexfield application module that was created when you created the
business components in Section 25.2.4.1.1, "How to Create Key Flexfield Business
Components for a Maintenance Model."
Figure 257 Create Application Module Wizard Application Modules Page
Note:
7.
When you complete the Create Application Module wizard, right-click the new
application module instance and choose Run to test it.
The maintenance application module must have a
configuration named appmodule_nameLocal. By default, this is created
for you. For example, if the application module is called
MyKffMaintAM, then a configuration named MyKffMaintAMLocal must
exist.
Note:
25-27
If you wish to completely overwrite doDML with your own implementation, you can
turn the automatic locking off by calling setAutoCombinationLockEnabled(false),
then calling lockCombination(DBTransaction) on your own. For more information,
see the Java documentation for
oracle.apps.fnd.applcore.oaext.model.KFFMEntityImpl.
Set the :app_id to the application_id that was specified when the flexfield was
created, and set :kff_code to the flexfield's key_flexfield_code. For more
information, see Section 25.2.1.6, "What You May Need to Know About the Key
Flexfield Setup API."
2.
Issue the following SQL statement to set the name of the application module to be
used for dynamic combination insertion:
update fnd_kf_flexfields_b
set application_module_name = 'fully qualified name of application module'
where application_id = :app_id
and key_flexfield_code = :kff_code
The name of the application module must be fully qualified; for example,
mycompany.myproduct.flex.kff1.applicationModule.Kff1AM.
Set the :app_id to the application_id that was specified when the flexfield was
created, and set :kff_code to the flexfield's key_flexfield_code. For more
information, see Section 25.2.1.6, "What You May Need to Know About the Key
Flexfield Setup API."
25.2.4.2.2 Inserting a Code Combination the Simplest Case In the simplest case, you need
only replace the existing base object class,
oracle.apps.fnd.applcore.oaext.model.OAApplicationModuleImpl, with
25-28 Developer's Guide
oracle.apps.fnd.applcore.oaext.model.KFFCombinationCreatorImpl.
KFFCombinationCreatorImpl extends OAApplicationModuleImpl.
This implementation is possible only under the following conditions:
You have no custom Java application module class for this application module.
Only one key flexfield application module instance is nested in this application
module, and that nested instance is the one that represents the key flexfield of
interest.
You do not need to update any columns of the combinations table, including the
value attribute columns.
25.2.4.2.3 Inserting a Code Combination with Added Combination Attributes To insert a code
combination with added combination attributes, you implement the
KFFCombinationCreator Java class in the maintenance application module, and you
create a Java implementation of the maintenance application module. You can
optionally initialize the columns.
1.
sin: The structure instance number. This should be null if this key flexfield
does not allow multiple structures.
dsn: The data set number. This should be null if this key flexfield does not use
data set numbers.
segValues: A read-only list of segment values.
Generate a Java application module class to extend your existing base object class.
By default, the base class is OAApplicationModuleImpl from the
oracle.apps.fnd.applcore.oaext.model package. An example of an application
module class is shown in Example 253.
Example 253
Implementing KFFCombinationCreator
25-29
Get the list of value attribute codes for a label used in this flexfield.
Get the current value of a value attribute column of the combinations table.
25-31
System.out.println("
}
System.out.println();
// Get the current combination start date.
System.out.println("StartDateActive = "
+ combAttrs.getValueAttribute(null,
FlexfieldSegmentValue.VALUE_ATTR_START_DATE_ACTIVE));
// Get the current combination end date.
System.out.println("EndDateActive = "
+ combAttrs.getValueAttribute(null,
FlexfieldSegmentValue.VALUE_ATTR_END_DATE_ACTIVE));
// Get the current combination enabled flag.
System.out.println("EnabledFlag = "
+ combAttrs.getValueAttribute(null,
FlexfieldSegmentValue.VALUE_ATTR_ENABLED_FLAG));
// You can update the standard value attributes by calling
// combAttrs.setValueAttributes(Map).
}
4.
If you want to initialize other columns of the combinations table, first include
them in the master view object. After insertCombination is called, the new entity
will be available to the master view object as well, as shown in Example 255,
which shows an alternative version of MyKffMaintenanceAM.java.
Example 255
View Object
+ sin);
}
}
Example 256
Implementing KFFCombinationCreatorProxy
25-33
3.
Note:
For more information, see Section 25.2.4, "How to Create Key Flexfield
Business Components."
Before you begin:
Create a read-only entity object for your combinations table and add it as an ADF
Business Components usage for your key flexfield, as described in Section 25.2.1.9,
"Registering Entity Details Using the Setup APIs."
To create key flexfield business components for a read-only reference model:
1.
Complete Step 1 through Step 8 in Section 25.2.4.1.1, "How to Create Key Flexfield
Business Components for a Maintenance Model."
2.
On the Entity Object page, expand the tree of available models and select the
read-only entity object that you created for the combinations table.
The entity object you select must include all of the attributes that will be
referenced by the flexfield. For the key flexfield primary usage, this includes
attributes that represent the CCID, SIN, and segment columns, and the DSN
column if it exists in the combinations table.
3.
Create your shared ADF library containing the business components from the
read-only reference model you just built, then add the business components from the
writable maintenance model as well.
To create an ADF Library JAR file:
1.
Right-click the project you wish to share and select Project Properties from the
menu.
2.
Select Deployment.
3.
If a deployment profile is already listed, you can verify that it is for an ADF
Library JAR file. Open the profile for editing and observe the window title to
confirm that it says "Edit JAR Deployment Profile Properties."
If you do not already have an appropriate deployment profile, you can create one:
4.
a.
b.
In the New Gallery, expand General, select Deployment Profiles and then
ADF Library JAR File, and click OK.
c.
In the Create Deployment Profile ADF Library JAR File dialog, enter a
name for the profile and click OK.
Right-click the project you wish to share and select Deploy > deployment_profile_
name > To JAR File.
The JAR file is created in your project's deploy directory as deployment_profile_
name.jar. You can send it to other developers for use in their projects.
Obtain an ADF Library JAR file from another developer and save it to an
accessible directory for importing.
2.
Right-click the project where you want to import the components and select
Project Properties.
3.
4.
Click Import, then go to the location of the ADF Library JAR file.
5.
25-35
To enable end users to select key combinations for new rows, ensure that you provide
a default value for every Structure Instance Number attribute.
Drag the master view object from the application module onto the page, and add it
as either a form or a table.
3.
Select the key flexfield view object and drag it onto the page. Drop the flexfield
view object onto the form or table that you just created.
For more information, see Section 25.4, "Employing Key Flexfield UI Components on a
Page."
If the Structure Instance Number is static, set the Value Type to Literal, and
specify the static value as the default.
If the Structure Instance Number is dynamic, set the Value Type to Expression,
and enter a Groovy expression to retrieve the appropriate Structure Instance
Number value and set it as the default.
Note: Use the defaultSIN attribute in the JSPX file to define the
default Structure Instance Number value for situations where no rows
exist.
For an Applications Table component, if the end user deletes all rows
from the table, your application can again set a new default Structure
Instance Number value for the first new row, and the column
structure corresponding to that Structure Instance Number will be the
valid structure for the table.
For an ADF Table, the column structure (determined by the initial
Structure Instance Number value) cannot be changed after the table
has been created, even if all rows are deleted.
For more information about setting attribute defaults, see the discussion about
defining default values in the "Setting Attribute Properties" section of the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
2.
3.
Create a view link from your (consumer) product view object to the producer's key
flexfield view object.
2.
Nest the producer's key flexfield application module instance in the (consumer)
application module for the application.
3.
Add a key flexfield view object instance to the (consumer) application module for
your application.
After you complete the consumer tasks, you can incorporate the key flexfield UI
components into your application as described in Section 25.4, "Employing Key
25-37
Ensure that the flexfield library JAR files that were created by the producer team
have been added to your project. For more information about library JAR files, see
Section 25.2.5.1, "Creating an ADF Library JAR File" and Section 25.2.5.2,
"Importing Business Components from an ADF Library."
You should have already created an entity object and a view object for the
reference table (the product table with a foreign key reference to the combinations
table). You use the reference table's view object for the source of the view link.
Ensure that the view object does not include flexfield attributes such as
SEGMENT1_VARCHAR2, SEGMENT2_NUMBER, and so on. Ensure that you
include the attributes that are needed for the foreign key reference, such as CCID,
SIN, and, if present, DSN. Ensure that the CCID attribute's Display control hint is
set to Hide.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield View Link, and click OK.
3.
In the Create Flexfield View Link wizard, on the Name page, provide a package
name and a view link name, and click Next.
4.
In the View Objects page, in the Select Source View Object tree, expand the
available objects from your current project and select a source view object.
5.
In the Select Destination Flexfield tree, expand the available flexfield view objects
from your project and select the key flexfield's base view object with which you
want to associate the source view object.
6.
In the View Link Accessor Name field, enter an appropriate name for the view
link accessor.
7.
Click Next. The Source Attributes page appears, as shown in Figure 258.
Figure 258 Create Flexfield View Link Wizard Source Attributes Page for Key
Flexfields
8.
From the Code-Combination ID dropdown list, select the source attribute that
corresponds to the CCID of the destination key flexfield.
The CCID must be mapped to type java.lang.Long.
9.
Note:
10. If your destination key flexfield supports multiple structure instances and is data
set-enabled, the Data Set Number dropdown list appears on the Source Attributes
page. You must specify a data set as an additional source attribute. From the
dropdown list, select the source attribute that corresponds to the DSN of the
destination key flexfield.
The DSN must be mapped to type java.lang.Long.
11. Click Finish to go to the Summary page.
Note: You can skip the Properties page because view link-specific
properties are not supported.
12. On the Summary page, review the summary, then click Finish to create the view
link.
Using Key Flexfields
25-39
13. Optionally, disable the automatic propagation of value set security rules to the
product table by adding a custom property to the view link between the product
view object and the key flexfield view object, as follows:
<propertyname="FND_ACFF_MasterSecuredByFlexfield" Value="false"/>
25.3.2 How to Nest an Instance of the Key Flexfield Application Module in the Product
Application Module
Use the overview editor for the product application module to nest the application
module instance for the key flexfield. This is the application module instance that was
created when you created the flexfield business component and was named using the
prefix that you specified when you defined the usage's entity details. The nested key
flexfield application module instance shares the same transaction and entity object
caches as the application module.
Before you begin:
You should have already created a product application module.
To nest an instance of the key flexfield application module in the product
application module:
1. In the Application Navigator, double-click the product application module.
2.
3.
On the Data Model Components page, expand the Application Module Instances
section and, in the Available list, select the key flexfield application module.
The New App Module Instance field below the list shows the name that will be
used to identify the next instance that you add. You can change this name.
4.
With the desired application module selected, move the key flexfield application
module to the Selected list.
25.3.3 How to Add an Instance of a Key Flexfield View Object to the Product
Application Module
You must add a flexfield view object instance that reflects the master-detail hierarchy
of the view link that you created in Section 25.3.1, "How to Create Key Flexfield View
Links" to the product application module. You can use the data model that the
application module overview editor displays to create the master-detail hierarchy of
view instances. The master view object is the view object for the reference table (the
product table with a foreign key reference to the combinations table), and the detail
view object is the view object for the flexfield. For example, if you created a view link
from the ExpenseLines view object to the GLKff view object, then ExpenseLines is the
master and GLKff is the detail.
For more information about creating a hierarchy of view instances, see the "Adding
Master-Detail View Object Instances to an Application Module" section in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Before you begin:
1. Add an instance of the view object for the reference table to the product
application module, as described in the "How to Add a View Object Instance to an
Application Module" section in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
25-40 Developer's Guide
2.
Create a view link between the reference table view object and the key flexfield
view object as described in Section 25.3.1, "How to Create Key Flexfield View
Links."
3.
4.
If an instance of the reference table view object does not appear in the Data Model
list, then select it in the Available View Objects list and move it over. This is the
master view object instance.
5.
In the Data Model list, select the instance of the view object for the reference table
(the master view object instance) so that it appears highlighted. This will be the
target of the detail flexfield view instance that you will add.
6.
In the Available View Objects list, expand the view object for the reference table
and move the nested key flexfield view object (the detail view object) to the Data
Model list. The flexfield view instance appears nested under master view instance,
as shown in Figure 259.
Figure 259 Flexfield View Instance Nested Under Master View Instance
25-41
Note:
In a typical application, you would have one code-combination maintenance page that
maintains the key flexfield, where the key flexfield is the representation of an entity in
your application. You would also have one or more code-combination reference pages
with foreign key references to the same combinations table. For example, in an order
entry/inventory application, you might have a code-combination maintenance page
where you define new parts with a key flexfield for the part numbers.
You would also have a code-combination reference page where you enter orders for
parts, using the key flexfield to indicate what parts are included in the order. The page
might also contain a code-combination filter, which you use to determine the
acceptable values of your part numbers. This code-combination filter references the
same key flexfield as the code-combination maintenance page and the
code-combination reference page.
The order of key flexfield segments in the application user interface corresponds to the
order in which they were defined in the key flexfield metadata. You cannot reliably
change that order at runtime. The user interface dynamically reads the displayed
attributes from the view object and displays them in the same order that they occur in
the view object. There are no attribute UI hints that you can use to override this
behavior.
Reordering key flexfield segments is not supported and can potentially create data
integrity issues for code combinations, which are sequence-aware. Because of this, it is
important that you plan the segment order of your key flexfields in advance.
The tasks to employ a key flexfield on a page include:
If you want changes in your key flexfield to trigger a partial update of another
component, set the AutoSubmit UI property of the flexfield to True, and add the key
flexfield ID to the PartialTriggers UI property of the other component.
To ensure that the trigger works, you must append "CS" to
the key flexfield ID. For example, if you want changes in the
MyKeyFlex01 flexfield to trigger an update in another component, add
"MyKeyFlex01CS" to that component's PartialTriggers property.
Caution:
For more information about setting user interface properties, see Section 25.4.3.1,
"Configuring Flexfield-Level User Interface Properties."
25-43
2.
When prompted, select the type of user interface that you want to create:
ADF Form
ADF Table
For an ADF Table, select the Row Selection option in the Edit Table Columns
dialog.
3.
In the Data Controls panel, select the key flexfield view object and drag it onto the
page. Drop the flexfield view object onto a form or a table, and select the
appropriate flexfield UI component. Figure 2510 shows a key flexfield being
dropped onto a form.
Figure 2510
4.
Using either sequence generation or default values, ensure that when the end user
adds a row to the page, a valid value is generated for the master view object's
primary key before the row is created. Also ensure that the primary key cannot be
entered or edited by the user.
Caution: You cannot use the code combination ID as part of the
generated primary key.
5.
If you are creating an editable table, select the table in the Structure window,
expand the Behavior section of the Property Inspector and set the EditingMode
attribute. If you want all the rows to be editable, then select editAll. If you want to
enable the end user to click a row to make it editable, then select clickToEdit.
If you select clickToEdit, then the editable row displays the concatenated flexfield
segment values in an input text component. The end user can click an icon that is
next to the editable flexfield to open a dialog box that has an input field for each
segment. The flexfield values in the non-editable rows are displayed as read-only
values. The user can click the icon that is next to a read-only flexfield value to
open a window that displays the segment labels, values, and descriptions.
If the SIN value is static, set the Value Type to Literal, and specify the static
value as the default.
If the SIN value is dynamic, set the Value Type to Expression, and enter a Groovy
expression to retrieve the appropriate SIN value and set it as the default.
For secondary-usage flexfield segments in table components,
you can use the defaultSIN attribute in the JSPX file to define the
default SIN value for situations where no rows exist.
Note:
For an Applications Table component in reference mode, the default SIN and structure
for a new or modified row is just a starting point. You can always allow for runtime
selection of a new structure by LOV or input field.
Caution: For key flexfield secondary usages, the SIN value of the
first row of a user interface table that contains secondary mode
columns determines the secondary mode column structure to be used
for the table. For any additional row that contains a different SIN
value, the secondary mode columns that are not also part of the first
row's structure will not render in the table. If there are no rows, then
the value of the defaultSIN tag attribute from the JSPX file, if set,
determines the secondary mode column structure.
For an Applications Table component, if the end user deletes all rows
from the table, then your application can again set a new default SIN
value for the first new row, and the secondary mode column structure
corresponding to that SIN will be the valid structure for the table.
For an ADF Table, the secondary mode column structure (determined
by the initial SIN value) cannot be changed after the table has been
created, even if all rows are deleted.
For more information about setting attribute defaults, see the discussion about
defining default values in the "Setting Attribute Properties" section of the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
25-45
25.4.1.3 Ensuring Proper Updating of Reference Mode SIN values in an ADF Form
or ADF Applications Table
It is best to not display the CCID or, if it is displayed, to make it a read-only field.
When the end user clicks the popup icon, the popup requires the user to select a code
combination whenever the SIN is changed for a row, and the CCID is set based on the
user's selection.
If the CCID is not displayed in the user interface or if it is displayed as a read-only
value, then you must ensure that the CCID for the current row in the view object is set
to null whenever the SIN is changed by the end user.
If the form does display the CCID in an editable mode, then the application must force
the end user to set the CCID to null, change the SIN value, and then enter the CCID
value to update the concatenated value.
25.4.1.4 Ensuring Proper Updating of Secondary Mode SIN Values in an ADF Form
When an end user makes changes to an existing ADF Form row that contains key
flexfield secondary usage attributes, it might result in the need for that row to use a
different structure instance. The row's underlying view object retains the old SIN
value, which produces a mismatch with the data and generates runtime errors. Your
application must change the SIN value in the row so it uses the new structure instance.
You add code to your page to ensure that this happens, as shown in Example 257.
Example 257
button or a search query, then you must add functionality to dynamically refresh the
segment columns.
To refresh the flexfield segments based on the current iterator rowset data, create a
listener handler method in the flexfield's backing bean and bind the listener to the
component that is initiating the table refresh. The listener must first call the default
listener and then call DescriptiveFlexfield.updateFlexColumns(RichTable), where
RichTable is the binding for the table that contains the flexfield.
Example 258 shows an example of a custom flexfield handler for a query event. The
method first calls invokeMethodExpression to call the original query listener, and then
calls updateFlexColumns with the table component that contains the flexfield as the
parameter. Example 259 shows the binding of the custom flexfield handler to the
query component.
Example 258
Flexfield Listener
<af:query id="qryId1"
headerText="#{applcoreBundle.QUERY_SEARCH_HEADER_TEXT}"
disclosed="true"
value="#{bindings.criteriaQuery.queryDescriptor}"
model="#{bindings.criteriaQuery.queryModel}"
queryListener="#{backingBeanScope.dffBean.customKffSearchQueryListener}"
queryOperationListener="#{bindings.KffCriteriaQuery.processQueryOperation}"
resultComponentId="::AT2:_ATp:ATt2"/>
Note:
25-47
Figure 2511
For more information about tables and popups, see the "Using Tables,
Trees, and Other Collection-Based Components" and "Using Popup
Dialogs, Menus, and Windows" chapters of the Oracle Fusion
Middleware Web User Interface Developer's Guide for Oracle Application
Development Framework.
Key flexfield segments always appear as form fields or table columns in the same
order that their corresponding attributes appear in the underlying view object.
In screenreader mode, a labeled icon of three horizontal bars appears next to the key
flexfield input text field. When the end user clicks the icon, instead of the standard
popup, a page is displayed that shows the segment details. The user clicks Done to
return to the prior page.
For key flexfields in forms and in tables, you can click the search icon to select a valid
new flexfield code combination using individual segment values as criteria, as shown
in Figure 2513.
Figure 2513
Note:
2.
Create a view link between the view object for the reference table and the key
flexfield polymorphic view object as described in Section 25.3.1, "How to Create
Key Flexfield View Links."
2.
Add the key flexfield's view instance to the product application module as
described in Section 25.3.3, "How to Add an Instance of a Key Flexfield View
Object to the Product Application Module."
25-49
3.
Nest the key flexfield application module instance in the product application
module, as described in Section 25.3.2, "How to Nest an Instance of the Key
Flexfield Application Module in the Product Application Module."
4.
Ensure that the discriminator attribute in the view object for the reference table,
such as the SIN attribute, is enabled to display a list of values. You can find this
information on the Attributes navigator tab for the view object. Also, ensure that
the Auto Submit property for the discriminator attribute is set to true in Control
Hints.
For information about enabling a list of values for an attribute and setting control
hints, see the "Defining SQL Queries Using View Objects" chapter of the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
In the Application Navigator, double-click the view object for the reference table.
2.
3.
4.
In the Create View Criteria dialog, enter the name of the view criteria to identify
its usage in your application.
5.
6.
Select the discriminator, such as Sin, from the Attribute dropdown list.
7.
Accept the default values of Equal to for the Operator and Literal for the
Operand.
8.
Select the Group node that you just added, and click Add Item.
9.
From the Attribute dropdown list, select the view accessor for the view link
between your application's reference view object and the key flexfield view object.
10. Accept the default Exists value for Operator and Inline View Criteria for
Operand.
11. Select the bottom node in the View Criteria tree as shown in Figure 2514.
Figure 2514
12. Select the attribute that corresponds to the discriminator, such as _STRUCTURE_
Operand.
this view criteria, identify the nested view criteria that contains the
<ViewCriteriaItem> element for _STRUCTURE_INSTANCE_NUMBER.
16. In the <CustomProperties> element, add a <Property> element. Set the Property
2.
If you are working with secondary-usage flexfield segments and the flexfield is an
ADF Table that is wrapped in an Applications Table component, review
Section 25.4.1.2, "Ensuring Proper Handling of New Rows" and Section 25.4.1.5,
"Dynamically Refreshing Segments on a Code-Combination Maintenance Page or
Secondary Usage Segments."
Open the JSPX page to which you want to add the search form.
2.
From the Data Controls panel, select the reference view object's data collection and
expand the Named Criteria node to display a list of named view criteria.
25-51
3.
Drag the view criteria that you created in Section 25.4.2.1, "Setting Up the Business
Component Model Layer" and drop it onto the page or onto the Structure window.
4.
From the context menu, choose Query > ADF Query Panel with Table, as shown
in Figure 2515.
Figure 2515
5.
If you are working with a secondary (partial) usage or you are working with a
maintenance page, perform the following substeps to enable the execution of a
saved search when the page is loaded for the first time:
a.
From the Property Inspector for the table in which the flexfield is displayed,
obtain the TableId value.
b.
In the Property Inspector for the Query component, set the value of the
ResultComponentId property to the TableId value.
6.
In the Edit Table Columns dialog, you can rearrange any column and select table
options.
7.
In the Data Controls panel, select the key flexfield view object, drop it into the
table, and choose Create > Oracle Key Flexfield Column to add the key flexfield
to the table, as shown in Example 2516.
Figure 2516
8.
In the user interface project, create a custom bean that implements the
oracle.adf.view.rich.event.QueryOperationListener interface as shown in
Example 2511.
Set VIEW_CRITERIA_NAME to the name of the view criteria, and set KFF_ACCESSOR_
NAME to the view accessor from the view link between the view object for the
reference table and the key flexfield view object.
Example 2511 Custom Listener Java Class
package oracle.apps.fnd.applcore.flex.test.backing;
import java.util.List;
import javax.faces.event.AbortProcessingException;
import
import
import
import
import
import
import
oracle.adf.model.BindingContext;
oracle.adf.model.binding.DCBindingContainer;
oracle.adf.view.rich.event.QueryOperationEvent;
oracle.adf.view.rich.event.QueryOperationListener;
oracle.adf.view.rich.model.AttributeCriterion;
oracle.adf.view.rich.model.Criterion;
oracle.adf.view.rich.model.QueryDescriptor;
import oracle.jbo.uicli.binding.JUFormBinding;
import
import
import
import
import
oracle.jbo.ViewCriteria;
oracle.jbo.ViewCriteriaItem;
oracle.jbo.ViewCriteriaRow;
oracle.jbo.common.ViewCriteriaItemImpl;
oracle.jbo.uicli.binding.JUSearchBindingCustomizer;
25-53
This custom bean will be triggered when a value is selected from the LOV
component for the discriminator attribute, such as the LOV for the SIN attribute.
When invoked, the processQueryOperation() method is called. The
JUFormBinding that is associated with the view criteria is accessed to extract the
view criteria.
The applyDiscriminator() method extracts the ViewCriteriaItem for the
discriminator attribute, gets the value that was selected from the discriminator's
LOV component, and loads into the query panel the key flexfield's subtypes with a
matching discriminator value.
9.
Complete the following steps to attach the custom bean to the query:
a.
b.
c.
d.
The significant properties on the Common, Data, Style, Behavior, and Other property
tabs are listed in Table 256.
Table 256
Description
Common > Id
25-55
Description
Description
25-57
Description
If you want changes in your key flexfield to trigger a partial update of another component, set the
AutoSubmit UI property of the flexfield to true, and add the key flexfield ID to the PartialTriggers UI
property of the other component. To ensure that the trigger works, you must append "CS" to the key
flexfield ID. For example, if you want changes in the MyKeyFlex01 flexfield to trigger a partial update in
another component, add "MyKeyFlex01CS" to that component's PartialTriggers property.
Note: The Behavior > Mode property defines the user interface
mode of the key flexfield component.
Only the single default value is supported, which renders the key
flexfield as a single LOV.
Note:
The following properties can be used to define usage-specific behavior for one or more
key flexfield segments, identified by segment label. These property settings apply to
all segments that have the specified segment label assigned.
SegmentLabel: This string property specifies the segment label of the segment
being configured. This string property is required.
Rendered: This boolean property indicates whether the segment is visible on the
application page.
Required: This boolean property indicates whether the segment must have a
value.
Readonly: This boolean property indicates whether end users can modify the
segment.
Label: This string property provides a display label for the UI component.
ShortDesc: This string property provides a short description of the UI component.
This text is commonly used by user agents, such as browsers, to display tooltip
help text, in which case the behavior for the tooltip is controlled by the user agent.
Columns: This integer specifies the width of the text control, in terms of the number
of characters shown. The number of columns is estimated based on the default
font size of the browser.
Note: If you set a segment's Required property to true in the
flexfield metadata, for validation purposes you cannot override this
by resetting it to false in the page metadata. You can, however, do the
reverse: Change a nonrequired segment to be required in the page
metadata.
25-59
The default values of these properties are derived from the flexfield metadata, but you
can override them at the page level.
Note: If you set a segment's required property to true in the
flexfield metadata, for validation purposes you cannot override this
by resetting it to false in the page metadata. You can, however, do the
reverse: Change a non-required segment to be required in the page
metadata.
For information about using EL expressions, see the "Creating ADF Data Binding EL
Expressions" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
You apply these properties by dragging and dropping the following component from
the Component Palette into the key flexfield element:
<fnd:keyFlexfieldPartial propertyname1="value" [propertyname2="value"
[propertyname3="value"]]>
26
Using the Advanced Features of Key
Flexfields
26
This chapter discusses the development activities for taking advantage of key flexfield
partial usages, code-combination filters, and other advanced features.
This chapter includes the following sections:
Section 26.3, "Completing the Development Tasks for Key Flexfields in Secondary
Mode"
Section 26.4, "Working with Code-Combination Filters for Key Flexfields"
When an end user opens a key flexfield popup window to search for a code
combination.
When the code-combination ID attribute of a view object for a reference table is set
programmatically.
Code combination constraints are not applied when an existing foreign key reference
to a code combination is resolved into individual segments (or a concatenated string)
for display.
Combination constraints are view object properties and are not applied on any entity
objects.
You create a view accessor to define a code combination constraint. You can define the
following types of code combination constraints:
Validation date
Validation rules
Open the foreign key view object that references the code combinations.
2.
Click the Add icon in the View Accessors section to display the View Accessors
dialog.
3.
Create a view accessor to the key flexfield's base view object, as shown in
Figure 261.
The destination of the view accessor is the key flexfield's base view object The
name of the view accessor must be derived from the name of the view link
accessor to the key flexfield view object, and must take the following form:
viewlinkaccessornameConstraints
For example, for a view link accessor named AcctKff, Figure 261 shows the
accessor name AcctKffConstraints.
4.
Edit the view accessor to define the bind parameter values, as shown in
Figure 262.
You do not need to select any view criteria for this activity.
Only the bind parameter values are needed to define a code
combination constraint.
Note:
If you do not see any bind parameters, it is likely that you have just
re-created the business components and overwritten the old ones. You
can close the application and remove it from Oracle JDeveloper. When
you open the application again, JDeveloper should load the latest
definitions, including the bind parameters.
There are four types of code combination constraints. To apply a constraint type,
provide a value for the appropriate bind parameter for the constraint type as
shown in the following list. If no value is provided, that constraint type is not
enabled.
Extra WHERE clause: This constraint is invoked with the bind parameter Bind_
ExtraWhereClause. You can also incorporate the predefined bind parameters
BindVar0 through BindVar9.
For information about how to provide a value for this bind parameter, see
Section 26.2.1.2, "Constraining Code Combinations by an Extra WHERE
Clause."
Validation date: This constraint is invoked with the bind parameter Bind_
ValidationDate.
For information about how to provide a value for this bind parameter, see
Section 26.2.1.3, "Constraining Code Combinations by Validation Date."
Value attribute validation rules: This constraint is invoked with the bind
parameter Bind_ValidationRules.
For information about how to provide a value for this bind parameter, see
Section 26.2.1.4, "Constraining Code Combinations by Validation Rules."
Edit only the bind parameters that you need, and leave the others blank. You can
use Groovy expressions as bind-parameter values. This means that the constraints
can come indirectly from a view attribute, the view object, or a Java method.
Note: You can ignore the Row-level bind values exist option,
because the frequency of evaluation of bind parameters is
predetermined, as follows:
Bind_ExtraWhereClause
Bind_ValidationRules
Bind_ValidationDate
Bind_DynamicCombinationCreationAllowed
Create the view accessor and open it for editing as described in Section 26.2.1,
"How to Define Code Combination Constraints."
2.
You can also express this as a Groovy string constant. Be sure to escape the dollar
sign with a backslash:
"(:BindVar0 IS NULL) OR (\${COMBINATION_TABLE}.MY_COLUMN = :BindVar0)"
Note:
Create the view accessor and open it for editing as described in Section 26.2.1,
"How to Define Code Combination Constraints."
2.
Note:
26.2.1.4.1 How to Create Validation Rules Use the create_vrule(...) procedure from the
FND_FLEX_KF_SETUP_APIS PL/SQL package to register a flexfield segment's validation
rule. Validation rules apply only to segments that are validated against a list-validated
value set. If the segment is validated against a format-only value set, the validation
rules are ignored.
Note that when a segment is labeled with multiple segment labels, its validation rules
are joined with an AND operator in the WHERE clause.
When the ALWAYS_APPLIED_FLAG is set to Y, the validation rule is always applied, such
as when a combination is validated by C or PL/SQL validation APIs or a combination
26-6 Developer's Guide
Lexical References
Lexical Type
Lexical
Code
Example
Notes
VALUE
VALUE
&{VALUE.VALUE}
Represents the
VALUE column in
segment lists of
values and
represents the
segment column in
combination lists of
values.
VALUE_ATTRIBUTE value
&{VALUE_ATTRIBUTE.GL_ACCOUNT_
attribute code TYPE}
Represents the
value table value
attribute column in
segment lists of
values and
represents the
combination table
value attribute
column in
combination lists of
values.
For example, if the following WHERE clause were registered as a validation rule for a
segment, then the derived SQL query to retrieve the segment's list of values would be
similar to Example 261, and the derived SQL query to retrieve the combination list of
values would be similar to Example 262.
GL_AFF_AWC_API_PKG.gl_valid_flex_values(
:{FLEXFIELD.VALIDATION_DATE}, &{VALUE.VALUE}) = 'Y')
Example 261
SELECT ...
FROM fnd_vs_values_vl fvvv
WHERE fvvv.value_set_id = :Bind_ValueSetId
AND fvvv.value like :Bind_Value
AND (GL_AFF_AWC_API_PKG.gl_valid_flex_values(
:Bind_ValidationDate, fvvv.value) = 'Y'))
Example 262
SELECT ...
FROM gl_code_combinations glcc
WHERE glcc.chart_of_accounts_id = :Bind_SIN
AND ...
AND
(GL_AFF_AWC_API_PKG.gl_valid_flex_values(
:Bind_ValidationDate, glcc.segment5) = 'Y'))
Tip:
26.2.1.4.2 How to Set the Bind_ValidationRules Parameter Edit the view accessor's Bind_
ValidationRules parameter to specify the validation rules to be applied to constrain
the code-combination filters.
To set the Bind_ValidationRules parameter:
1. Create the view accessor and open it for editing as described in Section 26.2.1,
"How to Define Code Combination Constraints."
2.
The validation rules are predefined as part of the key flexfield definition. The
supplied list is the list of rules must be applied when searching for a code
combination.
Note the following cautions when constructing this list:
In a search user interface, the supplied validation rules also affect the list of values
of a segment. For example, the end user may pick a value for a segment from a list
of values, then use the segment value to search for a code combination. The list of
values of the segment will be constrained by the supplied validation rules.
Create the view accessor and open it for editing as described in Section 26.2.1,
"How to Define Code Combination Constraints."
2.
Example 264 is an example of Java code that retrieves segment label information from
a deployed flexfield using the flexfield view row.
Example 264
For more information about segment labels, see Section 25.2.2, "How to Implement
Key Flexfield Segment Labels." For more information about the Java API, see the
Javadoc.
26.2.3 How to Prepare Key Flexfield Business Components for Oracle Business
Intelligence
Oracle Business Intelligence is a comprehensive collection of enterprise business
intelligence functionality that provides the full range of business intelligence
capabilities including interactive dashboards, full ad hoc, proactive intelligence and
alerts, enterprise and financial reporting, real-time predictive intelligence, and more.
While key flexfields are modeled using polymorphic view objects, flexfield technology
is not compatible with Oracle Business Intelligence, which also requires reference data,
such as lookups, to be modeled as view-linked child view objects. For a key flexfield to
be used by Oracle Business Intelligence, it must be flattened into a usable static form.
To make this possible, you must designate the flexfield as business
intelligence-enabled. When you create business components for this key flexfield, the
business component modeler recognizes the business intelligence-enabled setting, and
a view object that is flattened for business intelligence is generated alongside the
standard key flexfield polymorphic view object. You must also slightly modify the
process of creating key flexfield view links and application modules.
When the business intelligence-enabled and flattened key flexfield is configured as
part of an application, the implementor can select which individual flexfield segments
to make available for use with Oracle Business Intelligence. Only the segments that are
business-intelligence enabled are included in the flattened view object. Administrators
must then import the changes into the Oracle Business Intelligence repository to make
them available for Oracle Business Intelligence.
You can set the flexfield's business intelligence-enabled flag at registration time using
the fnd_flex_kf_setup_apis.create_flexfield(...) procedure, or you can set the
flag later using the fnd_flex_kf_setup_apis.update_flexfield(...) procedure. To
learn how to generate documentation about using these procedures, see
Section 25.2.1.6, "What You May Need to Know About the Key Flexfield Setup API."
You can optionally provide flattened fact names for the flexfield's entity details. This
helps to automate the process for importing the key flexfield into Oracle Business
Intelligence. To provide the flattened fact name, set the BI_FLATTENED_FACT_NAME
value when you register the entity details using the create_adfbc_usage(...)
procedure. You can also set the flag later using the update_adfbc_usage(...)
procedure.
Use the Manage Key Flexfields task, which is accessed from the Setup and
Maintenance work area of any Oracle Fusion Setup application, to enable the segments
for business intelligence. Only the segments that are business-intelligence enabled are
included in the flattened view object.
If you want to map the business intelligence-enabled segments to logical dimensions
in the Oracle Business Intelligence logical model, use the Manage Key Flexfields task
to create segment labels and to map the labels to the logical dimensions. Then assign
the labels to the appropriate flexfield segments. By mapping the segments to the
dimensions, you minimize the steps for importing the flexfield into Oracle Business
Intelligence.
If your flexfield will use hierarchical (tree structured) value sets, create
column-flattened versions of the affected view objects and import them into your
project before continuing.
If the flattened tree view objects are not in your project, the Create Flexfield
Business Components wizard will report the missing view objects as errors.
For more information, see Section 61.8.1, "Designing a Column-Flattened View
Object for Oracle Business Intelligence."
26-11
Create a view link using the procedure described in Section 25.3.1, "How to Create
Key Flexfield View Links." Keep the following in mind:
The view object that you use for the source view object can be the same source
view object that you used for the base key flexfield.
Create the view link from the source view object to the business
intelligence-specific view object, which is the view object with the "BI:" prefix
as shown in Figure 263.
Figure 263 Create Flexfield View Link Wizard View Objects Page
3.
On the Data Model page of the Create Application Module wizard, when you
create an instance of the master view object, there is no need for a child view
object.
b.
On the Application Modules page of the wizard, add an instance of the key
flexfield Oracle Business Intelligence application module as a nested instance
of this application module. You can identify the Oracle Business Intelligence
application module by the analytics subpackage under the package root.
If you already have a product Oracle Business Intelligence
application module, you may use it.
Note:
4.
Define the custom properties required to link the master view object instance to
the default view instance.
Do this in the General navigation tab of the nested instance definition of the
business intelligence-enabled flexfield application module, as shown in
Figure 264.
26-13
Figure 265 Business Component Browser View of Flexfield Row with SIN = 11
Figure 266 Business Component Browser View of Flexfield Row with SIN = 25
2.
2.
Adding a transient attribute to the master view object to store the concatenated
flexfield key.
3.
4.
Creating the service interface for the product application module within which the
key flexfield application module is nested.
5.
Adding flexfield service data object support utility methods to the product
application module.
In this section, master view object refers to the view object for
the reference table as illustrated by Figure 251.
Note:
26-15
1.
Create the master entity object and view object for the product table that references
the key flexfield.
2.
Note:
3.
Create a flexfield view link between the master view object and the flexfield
business component as described in Section 25.3.1, "How to Create Key Flexfield
View Links."
4.
Nest the key flexfield application module instance in the product application
module as described in Section 25.3.2, "How to Nest an Instance of the Key
Flexfield Application Module in the Product Application Module."
5.
Add the key flexfield view object instance to the application module as described
in Section 25.3.3, "How to Add an Instance of a Key Flexfield View Object to the
Product Application Module."
Complete the following steps to ensure that Service Data Objects (SDOs) exist for
all subtype objects.
a.
In the Application Navigator verify that .xsd files exist for all flexfield
subtype view objects.
b.
Open the .xsd file for the key flexfield's base view object and verify that
<include> elements exist for all the flexfield subtype view objects.
Figure 267 The Include Elements for the Flexfield Subtype SDOs
c.
If any subtype view object SDOs are missing, edit the key flexfield's base view
object, and, on the Java navigation tab, click the Edit Java options icon.
In the Select Java Options dialog shown in Figure 268, select Generate
Service Data Object Class, ensure that the namespace is the same location
that contains the flexfield view object XML files, and click OK.
When the SDO is generated for the base view object of the key flexfield
polymorphic view object, generic SDOs are automatically generated for all the
base view object subtypes.
Figure 268 Generating the SDO for the Key Flexfield Base View Object
2.
Edit the view link between the master view object and the flexfield view object.
3.
Click the General navigation tab in the overview editor, expand the Custom
Properties section, and add a SERVICE_PROCESS_CHILDREN property set to true, if
one does not already exist.
4.
5.
In the overview editor, add a transient attribute to store the key flexfield
concatenated string.
a.
Click the Attributes navigation tab, and click the Add icon in the Attributes
section.
b.
In the View Attribute dialog shown in Figure 269, enter a name for the
attribute.
26-17
c.
d.
e.
f.
g.
Click OK.
6.
Click the Java navigation tab and click the Edit icon in the Java Classes section to
generate classes for the master view object.
7.
In the Select Java Options dialog shown in Figure 2610, select the following
checkboxes and click OK:
Include accessors
Figure 2610
8.
In the Java navigation tab, click the link for the View Row Class to open it in the
editor.
9.
Add the code shown in bold in Example 265 to the setter method for the transient
attribute that you created. Set the viewAccessorName to the name of the view
accessor from the view link between the master view object and the key flexfield
view object.
The added code stores the key flexfield concatenated string.
Example 265
/**
* Sets <code>value</code> as the attribute value for the calculated attribute
KffConcatSegment
* @param value value to set the KffConcatSegment
*/
public void setKffConcatSegment(String value) {
String concatAttrPrefix = FlexfieldProperty.PREFIX;
String concatAttrPostfix =
FlexfieldProperty.CONCATENATED_STORAGE_ATTR_POSTFIX;
// Modify next line to set viewAccessorName to name of the VL
String viewAccessorName = "put KFF view link acccessor name here";
String concatAttrName =
concatAttrPrefix + viewAccessorName + concatAttrPostfix;
setAttributeInternal(concatAttrName, value);
26-19
setAttributeInternal(KFFCONCATSEGMENT, value);
}
10. Edit the product application module in which the key flexfield application module
instance, master view object instance, and flexfield view object instance are nested.
11. Click the Web Service navigation tab and click the Add icon to enable support for
the service interface. If the icon is not enabled, click the Edit icon instead and edit
the pages that are named in the following steps.
12. In the Service Interface page of the Create Service Interface wizard, the Web
Service Name and Target Namespace fields are automatically populated with
appropriate values for this application module.
Click Next to continue.
13. In the Service Custom Methods page, select the client methods in the Available list
that you want to expose as part of the service interface and move them to the
Selected list.
14. Click Next to continue.
15. In the Service View Instances page select the view objects in the Available list that
you want to expose as part of the service interface and move them to the Selected
list.
16. Highlight each view object on the Selected list to display the Basic Operations
and View Criteria Find Operations lists for the operations that are available for
that view object, as shown in Figure 2611.
Select the checkbox for each operation of the view object that you want to expose
in the service interface and clear the rest.
Figure 2611
service from the application module. You should see that the Web Service
navigation tab now reflects the custom methods, view instances, basic operations,
and view criteria find operations that you chose to expose, as shown in
Figure 2612.
Figure 2612
The generated service interface components appear below the application module
in the Application Navigator, as shown in Figure 2613.
Figure 2613
20. In the overview editor for the product application module, click the Java
navigation tab.
26-21
21. If the Application Module Class and the Application Module Definition Class
do not appear in the list of Java classes, click the Edit icon and generate the classes.
22. In the Java Classes section, click the link for the Application Module Class.
23. Add the utility methods shown in Example 266 to the application module class.
navigation tab for the product application module and click the Edit icon in the
Service Interface Custom Methods section.
25. In the Service Custom Methods page, move the newly added public methods to
the Selected list to make them available for clients and click OK.
The application module's remote server implementation class will be modified to
expose these methods.
Ensure that the BC4J Service Client and BC4J Service Runtime libraries are
included in your project.
2.
3.
Expand Application Resources > Descriptors > ADF Meta-INF, and open the
connections.xml file.
2.
Locate the Reference element for the product application module's service
(ApplicationService in this example).
This is the service that you created in Section 26.2.4.1, "Exposing a Key Flexfield
Application Module as a Web Service" for the product application module in
which the key flexfield maintenance application module instance, master view
object instance, and flexfield view object instance are nested.
3.
Add the StringRefAddr elements that are shown in bold in Example 267. Modify
the host and port number in the jndiProviderURL entry to point to an instance of
Oracle WebLogic Server. The port number is typically 7101.
Using the Advanced Features of Key Flexfields
26-23
Run the remote server class for the product application module to deploy the
service to an Integrated WebLogic Server instance and to manually test the web
service.
The remote server class was generated when you exposed the
key flexfield as a web service in Section 26.2.4.1, "Exposing a Key
Flexfield Application Module as a Web Service." This class has a name
that ends with ServiceImpl.java.
Note:
5.
Optionally, create and run Java client programs to test invoking the web service.
Example 268 is an example of how a client test program would use the support
utility methods for the flexfield service data object that you added in
Section 26.2.4.1, "Exposing a Key Flexfield Application Module as a Web Service."
Example 268
26.2.5 How to Access Key Flexfields from an ADF Desktop Integration Excel Workbook
ADF Desktop Integration makes it possible to combine desktop productivity
applications with Oracle Fusion applications, so you can use a program such as
Microsoft Excel as an interface to access application data.
Using ADF Desktop Integration, you can incorporate key flexfields into an integrated
Excel workbook, so you can work with the flexfield data from within the workbook.
For more general information about integrating Oracle Fusion applications with
desktop applications, see the Oracle Fusion Middleware Desktop Integration Developer's
Guide for Oracle Application Development Framework. This guide provides most of the
information you need to complete the required activities, including the following:
26-25
Preparing your Excel workbook to access the column containing the flexfield.
Incorporating a key flexfield as a dynamic or static column in an ADF Desktop
Integration Table on a worksheet in the workbook.
Note: The Oracle Fusion Middleware Desktop Integration Developer's
Guide for Oracle Application Development Framework does not make
explicit reference to technologies documented in this Oracle Fusion
Applications Developer's Guide, and this guide does not repeat the
content in the Oracle Fusion Middleware Desktop Integration Developer's
Guide for Oracle Application Development Framework. Therefore, you
must read the Oracle Fusion Middleware Desktop Integration Developer's
Guide for Oracle Application Development Framework for a full
understanding of how to use ADF Desktop Integration technology in
general.
Using a static column in a popup dialog associated with a single cell. Use this
approach for either of the following reasons:
The ADF Desktop Integration Table needs to expose the same key flexfield
instance more than once. In this case, only one instance can be dynamic. All
other instances should be exposed as static columns.
In addition to using the popup dialog, end users can enter values directly into the
segment field, with the values separated by an appropriate delimiter that you
specify.
A static column is any column for which the DynamicColumn
property is set to False.
Note:
Note:
The key flexfield's segments are part of your database table, so the flexfield is
generated against the same entity object on which your worksheet view object is
based.
In addition to configuring ADF Desktop Integration with the dynamic or static column
key flexfield, you might also need to call a custom application module to handle the
update or insert of a key flexfield data row.
Add the ADF Desktop Integration Model API library to your data model
project.
In your page definition for the worksheet, add the key flexfield that you want to
access to the master worksheet view object as a child node. Do not add any
display attribute to the child node, which expands as a dynamic column in the
worksheet.
For more information about how to create a page definition file for a desktop
integration project, see the "Working with Page Definition Files for an Integrated
Excel Workbook" section of the Oracle Fusion Middleware Desktop Integration
Developer's Guide for Oracle Application Development Framework.
To make the key flexfield column of the ADF Desktop Integration Table
component dynamic, set the DynamicColumn property in the TableColumn array
of the ADF Desktop Integration Table to True. A dynamic column in the
TableColumn array is a column that is bound to a tree binding or tree node binding
whose attribute names are not known at design time. A dynamic column can
expand to more than a single worksheet column at runtime.
For more information about the binding syntax for dynamic columns, see the
"Adding a Dynamic Column to Your ADF Table Component" section of the Oracle
Fusion Middleware Desktop Integration Developer's Guide for Oracle Application
Development Framework.
Inputtext
OutputText
ModelDrivenColumnComponent
For the subcomponent's Value property, access the Expression Builder, expand the
Bindings node and your tree binding for the table, and select the flexfield node.
For the subcomponent's Label property, access the Expression Builder, expand the
Bindings node and your tree binding for the table, and select the flexfield node.
For information about the Expression Builder, see the "Using the Expression Builder"
section in the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle
Application Development Framework.
26-27
26.2.5.3 Configuring ADF Desktop Integration with a Static Column Key Flexfield
ADF Desktop Integration supports key flexfields by using tree bindings in an ADF
Desktop Integration Table. If you are adding your key flexfield as a static column, you
can alternatively use an ADF Read-Only Table. Keep in mind that ADF Read-Only
Tables support static columns, but not dynamic columns. Popup dialogs support both
types.
A key flexfield appears as a node in the tree binding at design
time. Because flexfields are built up dynamically at runtime, you will
not see any attributes under the flexfield node in the page definition,
but the node itself is present.
Note:
When you configure the popup dialog, make the following changes:
You can use the column's action set properties to make the key flexfield web page
available for editing. You should include the attributes used in the web page in the
table's cached attributes unless the row will be committed immediately.
You must choose a fixed attribute (the key flexfield CCID) to represent the flexfield
in the worksheet. Add a Dialog action to the DoubleClickActionSet of an
InputText or OutputText component, then connect the Dialog action to a JSPX
page that will display the key flexfield.
For more information about how to create a page definition file for a desktop
integration project, see the "Working with Page Definition Files for an Integrated
Excel Workbook" section of the Oracle Fusion Middleware Desktop Integration
Developer's Guide for Oracle Application Development Framework.
For static display of a key flexfield in an ADF Desktop Integration workbook, you
must create an updatable transient attribute in the view object on which the ADF
Desktop Integration table is based. This transient attribute will hold the concatenated
value of the key flexfield segments, separated by a delimiter. If one purpose of the
worksheet is to display existing data from the database, the transient attribute should
be populated using custom application module methods upon returning from a popup
dialog or opening the worksheet.
The following examples demonstrate the code needed to accomplish these tasks.
Example 269 and Example 2610 apply to an ADF Desktop Integration
implementation with the key flexfield exposed as a dynamic column. Example 2611
and Example 2612 apply to an ADF Desktop Integration implementation with the key
flexfield exposed as a static column.
Example 269
You add this code as an application module method that will be invoked from the
UpdateRowActionId property of an ADF Desktop Integration Table. This code will be
invoked for every row that is updated.
Row tempRow = null;
// Get KFF child row information based on the KFF view link accessor.
KFFViewRowImpl acctRow;
ViewRowImpl kffAcctRow = (KFFViewRowImpl)linerow.getAccountLineKff();
// If it is not child row (for a new row case or cases where
// KFF data is not invalid/present for existing DB Row)
// get a dummy row from ADF Desktop Integration helper class.
if (kffAcctRow == null) {
tempRow = ModelHelper.getAdfdiTempChildRow(linerow, "AccountLineKff");
kffAcctRow = (ViewRowImpl)tempRow;
}
Long kffAcctId = null;
String acctSeg=null;
//
//
//
//
26-29
Example 2610 Inserting a New Row with a Key Flexfield Dynamic Column
Add this code as an application module method that will be invoked from the
InsertAfterRowActionId property of an ADF Desktop Integration Table. This code
will be invoked for every row that is inserted.
Row tempRow = null;
// Retrieve key flexfield child row information based on
// the KFF view link accessor
ViewRowImpl kffAcctRow = (ViewRowImpl)linerow.getAccountLineKff();
// If not a child row (for new row case or cases where
// KFF data is not invalid/present for existing DB Row),
// get a dummy row from ADF Desktop Integration helper class
if (kffAcctRow == null) {
tempRow = ModelHelper.getAdfdiTempChildRow(linerow, "AccountLineKff");
kffAcctRow = (ViewRowImpl)tempRow;
}
Long kffAcctId = null;
kffAcctId =
linerow.getKeyFlexfieldCombinationID("AccountLineKff",
KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
// If you need dynamic insert (creating new segment combinations)
// in the ADF Desktop Integration worksheet,
// make sure the end user supplies a valid value for at least one segment.
26-30 Developer's Guide
if (kffAcctId==null) {
String delimiter = FlexfieldViewDefImpl.getDelimiter(kffAcctRow.getViewDef());
List segments =
FlexfieldViewDefImpl.getFlexfieldAttributes(kffAcctRow.getViewDef());
StringBuffer delim = new StringBuffer();
for (int i = 0; i < segments.size() - 1; i++) {
delim.append(delimiter);
}
// If getConcatenatedSegments() return only delimiter information,
// that means end user has not supplied valid KFF Segment values.
if
(!KFFViewRowImpl.getConcatenatedSegments(kffAcctRow).equals(delim.toString())){
linerow.setKeyFlexfieldCombinationID("AccountLineKff",
KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
// Get CCID value based on segment information.
kffAcctId =
linerow.getKeyFlexfieldCombinationID("AccountLineKff",
KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
}
}
// Set CCID column with CCID value.
linerow.setDistCodeCombinationId(kffAcctId);
Example 2611 Updating or Inserting a Row with a Key Flexfield Static Column
This code should be added to the setter method of the transient attribute in your view
object RowImpl.
setAttributeInternal(TRANSIENTACCOUNT, value);
// Get KFF child row information based on the KFF view link accessor.
ViewRowImpl kffAcctRow = (ViewRowImpl)linerow.getAccountKff();
Row tempRow;
//
//
//
if
}
Long kffAcctId = null;
// If you need dynamic insert (creating new segment combinations)
// in the ADF Desktop Integration worksheet,
// make sure the end user supplies a valid value for at least one segment.
String delimiter = FlexfieldViewDefImpl.getDelimiter(kffAcctRow.getViewDef());
List segments =
FlexfieldViewDefImpl.getFlexfieldAttributes(kffAcctRow.getViewDef());
StringBuffer delim = new StringBuffer();
for (int i = 0; i < segments.size() - 1; i++) {
delim.append(delimiter);
}
26-31
this.getKeyFlexfieldCombinationID("AccountKff", value);
Example 2612 Applying Modified Segment Values to a Cell in a Key Flexfield Static
Column
You add this code as a custom application module method that will be invoked from
the ActionListener property of the OK button in the popup dialog JSPX page.
// Get a reference to your ADF DesktopIntegration table view object.
DesktopQuickInvoicesHeaderVOImpl headerVO =
this.getDesktopQuickInvoicesHeader();
// Get a reference to the current row, which is the row from which
// popup dialog is opened
DesktopQuickInvoicesHeaderVORowImpl headerRow =
(DesktopQuickInvoicesHeaderVORowImpl)headerVO.getCurrentRow();
// Get a reference to your key flexfield row
ViewRowImpl kffAcctRow = (ViewRowImpl)headerRow.getAccountKff();
Row tempRow;
// If that is null (for a null CCID or an invalid CCID or a new row),
// get temp row from ADF Desktop Integration.
if (kffAcctRow == null) {
tempRow = ModelHelper.getAdfdiTempChildRow(headerRow, "AccountKff");
kffAcctRow = (ViewRowImpl)tempRow;
}
// Derive and assign value of segments to your transient attribute
// that is created for single cell display in the ADF Desktop Integration Table.
headerRow.setTransientAccount(KFFViewRowImpl.getConcatenatedSegments(kffAcctRow));
Single-segment secondary usage: Use this mode when you want to capture only
one segment value in a transaction or setup table. For example, if you want to
capture the default cost center value for an employee in the EMPLOYEES table in
the DEFAULT_COST_CENTER column.
All-segment secondary usage: Use this mode when you want to capture all the
flexfield's segment values in a transaction or setup table. For example, if you want
to capture all the segment values in a general ledger setup table for use in filling in
missing values in the subledger account engine.
To incorporate a key flexfield secondary usage into your
application, you must have already defined and registered the key
flexfield primary usage on which it is based. See Section 25.2.1.5,
"Registering and Defining Key Flexfields Using the Setup APIs,"
before continuing.
Note:
The development tasks for key flexfields in secondary mode consist of the following
steps:
1.
2.
Create key flexfield business components that are based on the secondary usage
for use in secondary mode development tasks.
3.
Create a view link between your product view object and the secondary mode key
flexfield.
4.
The remainder of the development process is essentially the same as the consumer
development process for key flexfield primary usages. You can skip the section on
creating key flexfield view links and continue with the tasks described in the
following sections:
a.
b.
Section 25.3.3, "How to Add an Instance of a Key Flexfield View Object to the
Product Application Module"
c.
Note:
d.
Note:
After you have completed the development tasks for secondary usages, you can
incorporate the secondary usages in the application user interface as described in
Section 25.4, "Employing Key Flexfield UI Components on a Page."
26-33
3.
Create an ADF Business Components usage for the flexfield table usage as
described in Section 25.2.1.9, "Registering Entity Details Using the Setup APIs."
To implement a key flexfield secondary usage, you select the usage at design time. For
more information, see Section 25.2.4, "How to Create Key Flexfield Business
Components."
If you need to change a table usage after creating it, you must delete the table usage,
then re-create it.
Define a segment label for the segment that you want to capture.
The segment label must be defined as Unique to ensure that only one segment in a
given structure can be associated with this label.
For more information about segment labels, see Section 25.2.2, "How to Implement
Key Flexfield Segment Labels."
3.
4.
Create an ADF Business Components usage for the flexfield table usage as
described in Section 25.2.1.9, "Registering Entity Details Using the Setup APIs."
To implement a key flexfield secondary usage, you select the usage at design time. For
more information, see Section 25.2.4, "How to Create Key Flexfield Business
Components."
If you need to change a table usage after creating it, you must delete the table usage,
then re-create it.
26.3.3 How to Create Key Flexfield Business Components for Secondary Usage
Zero or more secondary usages can be defined for a given flexfield, each one
potentially on a different product table.
Before you begin:
1. One or more required libraries might have not been automatically included in
your project. Ensure that all required libraries, notably the BC4J Service Runtime,
Java EE 1.5 and Java EE 1.5 API libraries, are included.
2.
Using the Create Entity Object wizard, create entity objects for the combinations
tables that you have defined. Verify the following:
Note:
These entity objects are directly modeled on the combinations tables; hence,
they contain the fixed (nonflexfield) columns, if any, along with all of the
flexfield columns. In general, all columns should be included.
3.
The package name and the object name prefix for each entity object are
registered with the flexfield usage to which it will provide data, as described
in Section 25.2.1.9, "Registering Entity Details Using the Setup APIs."
Build your project to ensure that the entity objects are available in classes. The
modeler relies on what is in your classes.
26-35
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Business Components, and click OK.
3.
On the Flexfield page of the Create Flexfield Business Components wizard, select
key from the Type dropdown list as shown in Figure 2614.
Figure 2614
4.
In the Application field, specify the full name of the application to which your key
flexfield belongs.
You can browse for the name, and filter by ID, Short Name, or Name.
5.
In the Code field, specify the code of the key flexfield you want to use.
You can browse for and filter by Code.
6.
In the Usage section, select the table row that contains the desired secondary key
flexfield usage. Key flexfield usage can be one of the following types:
Do not select a flexfield usage without a prefix in the Description field. For more
information about key flexfield secondary usages, see Section 26.3.1, "How to
Register a Key Flexfield All-Segment Secondary Usage."
7.
Click Next.
8.
On the Path page, select the path of the directory structure in which to create the
flexfield business components and click Next.
9.
On the Entity Object page, select the entity object to use as the data source for the
key flexfield Figure 2615.
Because you selected a secondary usage on the Flexfield page, you must select the
entity object for the table where that usage is defined.
The entity object you select must include all of the attributes that will be
referenced by the flexfield. For secondary usages, this includes attributes that
represent the SIN column, the DSN column if it exists in the combinations table,
and all of the flexfield segment columns.
If you select a polymorphic entity object, ensure that the
InheritPersonalization property for every subtype entity is set to
true.
Note:
10. You might wish to select an entity object for which the key flexfield attributes are
defined as transient (not based on database table columns). If you need to do this,
then select The names of the flexfield attributes match the names of registered
columns exactly; do not check the underlying columns.
When a key flexfield entity object attribute is transient, there is no matching
underlying column name. When you select this option, the system will match the
entity object attribute names to the key flexfield column names, and use the
matching attributes to access the flexfield data. Ensure that the entity object has a
full set of attributes with matching names before you select this option.
26-37
This entity object must be registered under the primary usage as described in
Section 25.2.1.9, "Registering Entity Details Using the Setup APIs." There is no
need to register another table for this purpose, even if the entity object is based on
some other table.
If the entity object with transient key flexfield attributes is not
based on the primary usage, the transient attributes must be named
using the same prefix as the other attributes of that entity object (and
the corresponding table columns). For more information, see
Section 26.3.1, "How to Register a Key Flexfield All-Segment
Secondary Usage."
Note:
Figure 2616 if this secondary usage is simply to add extra information for a
product row and the user should not be required to provide information for every
segment.
Figure 2616
13. From the Structure Instance Number dropdown list, select the entity attribute that
corresponds to the key flexfield SIN for the secondary usage. The SIN must be an
attribute of type java.lang.Long.
If the key flexfield is data set-enabled, this page will also contain a Data Set
Number dropdown list. From the dropdown list, select the entity attribute that
corresponds to the DSN for the secondary usage. The DSN must be an attribute of
type java.lang.Long.
14. Click Next.
15. The Naming page displays the entity object's package name and object name that
you registered for the usage, as described in Section 25.2.1.9, "Registering Entity
Details Using the Setup APIs." Click Next.
16. On the Summary page, review your choices and click Finish.
The business components generated will replace any existing ones that are based
on the same flexfield.
This wizard might fail with a "ClassNotFound" exception
message. This indicates that one or more required libraries have not
been automatically included in your project, notably the BC4J
Service Runtime, Java EE 1.5 and Java EE 1.5 API libraries. You
can resolve this issue by manually adding any missing libraries; then
you can complete this procedure successfully.
Note:
17. Refresh the project to see the newly created flexfield business components in the
Application Navigator.
26.3.4 How to Create Key Flexfield View Links for a Secondary Usage
A view link is needed whenever a product view object references your key flexfield.
The base view object can have many incoming view links from various product view
objects, as a key flexfield is usually shared by many product tables.
Before you begin:
You should have already created a master view object for your entity object using the
standard wizard.
Ensure that the view object does not include flexfield attributes such as SEGMENT1_
VARCHAR2, SEGMENT2_NUMBER, and so on. Ensure that you include the
attributes that are needed for the foreign key reference, such as CCID, SIN, and, if
present, DSN. Ensure that the CCID attribute's Display control hint is set to Hide.
To create a key flexfield view link for a secondary usage:
1. In the Application Navigator, right-click the project and choose New.
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield View Link, and click OK.
3.
In the Create Flexfield View Link wizard, on the Name page, provide a package
name as shown in Figure 2617.
26-39
Figure 2617
4.
5.
Click Next. The View Objects page appears, as shown in Figure 2618.
Figure 2618
6.
In the Select Source View Object tree, select a secondary usage view object.
7.
In the Select Destination Flexfield tree, expand the available flexfield view objects
from your project and select the key flexfield's base view object.
8.
In the View Link Accessor Name field, enter an appropriate name for the view
link accessor.
9.
Click Next. The Source Attributes page appears, as shown in Figure 2619.
Figure 2619 Create Flexfield View Link Wizard Source Attributes Page for Secondary
Mode Key Flexfields
This page is informational only. The key attributes of the source view object will be
used to define the view link. The primary key attribute should be listed for this
selection.
10. Click Finish to go to the Summary page.
Note: You can skip the Properties page because view link-specific
properties are not supported.
11. On the Summary page, review the summary, then click Finish.
SIN
CCID
Summary_Flag
Enabled_Flag
Segment1_Varchar2
Segment2_Varchar2
11
77
8.5X12
YEL
11
78
8.5x14
GRN
14
ERGO
NYLON
14
HGBAK
LEATHER
26-41
When you apply this filter condition to the combinations table, the result listed in
Table 263 is presented. Note that not all columns are shown in the table.
Table 263
SIN
CCID
Summary_Flag
Enabled_Flag
Segment1_Varchar2
Segment2_Varchar2
14
ERGO
NYLON
Combination filter conditions for key flexfields are stored in a database column of type
XMLType. This column is referred to a a filter-condition column.
There are three types of code-combination filters that you can use in your application
standard code-combination filters, code-combination filters for Oracle Business
Intelligence Publisher (Oracle BI Publisher) reports, and cross-validation filters.
Note:
To incorporate cross-validation filters, you follow much of the same process as you
would to implement standard filters. The code-combination filter procedures that
follow note which procedures do not apply to these types of filters.
For more information about implementing cross-validation rules, see Section 25.2.3,
"How to Implement Cross-Validation Rules and Custom Validation."
26-43
1.
Use the following Alter script to add a filter-condition column (for example,
Filter) of type XMLType to your table:
Alter table FND_MYFILTER_KFF1 add Filter xmltype
XMLType column Filter
Store as BINARY XML
XMLSCHEMA "http://www.oracle.com/apps/fnd/applcore/flex/kff/FndFilter.xsd"
ELEMENT "KeyFlexCodeCombinationFilter";
Note:
For standard filters only, create an entity object for the table containing the
filter-condition column.
2.
3.
4.
Note:
2.
To use code-combination filters, you must first have completed the Create
Flexfield Business Components wizard for at least one key flexfield, so that your
project contains one or more key flexfield business components.
Create an entity object (for example, Kff1Fltr1EO) for the table containing your
filter-condition column.
2.
Open the entity object, and, in the overview editor, click the General navigation
tab.
3.
Expand the Custom Properties section and add the FND_FILTER property with a
value of Y.
This property enables the base classes (OAEntityImpl) to recognize that the entity
object contains a filter attribute.
4.
Because the column type of the filter attribute is XMLType, which is not natively
supported by ADF Business Components, you must edit the attribute to make it a
transient attribute that is computed using a SQL expression.
Click the Attributes navigation tab, select the filter attribute, and click the Edit
icon to open the Edit Attribute dialog.
5.
In the Entity Attribute dialog, click the Entity Attribute node and change the
attribute from a persistent type to a calculated type, as shown in Figure 2620.
a.
b.
c.
26-45
6.
Figure 2621
7.
Add the custom filter properties that are listed in Table 264 to the filter attribute.
Table 264
Name
Value
Description
FND_FILTER
FND_FILTER_TABLE
table-name
FND_FILTER_COL
column-name
FND_FILTER_TABLE_COL_PKn
primary-key-column-id
26-47
Value
Description
FND_FILTER_TABLE_ATTR_PKn
If you are implementing a standard code-combination filter, then create the view
object for the entity object that you created in Section 26.4.5.1, "Creating a Filter
Entity Object for a Standard Filter."
If you are implementing the filter for use in the key flexfield filter repository for
Oracle BI Publisher reports, then create the view object for the public entity object:
oracle.apps.fnd.applcore.flex.kff.model.publicEntity.FndKfEssFiltersPEO
If you are implementing the filter to support cross-validation rules, then create the
view object for the provided cross-validation entity object:
oracle.apps.fnd.applcore.flex.kff.model.entity.KeyFlexfieldCrossValidationRuleE
O
In the view object for the cross-validation rules, define view criteria to set the
APPLICATION_ID and KEY_FLEXFIELD_CODE attributes to static values for your
application and key flexfield.
Note:
2.
In the New Gallery, expand Business Tier, select ADF Business Components and
then Flexfield Filter, and click OK.
3.
In the Filter Accessor dialog, expand the available view objects in your current
project on the left-hand list and select the view object attribute that corresponds to
the XML Filter column as shown in Figure 2622.
Figure 2622
4.
Expand the available flexfields in your current project on the right-hand list and
select a key flexfield to be filtered.
5.
Enter a name for the filter accessor (with no spaces), then click OK.
Open the filter view object and click the General navigation tab.
This property enables the base classes (OAViewRowImpl) to recognize that the view
object row contains a filter attribute.
2.
Expand the Custom Properties section and add the property FND_FILTER with the
Value set to Y.
3.
Click the Attributes navigation tab and select the filter attribute.
4.
Expand the Custom Properties section and add the property FND_ACFF_SIN for the
selected filter attribute. Set the Value to the structure instance number (SIN).
This property indicates the view object's SIN attribute that is associated with this
filter attribute.
5.
Create an application module for the filter. In the Data Model page, move the filter
view object to the Data Model list. In the Application Modules page, move the
flexfield application module, which was created when you created the flexfield
business component, to the Selected list.
26-49
Tip: You also can add the flexfield application module from the
Application Module Instances section in the Data Model navigation
tab for the application module.
6.
Run the Business Component Browser to ensure that all attributes appear.
Note:
Ensure that the Applications Core (ViewController) tag library has been added to
the user interface project, as described in Section 3.4, "Adding the Applications
Core Tag Library to Your User Interface Project."
Create the view object, view accessor, and application module for the
code-combination filter as described in Section 26.4.5, "How to Add
Code-Combination Filters to Your Application."
2.
Drag and drop the view object that contains your filter from the Data Controls
panel onto the page as an ADF Form or an ADF Table. Figure 2623 shows the
filter view object dropped onto the page as a form.
Figure 2623
3.
Ensure the CreateInsert and Commit actions are included on the page.
Note: These actions enable dynamic creation of new filter definitions
at runtime; they also enable you to insert new records into the filter
repository.
4.
If you dropped the view object onto the page as an ADF Table, select the filter
column and, in the Property Inspector, set Sortable to false.
Note:
5.
If you dropped the view object onto the page as an ADF Form, select the filter
component and, in the Property Inspector, enter the name of the flexfield in the
Label field. This name is used in the title of the filter popup dialog.
6.
By default, end users can choose to match on all conditions or any condition, as
shown in Figure 2624 and Figure 2625. If you want to restrict the filter to match
on all conditions only, add the RestrictConjunctionToAND property and set it to
true, as shown in Example 2613 and Example 2614
26-51
accessor="kff1" id="kff1"
restrictConjunctionToAND="true"/>
</af:column>
When this property is set to true, the Filter dialog box does not display the Match
options, as shown in Figure 2626. All of the conditions for the same segment are
joined with an OR operator and then combined with the conditions for other
segments using an AND operator, as shown in Example 2615.
Example 2615 Joining of Segments When restrictConjunctionToAND is true
(SEGMENT1 = 'A' or SEGMENT = 'B') AND (SEGMENT2 = 10 OR SEGMENT2 = 20)
Figure 2624
Figure 2626
When you add a filter-repository filter to the application page as an ADF Table, the
report submission user interface appears as shown in Figure 2628.
26-53
Figure 2628
When you click CreateInsert, a new row is added that includes the filter XML and
other required input, along with the default values for some of the columns. Your
application must provide defaults for the columns as described in Table 265.
Table 265
Column
Description
KeyFlexfieldCode
The code identifying the key flexfield to which this filter will be
applicable.This is a read-only value.
StructureInstanceNumber
This is the SIN, the discriminator attribute for the key flexfield
that is used in the key flexfield filter. While creating a new filter
definition or submitting a new job, a valid value should be the
default for this attribute at the view object level. The SIN is
required for capturing the filter XML. This is a read-only
attribute.
DataSetNumber
FilterId
ApplicationShortName
Filter
When you click Commit, the new row is inserted in the FND_KF_ESS_FILTERS
database table.
Note:
The operators supported for code-combination filters are the operators supported in
the Query panel. This includes the following data types and their operators:
You can also use the following hierarchical operators to query tree structures in your
filter: IS_CHILD_OF, IS_DESCENDENT_OF, IS_LAST_DESCENDENT_OF, IS_PARENT_OF, IS_
ANCESTOR_OF, IS_FIRST_ANCESTOR_OF, IS_SIBLING_OF.
For more information about trees, see Chapter 20, "Organizing Hierarchical Data with
Tree Structures."
Example 2616 shows some example scripts. The first one inserts a filter condition that
selects for SEGMENT1_VARCHAR2 = 'Value04', and the second one selects for the
inequality SEGMENT1_VARCHAR2 != 'Value02'.
Example 2616 Scripts for Inserting Filter Conditions into the Application Database
26-55
<value>Value04</value>
<properties>
<property>
<name>TestProp</name>
<value>ValueProp</value>
</property>
</properties>
</filterCriteriaItem>
<properties>
<property>
<name>TestProp</name>
<value>ValueProp</value>
</property>
</properties>
</filterCriteriaRow>
</KeyFlexFilter>
</FndFilter>'));
You might want to test these scripts to ensure that the database
is, in fact, performing schema validation on the XML document, by
attempting to insert XML that does not conform to this schema.
Note:
26.4.8 How to Apply Code-Combination Filters Using the PL/SQL Filter APIs
You can take advantage of code-combination filters (including filter-repository filters)
without using them in your application user interface. You use the WHERE clause API
for standard and cross-validation combination filters, and you use the XML API for
filter repository filters.
IN XMLType,
IN Varchar2,
IN Varchar2,
OUT Number,
OUT NOCOPY BIND_VAL_TAB,
OUT NOCOPY Varchar2);
/** ---------------------------------------------------------------------------- This procedure computes the WHERE clause for the filter
-- and provides it in the filterWhereClause parameter
-- Params
-IN Params
-filter
XMLType - Filter to be converted to SQL clause
-tableAlias Varchar2 - Alias table name to be used in SQL clause
-bindPrefix Varchar2 - Bind Prefix
-OUT Params
-sin
Number
- Structure Instance Number
-bindValues BIND_VAL_TAB
- List of Bind Values
-filterWhereClause Varchar2 - WHERE clause
----------------------------------------------------------------------------*/
26-57
TYPE
VALUE_VARCHAR2
VALUE_NUMBER
VALUE_DATE
Varchar2(20),
Varchar2(32767),
Number,
Date);
Example 2619, Example 2620, and Example 2621 demonstrate how to use the WHERE
clause API for an EQUALTO condition, a BETWEEN condition, and multiple conditions.
Example 2619 Using the WHERE Clause API for an EQUALTO Condition
Suppose that a filter condition has been defined in a combinations table as follows:
Use the tableAlias value in WHERE clauses to represent the combinations table name.
In this example, FND_KF_TEST_CCT1.SEGMENT1_VARCHAR2 should be entered as
FKFF1.SEGMENT1_VARCHAR2.
Similarly, use the bindPrefix value as a prefix when referencing individual bind
values, for example, :BND1, :BND2, or :BND3.
When invoked, the filter API in this example might produce the following values for
its output parameters:
filterWhereClause - FKFF1.SEGMENT1_VARCHAR2 = :BND1
sin
- 12
bindValues
- bindValues(1).NAME = BND1
- bindValues(1).TYPE = VARCHAR2
- bindValues(1).VALUE_VARCHAR2 = 123
With this output, you can assemble the following WHERE clause for an EQUALTO filter
condition:
select code_combination_id,
Segment1_VARCHAR2
from FND_KF_TEST_CCT1 FKFF1
where FKFF1.structure_instance_number=12
and FKFF1.SEGMENT1_VARCHAR2=123
Example 2620 Using the WHERE Clause API for a BETWEEN Condition
xsi:noNamespaceSchemaLocation=
"http://www.oracle.com/apps/fnd/applcore/flex/kff/KeyFlexCodeCombinationFilter.xsd
">
<keyFlexfieldCode>KFF1</keyFlexfieldCode>
<structureInstanceCode>VS_FRM_NUM_ON_CHR</structureInstanceCode>
<applicationShortName>FND</applicationShortName>
<filterCriteriaRow>
<filterCriteriaItem>
<attributeName>_P6_S0</attributeName>
<columnName>SEGMENT1_Varchar2</columnName>
<operator>BETWEEN</operator>
<conjunction>AND</conjunction>
<valueDataType>NUMBER</valueDataType>
<value>-500</value>
<value>1000</value>
</filterCriteriaItem>
</filterCriteriaRow>
</KeyFlexCodeCombinationFilter>'));
The filter expression captured in the preceding XML resolves to the following:
SEGMENT1_VARCHAR2 BETWEEN -500 and 1000
When invoked, the filter API in this example might produce the following values for
its output parameters:
filterWhereClause - FKFF1.SEGMENT1_VARCHAR2 = :BND1
sin
- 12
bindValues
- bindValues(1).NAME = BND1
- bindValues(1).TYPE = VARCHAR2
- bindValues(1).VALUE_VARCHAR2 = -500
- bindValues(2).NAME = BND2
- bindValues(2).TYPE = VARCHAR2
- bindValues(2).VALUE_VARCHAR2 = 1000
With this output, you can assemble the following WHERE clause for a BETWEEN filter
condition:
select code_combination_id,
Segment1_VARCHAR2
from FND_KF_TEST_CCT1 FKFF1
where FKFF1.structure_instance_number=12
and FKFF1.SEGMENT1_VARCHAR2 BETWEEN -500 AND 1000
Example 2621 Using the WHERE Clause API for Multiple Conditions
26-59
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.oracle.com/apps/fnd/applcore/flex/kff/Ke
yFlexCodeCombinationFilter.xsd">
<keyFlexfieldCode>KFF1</keyFlexfieldCode>
<structureInstanceCode>VS_FRM_NUM_ON_CHR</structureInstanceCode>
<applicationShortName>FND</applicationShortName>
<filterCriteriaRow>
<filterCriteriaItem>
<attributeName>_P6_S0</attributeName>
<columnName>SEGMENT1_Varchar2</columnName>
<operator>EQUALTO</operator>
<conjunction>AND</conjunction>
<valueDataType>NUMBER</valueDataType>
<value>123456</value>
</filterCriteriaItem>
<filterCriteriaItem>
<attributeName>_P6_S2</attributeName>
<columnName>SEGMENT2_Varchar2</columnName>
<operator>EQUALTO</operator>
<conjunction>AND</conjunction>
<valueDataType>NUMBER</valueDataType>
<value>123.45</value>
</filterCriteriaItem>
</filterCriteriaRow>
</KeyFlexCodeCombinationFilter>'));
The filter expression captured in the preceding XML resolves to the following:
SEGMENT1_VARCHAR2 = 123456 and SEGMENT2_VARCHAR2 = 123.45
When invoked, the filter API in this example might produce the following values for
its output parameters:
filterWhereClause sin
bindValues
-
FKFF1.SEGMENT1_VARCHAR2 = :BND1
FKFF1.SEGMENT2_VARCHAR2 = :BND2
12
bindValues(1).NAME = BND1
bindValues(1).TYPE = VARCHAR2
bindValues(1).VALUE_VARCHAR2 = 123456
bindValues(2).NAME = BND2
bindValues(2).TYPE = VARCHAR2
bindValues(2).VALUE_VARCHAR2 = 123.45
With this output, you can assemble the following WHERE clause for a BETWEEN filter
condition:
select code_combination_id,
Segment1_VARCHAR2, Segment2_VARCHAR2
from FND_KF_TEST_CCT1 FKFF1
where FKFF1.structure_instance_number=12
and FKFF1.SEGMENT1_VARCHAR2 = 123456
and FKFF1.SEGMENT2_VARCHAR2 = 123.45
26-60 Developer's Guide
IN VARCHAR2,
IN fnd_application.application_short_name%TYPE,
IN fnd_kf_flexfields_b.key_flexfield_code%TYPE,
IN NUMBER,
IN VARCHAR2,
OUT nocopy VARCHAR2,
OUT nocopy NUMBER,
OUT nocopy bind_variables);
Example 2623 demonstrates how to use this API to obtain the WHERE clause and bind
variable information for a filter in the filter repository.
Example 2623 Using the Filter Repository API
REM dbdrv: none
SET SERVEROUTPUT ON
WHENEVER SQLERROR CONTINUE
DECLARE
l_tableAlias VARCHAR2(30);
l_applicationShortName fnd_application.application_short_name%TYPE;
l_keyFlexfieldCode fnd_kf_flexfields_b.key_flexfield_code%TYPE;
l_filterWhereClause
VARCHAR2(32767);
l_filterId
NUMBER;
l_filterName
VARCHAR2(32);
l_bindVariables fnd_flex_xml_publisher_apis.bind_variables;
l_numOfBindVariables NUMBER;
CURSOR c_filter_id
IS
SELECT filter_id FROM fnd_kf_ess_filters;
BEGIN
l_filterName
:= 'DefaultFilter';
l_tableAlias
:= 'DefaultTable';
l_keyFlexfieldCode
:= 'KFF1';
l_applicationShortName := 'FND';
DBMS_OUTPUT.PUT_LINE('kff_filter');
FOR filter_id IN c_filter_id
LOOP
fnd_flex_xml_publisher_apis.kff_filter(p_lexical_name=>l_filterName,
p_application_short_name=>l_applicationShortName,
p_key_flexfield_code=>l_keyFlexfieldCode,
p_filter_id=>filter_id.filter_id,
p_code_combination_table_alias=>l_tableAlias,
x_where_expression=>l_filterWhereClause,
x_numof_bind_variables=>l_numOfBindVariables,
x_bind_variables=>l_bindVariables);
26-61
27
Testing and Deploying Flexfields
27
This chapter discusses how to configure flexfields with test segments, how to test your
flexfield business components in Oracle Fusion applications using Integrated
WebLogic Server, how to deploy a flexfield application to a Standalone Oracle
WebLogic Server Environment, how to deploy flexfields, how to regenerate flexfield
business components programmatically, and how to make flexfield setup task flows
accessible from Oracle Fusion Functional Setup Manager.
This chapter includes the following sections:
Section 27.2, "Deploying and Running the Flexfield Configuration User Interface"
Section 27.8, "Integrating Flexfield Task Flows into Oracle Fusion Functional Setup
Manager"
Using the Run with Flexfields dialog or the Debug with Flexfields dialog from
Oracle JDeveloper as described in Part 27.4.1, "Testing Flexfields from Oracle
JDeveloper."
Using an Integrated WebLogic Server instance as described in Section 27.4.2,
"Testing Flexfields from Integrated WebLogic Server."
Deploying your application to a standalone Oracle WebLogic Server instance as
described in Section 27.5, "Deploying Flexfields in a Standalone WebLogic Server
Environment." With this method, you can do end-to-end testing. That is, you can
configure a flexfield, deploy it, and view the pages that contain the flexfield.
27.2.1 How to Deploy and Run the ApplCore Setup Application to Integrated WebLogic
Server
Use the FndSetup.ear file to deploy the ApplCore Setup application to an Integrated
WebLogic Server instance.
Note: You can use this deployed application to configure flexfields
but you cannot use it to deploy the configurations. However, as you
will generate the flexfield business components using the Tester role
as described in Section 27.4.2, "Testing Flexfields from Integrated
WebLogic Server," you do not need to deploy the configurations.
Although you will not deploy the configurations to an MDS repository, you must
provide the name of a valid MDS repository and JNDI data source in the Applcore
Setup application's adf-config.xml file. For information about MDS repositories,
see the "Managing the Metadata Repository" chapter in the Oracle Fusion
Middleware Administrator's Guide.
If you have not started an Integrated WebLogic Server instance from JDeveloper,
choose Run and then choose Start Server Instance (Integrated WebLogic Server).
Complete the following steps to specify the Oracle Metadata Services (MDS)
repository partition to use for the flexfield configuration metadata.
1.
Change to the directory that contains the copy of the FndSetup.ear file and
complete the following commands to expand the enterprise archive (EAR) file.
mkdir tmpDir
cd tmpDir/
unzip ../FndSetup.ear
2.
Example 271
<metadata-store-usages>
<metadata-store-usage
id="WebCenterFileMetadataStore"
deploy-target="true" default-cust-store="true">
<metadata-store
class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
<property value="repository-name" name="repository-name"/>
<property value="test-partition-name" name="partition-name"/>
<property value="jndi-data-source" name="jndi-datasource"/>
</metadata-store>
</metadata-store-usage>
</metadata-store-usages>
3.
4.
Execute the following commands to re-create the EAR file with the modified
adf-config.xml file.
rm ../FndSetup.ear
zip -r FndSetup.ear .
mv FndSetup.ear ../
rm -Rf tmpDir
3.
Log in to the administration console for the Integrated WebLogic Server instance.
Note that the URL for administration is commonly set to
http://localhost:7101/console.
4.
From the Domain Structure, click Security Realm and then click myrealm in
the Realms table.
b.
Click the Users and Groups tab and click the Users tab.
Configuring Flexfields
c.
5.
6.
7.
In the Path field, type the full path to the directory that contains the FndSetup.ear
file with the modified adf-config.xml file.
8.
9.
with the appropriate host and port, such as localhost and 7101. Log in with the
application_developer user name and the Welcome1 password.
http://host:port/fndSetup/faces/SetupDemo_UIShellPage
See Section 27.3, "Configuring Flexfields" for information about using the application
to configure the flexfields.
2.
See the Implementing Common Features guides for your product family.
Testing Flexfields
Create test segments for the flexfield as described in Section 27.3, "Configuring
Flexfields." The test segment configurations must exist in the ApplicationDB
database for the project.
1.
2.
In the Run with Flexfields dialog (or the Debug with Flexfields dialog), click the
Add icon to add flexfields to the table.
Testing Flexfields
3.
Optionally, select a flexfield and click the Remove icon to remove an unnecessary
flexfield from the table.
4.
If a flexfield that you want to test does not have a Sync Status of Success or the
flexfield configuration was changed after the last time you synchronized it, select
the flexfield and click the Synchronize icon to generate flexfield business
components based on the current flexfield configuration in the database that is
displayed for the Database Connection.
Note: The Sync Status value for existing flexfield entries in the table
reflects the status at the time the dialog was last closed. If you have
made changes to a flexfield, you must synchronize it again even
though it shows a Sync Status of Success.
5.
Ensure that the Include in run check boxes for the flexfields that you want to test
are selected.
6.
Click Run (or click Debug if you are in the Debug with Flexfields dialog) to run
the target in an Integrated WebLogic Server instance.
Create test segments for the flexfield as described in Section 27.3, "Configuring
Flexfields."
3.
If you are importing flexfield components from an existing library, the flexfield
business components must be regenerated after you configure the flexfield.
If you use the Create Flexfield Business Components wizard, select the Tester role on
the Role page of the wizard, and specify a location for the generated business
components. For more information about using the Create Flexfield Business
Components wizard, see the appropriate section for the type of flexfield that want to
test:
Testing Flexfields
1.
2.
In the Application Properties dialog, click the Deployment navigation tab and
click New to create a new deployment profile.
3.
4.
5.
In the panel on the left-hand side of the Edit MAR Deployment Profile Properties
dialog, under MAR Options, select Metadata File Groups and click New.
6.
In the Create File Group dialog, enter a name for the user metadata group, as
shown in Figure 272, and click OK.
Testing Flexfields
7.
In the User Metadata Group section, add a contributor, enter the path to your test
components (a directory or archive), and click OK.
8.
In the panel on the left-hand side of the Edit MAR Deployment Profile Properties
dialog, under MAR Options, expand Metadata File Groups, expand the user
metadata group that you just added, and select the Directories node.
9.
In the Directories section, select the root package directory of the flexfield to be
tested, as shown in Figure 273, and click OK.
Caution: Ensure that you select the correct item. You must select the
directory of the root package of the flexfield to be tested, such that
only the objects that are below the level of that package come from the
test directory. The root package should match the package that you
previously registered with the business component's usage.
tab.
11. Select the MAR profile that you created earlier, and click OK
12. Test your application with the MAR profile.
Note:
When the plugin is enabled in JDeveloper, you will see log entries
with a Flexfield prefix, such as [09:25:01 PM] Flexfield: Search
library "Applications Core"...
For more information about generating EAR files from JDeveloper, see the
"Deploying Fusion Web Applications" chapter in the Oracle Fusion Middleware
Fusion Developer's Guide for Oracle Application Development Framework.
2.
Optionally, unzip the EAR file and inspect the adf-config.xml file to verify that
the flexfield packaging plugin added the flexfield packages to the
sessiondef-config tag and mapped all the flexfield ADF Business Components
packages to a metadata-store-usages tag. Example 272 shows sample tag
entries.
Example 272
<adf-config
xmlns="http://xmlns.oracle.com/adf/config"
xmlns:adf="http://xmlns.oracle.com/adf/config/properties" ... >
...
<mdsC:sessiondef-config>
<mdsC:package
value=
"oracle.apps.fnd.applcore.crmdemo.crma.model.view.link.flex;oracle.apps.fnd.applco
re.flex.test.model.entity.flex"/>
</mdsC:sessiondef-config>
...
<mds:mds-config version="11.1.1.000">
<mds:persistence-config>
<mds:metadata-store-usages>
<mds:metadata-store-usage
default-cust-store="true"
deploy-target="true"
id="WebCenterFileMetadataStore">
</mds:metadata-store>
</mds:metadata-store-usage>
</mds:metadata-store-usages>
</mds:persistence-config>
...
</adf-config>
For more information about MDS configurations and deploying applications, see the
"Deploying the Application" section in the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
The process for deploying a flexfield application includes the following tasks:
1.
b.
c.
d.
2.
Deploy the product application and the ApplCore Setup application to the
WebLogic Server domains.
3.
Log in to the administration console for the WebLogic Server instance and verify that a
Java Database Connectivity (JDBC) data source exists for the MDS repository. This
data source is typically named mds-ApplicationMDSDB. Note that the URL for
administration is commonly set to http://localhost:7101/console.
For more information about managing JDBC data sources, see the "Creating and
Managing JDBC Data Sources" section in the Oracle Fusion Middleware Administrator's
Guide.
To Create an MDS Partition:
1.
Enter the following WLST command to connect to the WebLogic Server instance,
replacing the user name and password arguments with your user name and
password.
connect('wls_username', 'wls_password', 'wls_uri')
27-11
The mds_jdbc_data_source is the JDBC data source for the MDS repository. The
partition_name can be any string. You might want to consult with your operations
team or release team for suggested partition names.
4.
Enter the following WLST command to connect to the WebLogic Server instance,
replacing the user name and password arguments with your user name and
password.
connect('wls_username', 'wls_password', 'wls_uri')
None)
archive.save()
The mds_jdbc_data_source is the JDBC data source for the MDS repository. The
partition_name is the name of the MDS partition that you are using to store the
flexfield customization metadata for all your Oracle Fusion applications. You
might need to ask your operations team or release team for the partition name.
The mds_datasource_JNDI is the JNDI name for the MDS data source, such as
jdbc/mds/mds-ApplicationMDSDBDS. For more information, see the
"registerMetadataDBRepository" section in the Oracle Fusion Middleware WebLogic
Scripting Tool Command Reference.
4.
Optionally, unzip the EAR file and inspect the adf-config.xml file to verify that
the flexfield packaging plugin updated the metadata-store-usage tags to add the
partition name. Example 273 shows sample tag entries.
Example 273
<mds:metadata-store-usages>
<mds:metadata-store-usage default-cust-store="true"
deploy-target="true" id="WebCenterFileMetadataStore">
<mds:metadata-store class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
<mds:property value="mds-ApplicationMDSDB" name="repository-name"/>
<mds:property value="ffpartition" name="partition-name"/>
<mds:property value="jdbc/mds/mds-ApplicationMDSDBDS" name="jndi-datasource"/>
</mds:metadata-store>
</mds:metadata-store-usage>
</mds:metadata-store-usages>
At the command line, enter the following line to start WLST, if it is not currently
running.
sh jdev_install/oracle_common/common/bin/wlst.sh
27-13
If you have not yet connected to the server, enter the following WLST command to
connect to the WebLogic Server instance, replacing the user name and password
arguments with your user name and password.
connect('wls_username', 'wls_password', 'wls_uri')
The mds_jdbc_data_source is the JDBC data source for the MDS repository. The
partition_name is the name of the MDS partition that you are using to store the
flexfield customization metadata for all your Oracle Fusion applications. You
might need to ask your operations team or release team for the partition name.
The mds_datasource_JNDI is the JNDI name for the MDS data source, such as
jdbc/mds/mds-ApplicationMDSDBDS.
27.5.2.4 Including Product Application Model Libraries in the ApplCore Setup EAR
File
Before you deploy the ApplCore Setup EAR file, ensure that it contains all the model
libraries that are required for your product application.
To include the product application model libraries in the ApplCore Setup EAR file:
1.
In a terminal window, change to the directory that contains the FndSetup.ear file.
This file can typically be found in the jdev_
install/jdeveloper/jdev/oaext/external directory.
2.
3.
If the APP-INF/lib folder does not exist, execute the following commands to create
it.
mkdir APP-INF
mkdir APP-INF/lib
4.
Copy all the library Java archive (JAR) files that your product requires to the
APP-INF/lib folder.
5.
6.
Execute the following commands to re-create the EAR file with the added JAR
files.
rm ../FndSetup.ear
zip -r FndSetup.ear .
mv FndSetup.ear ../
rm -Rf tmpDir
27.5.2.5 Deploying the Product and Setup Applications to the Server Domains
After you have mapped the applications as described in Section 27.5.2.2, "Mapping the
EAR File to the MDS Partition" and Section 27.5.2.3, "Mapping the ApplCore Setup
Application to the MDS Partition" and you have included the project model libraries in
the ApplCore Setup application as described in Section 27.5.2.4, "Including Product
Application Model Libraries in the ApplCore Setup EAR File," you can deploy the
applications to the appropriate domains for your topology.
For information about creating domains, see the "Creating a WebLogic Domain"
chapter in Oracle Fusion Middleware Creating Domains Using the Configuration Wizard.
For information about installing EAR files, see the "Install an Enterprise Application"
section in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console
Online Help.
2.
See the Implementing Common Features guides for your product family.
In addition, the following WLST commands are available for priming the MDS
repository with seeded flexfield artifacts and for deploying flexfields:
deployFlexForApp: Use this command to prime the MDS repository with seeded
flexfield artifacts. Deploys all flexfields that do not have a status of DEPLOYED.
You can also use this comment to deploy all flexfields regardless of their status by
setting the force parameter to 'true'.
deployFlex: Use this command to deploy a single flexfield. Deploys the flexfield
regardless of status.
deleteFlexPatchingLabels: Use this command to inquire about or delete all
flexfield patching labels.
27-15
For information about using the WLST command-line scripting interface, see Oracle
Fusion Middleware Oracle WebLogic Scripting Tool.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
Before you can use any WLST flexfield command from a development environment,
you must first prepare the environment as described in Section 27.6.1, "How to Prepare
Your Environment to Use the WLST Flexfield Commands." If you use the
deployFlexForApp command in a development environment, you must complete
additional steps described in Section 27.6.2, "How to Prepare Your Environment to Use
the deployFlexForApp Command."
After you execute a WLST flexfield command, you can log into the application and
view the pages that contain flexfields. If you have seeded any flexfield configurations
by defining value sets, segments, contexts, or structures, for example, the flexfields
should appear on the appropriate pages. If a flexfield has not been configured, the
corresponding user interface sections will be blank.
27.6.1 How to Prepare Your Environment to Use the WLST Flexfield Commands
Before you can use the WLST flexfield commands, you must prepare your
environment. The commands will not work until these steps are completed.
To prepare your environment for WLST flexfield commands:
1. The WLST flexfield commands can be executed only on the Administration Server
for a domain that has a running instance of the ApplCore Setup application. For
information on deploying the ApplCore Setup application, see Section 27.5.2.5,
"Deploying the Product and Setup Applications to the Server Domains."
2.
Ensure that the AppMasterDB data source is registered as a JDBC data source with
the Administration Server and points to the same database as the ApplicationDB
data source.
Map the setup application as described in Section 27.5.2.3, "Mapping the ApplCore
Setup Application to the MDS Partition."
3.
Deploy the product application and the ApplCore Setup application as described
in Section 27.5.2.5, "Deploying the Product and Setup Applications to the Server
Domains."
4.
The ADF Business Components objects required for generating the flexfield
business components. Typically these are entity objects. You can deploy them in a
JAR file.
The MDS repository for the generated flexfield business components. If you use a
file-system based repository, the metadata path must be an existing writable path.
You either can create a new application to invoke the modeler, or, if you already have a
web application for testing, you can include the Java code required for invoking the
modeler in your application. The deployment process is the same as any other web
application.
Your project must be set up correctly for the program to run successfully. The project
configuration requirements are the same as that for the Create Flexfield Business
Components wizard.
Example 274 demonstrates appropriate Java code for updating the business
components for a descriptive flexfield.
Example 274
import oracle.apps.fnd.applcore.flex.runtime.util.BCModeler;
public class Example
{
public static void main(String[] margs)
{
BCModeler.Arguments modelerArgs = new BCModeler.Arguments();
modelerArgs.put(BCModeler.Parameter.CONNECTION_URL,
"jdbc:oracle:thin:user/pass@myhost.com:1999:dev1");
// Specify where the objects should be.
modelerArgs.put(BCModeler.Option.OUTPUT_PATH,
"/mytest/mds/");
// The owner of the flexfield should have the following information.
Testing and Deploying Flexfields
27-17
Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager
modelerArgs.put(BCModeler.Parameter.FLEXFIELD_TYPE, "DFF");
modelerArgs.put(BCModeler.Parameter.APP_SHORT_NAME, "FND");
modelerArgs.put(BCModeler.Parameter.FLEXFIELD_CODE, "FLEX_DFF1");
modelerArgs.put(BCModeler.Parameter.TABLE_USAGE_CODE, "FLEX_DFF1");
modelerArgs.put(BCModeler.Parameter.TABLE_NAME, "FND_DF_TEST_DFF1_T1");
modelerArgs.put(BCModeler.Parameter.ENTITY_DEF_FULL_NAME,
"oracle.apps.fnd.applcore.flex.test.model.entity.Dff1EO");
// See BCModeler.Option for more usage-specific options. Consult the owner
// of the flexfield to see if any usage-specific option is required.
Exception e = BCModeler.run(modelerArgs.getCommandLineArgs(false),
System.out);
if (e != null)
{
e.printStackTrace();
}
}
}
27.8 Integrating Flexfield Task Flows into Oracle Fusion Functional Setup
Manager
Every Oracle Fusion application registers task flows for setup activities with a product
called Oracle Fusion Functional Setup Manager. For example, a human resources (HR)
application can register setup activities such as "Create Employees" and "Manage
Employee Tree Structure." Implementors and administrators use these registered task
flows, which are accessed from the Oracle Fusion Applications Setup and Maintenance
work area of Oracle Fusion Applications, to configure the applications by defining
custom configuration templates or tasks based on their business needs.
The registration application task flow is not available for
extensible flexfields and key flexfields. You must use the FND_FLEX_
DF_SETUP_APIS PL/SQL to register extensible flexfields as described in
Chapter 24.7, "Defining and Registering Extensible Flexfields." You
must use the FND_FLEX_KF_SETUP_APIS PL/SQL API to register key
flexfields as described in Section 25.2.1, "How to Develop Key
Flexfields."
Note:
Table 271 lists the flexfield setup task flows. To make these task flows available to
developers, implementors, or administrators, register the appropriate task.
For information about implementing your specific product family, do the following:
1.
2.
See the Implementing Common Features guides for your product family.
Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager
Table 271
Task Flow
Name
Manage
Descriptive
Flexfields
Parameters Passed
Behavior
/WEB-INF/oracle/apps/fnd/applcore
/flex/dff/ui/publicFlow/ManageDes
criptiveFlexfieldsTF.xml#ManageDe
scriptiveFlexfieldsTF
mode='search'
To restrict search mode to descriptive flexfields
belonging to a particular product module:
mode='search'
moduleType='moduletype'
moduleKey='modulekey'
To invoke edit mode for a specific descriptive
flexfield:
mode='edit'
descriptiveFlexfieldCode=dffcode
applicationId=appid
To optionally specify a page heading for the task
flow:
pageTitle='titlestring'
27-19
Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager
Parameters Passed
Behavior
/WEB-INF/oracle/apps/fnd/applcore
/flex/dff/ui/publicFlow/ManageExt
ensibleFlexfieldsTF.xml#ManageExt
ensibleFlexfieldsTF
mode='search'
To restrict search mode to extensible flexfields
belonging to a particular product module:
mode='search'
moduleType='moduletype'
moduleKey='modulekey'
To invoke edit mode for a specific extensible
flexfield:
mode='edit'
extensibleFlexfieldCode=effcode
applicationId=appid
To optionally specify a page heading for the task
flow:
pageTitle='titlestring'
Manage Key
Flexfields
/WEB-INF/oracle/apps/fnd/applcore
/flex/kff/ui/publicFlow/ManageKey
FlexfieldsTF.xml#ManageKeyFlexfie
ldsTF
Manage
Value Sets
/WEB-INF/oracle/apps/fnd/applcore
/flex/vst/ui/publicFlow/ManageVal
ueSetsTF.xml#ManageValueSetsTF
For related information about functional security actions and roles based on task
flows, see Part 51, "Implementing Function Security."
Part V
Part V
Chapter 28, "Getting Started with Oracle Enterprise Crawl and Search Framework"
28
Getting Started with Oracle Enterprise Crawl
and Search Framework
28
Getting Started with Oracle Enterprise Crawl and Search Framework 28-1
Search Designer
Semantic Engine
Security Services
Data Services
Query Service
ECSF integrates with the Oracle Secure Enterprise Search (Oracle SES) engine to
support application search. Oracle SES provides capabilities for crawling and indexing
the metadata and objects exposed by ECSF. The Security Plug-in and Crawler Plug-in
are modules on Oracle SES that interface with ECSF.
Facets
Actionable results
Security
Personalization
Internationalization
Results clustering
Context filtering
Custom weighting
Getting Started with Oracle Enterprise Crawl and Search Framework 28-3
Note:
Note:
Before you can run the utility, you must complete the following setup requirements:
1.
Make the searchable objects accessible to the ECSF Command Line Admin Utility.
2.
Set the class path to make sure it contains the required Oracle classes. ECSF
provides a set of scripts that you can use to set the class path.
3.
Provide the connection information in the script so that the ECSF Command
Line Administration Utility automatically connects to the specified database
during startup.
Manually connect to the database after you start the ECSF Command Line
Administration Utility.
4.
5.
Create ECSF query proxy users. To perform commands that connect to the Oracle
SES server (for example, deploy, start schedule, etc.), the engine instance must
be set up correctly so that its parameters have the required information. For more
information, see the "Managing Search with Oracle Enterprise Crawl and Search
Framework" chapter in the Oracle Fusion Applications Administrator's Guide.
6.
7.
(Optional) Set the startup parameter to support taking input from a text file.
After you have set up the ECSF Command Line Administration Utility, you can run
the utility by any of the following ways:
Start it as a Java program from a command line interface with the following
command:
java oracle.ecsf.cmdlineadmin.CmdLineAdmin
Getting Started with Oracle Enterprise Crawl and Search Framework 28-5
28.2.1 How to Make Searchable Objects Accessible to the ECSF Command Line
Administration Utility
Make the searchable objects accessible to the ECSF Command Line Administration
Utility by adding the ADF library JAR file containing the view object and entity object
definitions to its class path.
The ECSF Command Line Administration Utility needs the path of the JAR file
containing the searchable objects. These metadata objects are validated during register
and unregister operations.
You can find the unpacked EAR files containing the searchable object JAR files for the
search applications in the following locations:
/net/mount1/appbase/fusionapps/applications/fscm/deploy/EarFscmSearch.ear
/APP-INF/lib/searchable_object_jar_file
/net/mount1/appbase/fusionapps/applications/crm/deploy/EarCrmSearch.ear/A
PP-INF/lib/searchable_object_jar_file
/net/mount1/appbase/fusionapps/applications/hcm/deploy/EarHcmSearch.ear/A
PP-INF/lib/searchable_object_jar_file
To add the ADF library JAR file containing the view object and entity object definitions
to the class path for the ECSF Command Line Administration Utility, you must first
create the ADF library.
The application JAR file, which contains the searchable objects that are defined in your
application, is written to the deploy directory of the project.
To deploy or undeploy a searchable object, a JAR file containing the searchable object
must be specified in the class path of the ECSF Command Line Administration Utility.
For information, see Section 28.2.2, "How to Set the Class Path."
If you are deploying searchable objects from multiple applications, you must create a
JAR file for each of those applications to add the searchable objects to the class path.
as well as optional connection information, and run the ECSF Command Line
Administration Utility.
Note: If you receive a java.lang.ClassNotFoundException
exception, then add the JAR file containing that class to ADMIN_CP in
the script.
The ECSF Command Line Administration Utility references the class path to obtain
the location of Oracle Library home, Java home, Oracle WebLogic Server home, and
the JAR files needed for the ECSF Command Line Administration Utility operations.
Specify the Oracle Library home directory path by locating the line set ORACLE_
LIBRARY_HOME=SET_ORACLE_LIBRARY_HOME and replace SET_ORACLE_LIBRARY_HOME
with the ATGPF shiphome directory, for example, set ORACLE_LIBRARY_
HOME=C:\mw_home\oracle_common.
3.
Specify the ATGPF Library home directory path by locating the line set ATGPF_
LIBRARY_HOME=SET_ATGPF_LIBRARY_HOME and replace SET_ATGPF_LIBRARY_HOME
with the ATGPF shiphome directory, for example, set ATGPF_LIBRARY_
HOME=C:\mw_home\Oracle_atgpf1.
Specify the ATGPF Library home directory path by locating the line set ATGPF_
LIBRARY_HOME=SET_ATGPF_LIBRARY_HOME and replace SET_ATGPF_LIBRARY_HOME
with the ATGPF Library directory, for example, set ATGPF_LIBRARY_
HOME=c:\fmwtools_view\fmwtools\mw_home\jdeveloper.
4.
5.
b.
Replace SET_WLS_HOME with the Oracle WebLogic Server home directory path,
for example, set WLS_HOME= C:/MW_HOME/wlserver_10.3
The version of Java used must match the version required by the Oracle build.
6.
7.
Getting Started with Oracle Enterprise Crawl and Search Framework 28-7
Specify the Oracle Library home directory path by locating the line export
ORACLE_LIBRARY_HOME=SET_ORACLE_LIBRARY_HOME and replace SET_ORACLE_
LIBRARY_HOME with the ATGPF shiphome directory, for example, export ORACLE_
LIBRARY_HOME="/scratch/mw_home/Oracle_atgpf1".
Specify the Oracle Library home directory path by locating the line export
ORACLE_LIBRARY_HOME=SET_ORACLE_LIBRARY_HOME and replace SET_ORACLE_
LIBRARY_HOME with the Oracle Common Library directory, for example, export
ORACLE_LIBRARY_HOME="/scratch/login/view_storage/login_fmwtools_
view/fmwtools/mw_home/oracle_common".
3.
Specify the ATGPF Library home directory path by locating the line export
ATGPF_LIBRARY_HOME=SET_ATGPF_LIBRARY_HOME and replace SET_ATGPF_LIBRARY_
HOME with the ATGPF shiphome directory, for example, set ATGPF_LIBRARY_
HOME="/scratch/fmwtools/mw_home/Oracle_atgpf1".
4.
The version of Java used must match the version required by the Oracle build.
5.
6.
7.
The information for connecting to the database or MBean server is saved in the
runCmdLineAdmin script for the ECSF Command Line Administration Utility to use for
connecting to the Oracle Fusion Applications database at startup. You are prompted to
enter a password after you start the ECSF Command Line Administration Utility.
Locate set CONNECT_INFO= and specify the database or MBean server, using one of
the following formats:
Using SID:
connect to database hostname port SID
For example,
set CONNECT_INFO=connect to database fusionhost123 1566 fh123.
Using SID:
set CONNECT_INFO=connect to database descriptor '(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNECT_
DATA=(SID=dbmsdb2)))'
3.
Getting Started with Oracle Enterprise Crawl and Search Framework 28-9
Locate export CONNECT_INFO="" and specify the database or MBean server, using
one of the following formats:
Using SID:
connect to database hostname port SID
For example,
set CONNECT_INFO=connect to database fusionhost123 1566 fh123
Using SID:
set CONNECT_INFO=connect to database descriptor
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(C
ONNECT_DATA=(SID=dbmsdb2)))'
3.
connect to database
The ECSF Command Line Administration Utility prompts you for the host name,
port, and SID.
Using SID:
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNE
CT_DATA=(SID=dbmsdb2)))'
Using SID:
'(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=fusionhost123)(PORT=5521))(CONNE
CT_DATA=(SID=dbmsdb2)))'
connect to mbeanserver
The ECSF Command Line Administration Utility prompts you for the required
values.
Getting Started with Oracle Enterprise Crawl and Search Framework 28-11
You can directly pass the required values as arguments into the command.
The ECSF Command Line Administration Utility prompts you to enter a username
and password.
1.
2.
3.
Save.
SERVICE"="http://example.com:7777/search/api/admin/AdminService"
set param "SES_ADMIN_USERNAME" = "eqsys"
exit
You must know all of the object IDs when you create the input file. Using the input
file, you cannot create a new object and then manage it in one automation.
To configure the startup script to automatically run the commands you defined in the
input file, you must modify the startup script to include the AUTOMATE command in the
STARTUP_PARAMS parameter.
To set the JPS Config file path:
1. Open the runCmdLineAdmin.bat (Windows) or runCmdLineAdmin.sh (Linux) script,
located in ORACLE_HOME/jdeveloper/ecsf, in a text editor.
2.
Set the STARTUP_PARAMS parameter to AUTOMATE and point to the location of input
file. For example,
STARTUP_PARAMS="AUTOMATE /scratch/commands.txt"
where commands.txt is the input filename.
3.
Save.
The output of the ECSF Command Line Administration Utility is displayed on the
screen (or can be redirected), and errors are logged in the log file as usual. If the
input file cannot be found, the ECSF Command Line Administration Utility runs
in its usual mode and waits for the user to input a command through the prompt.
2.
3.
4.
Multiple developers can share one single Oracle Enterprise Manager application with
the Fusion Applications Control.
28.3.1 How to Register the ECSF Runtime MBean to the Integrated WebLogic Server
The ECSF runtime application registers an MBean
(oracle.ecsf.mbean.SearchRuntimeAdminMXBean) in WebLogic's Domain Runtime
Getting Started with Oracle Enterprise Crawl and Search Framework 28-13
3.
4.
5.
Registering the ECSF runtime MBean to the Integrated WebLogic Server makes the
MBean available to remote clients such as Fusion Applications Control in Oracle
Enterprise Manager.
3.
Save.
Host (the name of the machine that hosts Oracle WebLogic Server)
Port (the Oracle WebLogic Server runtime port number, for example, 7101)
Note:
3.
Click Farm_DefaultDomain.
4.
5.
Username: weblogic
Password: weblogic
Getting Started with Oracle Enterprise Crawl and Search Framework 28-15
Note:
29
Creating Searchable Objects
29
This chapter describes how to create searchable objects in Oracle Fusion Applications.
This chapter includes the following sections:
2.
(Optional) Enable the capability to crawl searchable objects with file attachments.
For more information, see Section 33.2, "Enabling Search on Fusion File
Attachments."
3.
4.
5.
6.
Note:
Consider the following when you define searchable objects and searchable attributes:
Rather than reuse or functionally overload view objects designed for other
purposes, construct view objects (parent and children) for search purposes (that is,
include only attributes you intend to search).
Exclude large objects (LOBs) from searchable objects unless you intend to search
LOB contents.
Restrict the use of multilevel view objects to five levels to avoid causing severe
feed performance degradation.
Collocate all servers (for example, ECSF, Oracle SES, database, and so on) and
follow standard performance, scalability, and reliability network performance
guidelines to minimize network latency between servers.
Remember that feed throughput is directly proportional to the amount of data that
is pulled from the database to be indexed.
Be selective with the searchable objects to ensure that only a limited portion of
data from the primary table is crawled to maximize crawling and indexing
performance.
Remember that attachments (Oracle Content Management SDK or LOBs) require
record by record processing, and every record requires one additional network
round-trip.
Store attributes only when necessary. Use attributes stored in Oracle SES only for
the following purposes:
Faceted navigation
Advanced search
Primary keys
If the value of an attribute must be searchable, then place it in the body of the
searchable object.
Raising change events. For information, see Section 33.8, "Raising Change
Events Synchronously."
If neither mechanism is implemented, then the data that has been added or
modified since the initial crawl will not be indexed, and therefore will not be
searchable.
To define searchable objects and searchable attributes, use the Search navigation tab of
the overview editor in Oracle JDeveloper to complete the following tasks:
1.
2.
Note:
When querying for root records during crawl time, ECSF also
traverses the view link accessors to query child view objects. ECSF
follows the parent view link accessors until it reaches the limit for the
number of view accessor levels to be crawled. The default limit is set
to 5 levels. If a parent view object has a view link accessor to its child
view object, and the child view object also has a view link accessor
pointing back to the parent view object, then the code cycles. It is not
necessary to index the data in both parent and child view objects.
When creating a view link object in Oracle JDeveloper, generate the
view link accessors in either end of the view link. Generate the view
link accessor only in the parent view object and not in the child view
object.
When defining search metadata, Groovy expressions are used to reference the
attributes of view objects and the attributes of their child, grandchild, and so on view
objects so that the attribute (string) values can be added into the ECSF index. You are
required to enter Groovy expressions for fields such as Title, Body, and Keyword.
You can also use Groovy expressions to localize ECSF. For information, see
Section 33.10, "Localizing ECSF Artifacts."
If the value for RowId is 1234, the value for Customer is ABC Inc, and the value for
CreatedDate is 1/1/2007, then a search would return the following title value:
Purchase Order 1234 created for ABC Inc on 1/1/2007
The ECSF runtime code parses, then evaluates the expressions in the context of a view
object, and returns the title with values for the variables.
If the view object represented by the ProductsView view link accessor contains one
record, and the value of its ProdCode attribute is 1XYZ, then a search would return the
following title value:
Product Codes: 1XYZ
If a child view object referenced by an expression contains more than one record, then
the values of all the child records are concatenated. For example, if the ProductsView
view link accessor contains three records, and the values of its ProdCode attribute are
1XYZ, 2ABC, and 3STU, then a search would return the title value:
Product Codes: 1XYZ 2ABC 3STU.
The view link accessor name for a child view object is available on the view link that
points to the child view object. The name of the view link accessor is the Destination
value. In Figure 291, which shows the accessor information about the Relationship
navigation tab of the view link editor, the name of the view link accessor is ZipLov.
Figure 291 Location of View Link Accessor Name for Child View Object
You can also find the name of view link accessor in the <ViewLinkAccessor> tag of the
XML source code of the view object.
Alternatively, you can use the curdoc keyword to access the current document, as
shown in Example 291.
Example 291
s = "";
if (curdoc.getChildDocs("ProductsView") != null)
{
for (d in curdoc.getChildDocs("ProductsView"))
{
s = s + d.attributes.ProdCode + " ";
}
};
"Product Codes: " + s;
The curdoc keyword is used to access child documents and their attributes.
Using Groovy expressions in the search metadata, you can access attributes in the
levels PO Line Detail, Line Item Product, and Product Doc. For example, you can
enter the following Groovy expression in the Title field:
POLine.LineDetail.AttributeX + POLine.LineDetail.LineProduct.AttributeY +
POLine.LineDetail.LineProduct.ProductDoc.AttributeZ
If a grandchild view object referenced by an expression contains more than one record,
then the values of all the grandchild records are concatenated. For example, if you
reference view object attributes with
viewLinkAccessorName.viewLinkAccessorName.voAttrName, then the result of the
expression POLine.LineDetail.AttributeX is the concatenation of all AttributeX
values for the LineDetail attribute of all POLine levels of the current PurchaseOrder
searchable object.
The class name of the Hiredate attribute's value is displayed and can be viewed in the
Data Feed:
Hiredate type: java.sql.Date.
After you determine the Java data type of a view object attribute, you can apply
standard Java formatting techniques to format its value. Example 293 shows a sample
Groovy expression for formatting a date.
Example 293
Note:
2.
If the view object is based on an entity object, then select a value from the
Primary Table dropdown menu.
If the view object is not based on an entity object, then enter the schema, table
name, and table alias for the primary table. Use the format DATABASE_
SCHEMA.TABLENAME TABLE_ALIAS_NAME (for example, fusion.Emp Employee).
You can either enter text directly into the text box or use the Select Primary
Table dialog. For more information, see Section 29.2.3.2, "Using the Select
Primary Table Dialog."
The table alias name you enter must match the table alias
name used in the view object's SQL statement. You can view the SQL
statement by selecting the view object's Query tab.
Note:
3.
In the Title field, enter a Groovy expression to be evaluated to a string for the
desired title of the search result. For more information, see Section 29.2.1, "How to
Use Groovy Expressions in ECSF."
The Title field allows for multiple lines of text.
You can also click the Edit icon to open the Edit Expression Editor, where you can
enter Groovy expressions for the desired title of the search result. Click OK to
save.
Note: Do not include attributes of type character large object (CLOB)
or binary large object (BLOB) in the Groovy expressions for the Title,
Body, and Keywords fields, or you will receive an error. All columns
with type CLOB or BLOB in a view object or its child view objects are
processed as Oracle SES attachments.
4.
5.
In the Keywords field, enter the keywords in the form of Groovy expressions. For
more information, see Section 29.2.1, "How to Use Groovy Expressions in ECSF."
You can also click the Edit icon to open the Edit Expression Editor, where you can
enter Groovy expressions for the desired title of the search result. Click OK to
save.
The values of the keywords are evaluated at crawl time using Groovy expressions,
and sent to Oracle SES as part of the document for indexing. After they are
indexed, the values of the keywords are searchable for the document with which
they are associated.
6.
Select the desired view object attribute from the Language Attribute dropdown
menu to specify the language of this view object record. If the object has no
language attribute, then leave it blank.
Currently, ECSF provides a way for you to specify if an
attribute is a language field. ECSF will assume that the value of this
field for each instance is the language for this instance. ECSF initially
supports the Oracle Fusion Applications language code. If no
language field is specified for a given searchable object, then ECSF
uses the language preference of the crawler user.
Note:
7.
Complete the Search PlugIn field by using the Search PlugIn dialog. For more
information, see Section 29.2.3.3, "Using the Search PlugIn Dialog."
8.
Note:
2.
Select the desired schema from the Database Schema dropdown menu.
3.
With the Tables checkbox selected in the Object Type field, click Query to list the
available tables.
4.
Select the desired table name from the list under Available Objects.
5.
Enter an alias for the primary table in the Table Alias field.
The table alias entered must match the table alias used in the
view object's SQL statement. You can view the SQL statement by
selecting the view object's Query tab.
Note:
6.
Click OK.
You must select a primary table from the Available Objects list
to save the changes.
Note:
Use the Search PlugIn dialog to specify the extension you want to use for the
searchable object.
Note:
2.
In the PlugIn Class Name field, enter the name of the custom Java class that
implements the methods to determine security and resolve the URL.
If there is no plug-in defined in the searchable object, and you
are not using a custom security extension, then this value is null and
by default is set to oracle.ecsf.impl.DefaultSearchPlugin, which is
used at runtime.
Note:
3.
Optional: Enter a parameter name in the Parameter Name field and its
corresponding value in the Value field, and click Add.
4.
To update an existing parameter, select the desired parameter in the table, change
its value, and then click Update.
5.
To delete an existing parameter, select the desired parameter in the table and click
Delete.
6.
Note:
Caution:
ECSF metadata can be packaged into an EAR file or a MAR file for consumption
during crawl time and query time.
29.2.5 What You May Need to Know About Making View Objects Searchable
The searchable object reflects any change in the search metadata only after you save
the view object. Until then, the changes are in memory. When you save the view object,
the search metadata is saved to the searchable object. If there is no existing searchable
object corresponding to the view object, then a new searchable object is created and
stored in the same location as the view object.
In addition, if you rename or delete a view object with a corresponding searchable
object, then the searchable object is likewise renamed or removed from the project.
Advanced search
Faceted navigation
Security
Note:
Use the Search navigation tab of the overview editor in JDeveloper, shown in
Figure 296, to set property values for view object attributes.
Figure 296 Search Page for Configuring Search Properties of View Object Attributes
Using the Search navigation tab, you can perform the following tasks on view object
attributes:
2.
Click the Add icon in the Searchable Attributes table header to open the
Searchable Attribute Properties dialog, shown in Figure 297.
3.
Select the desired view object attribute from the Attribute Name dropdown menu.
4.
Complete the remaining fields to define the property set for the searchable
attribute. For information about the searchable attribute properties, see Table 291.
Before creating new stored attributes, check the list of Oracle
SES attribute names and types to avoid conflicts. See Oracle Fusion
Applications Reference for Oracle SES Attributes.
Note:
Table 291
Property
Description
Stored
Secure Attribute
Description
Weight
Override Source
Note:
5.
Click OK.
6.
2.
Expand the Searchable Attributes table header to expose the table of searchable
attributes.
3.
Select the searchable attribute you want to modify. This highlights the entire row.
4.
Click the Edit icon in the Searchable Attributes table header to open the
Searchable Attribute Properties dialog, shown in Figure 297.
The attribute you selected on the Search navigation tab is displayed in the
Attribute Name field.
5.
Select or deselect the checkboxes to modify the property set for the searchable
attribute. For information about the searchable attribute properties, see Table 291.
6.
Click OK.
7.
2.
Expand the Searchable Attributes table header to expose the table of searchable
attributes.
3.
Select the searchable attribute you want to remove. This highlights the entire row.
4.
Click the Delete (red X) icon in the Searchable Attributes table header.
The attribute you selected on the Search navigation tab is removed from the table
of searchable attributes.
5.
Caution:
ECSF_SO_NAME. This attribute stores the fully qualified searchable object name that
corresponds to the searchable object on which the Oracle SES data source is based.
ECSF_TAGS. This attribute is created if Oracle WebCenter Portal tags are associated
with the searchable object. For information, see Section 33.3, "Enabling Search on
WebCenter Tags."
DEFAULT_ACL_KEY. ECSF uses this attribute to store access control list (ACL) keys
for the document.
29.2.8 What You May Need to Know About Defining Searchable Attributes
The searchable object reflects any change in the search metadata only after you save
the view object. Until then, the changes are in memory. When you save the view object,
the search metadata is saved to the searchable object. If there is no existing searchable
object corresponding to the view object, then a new searchable object is created and
stored in the same location as the view object.
In addition, if you rename or delete a view object with a corresponding searchable
object, then the searchable object is likewise renamed or removed from the project.
Caution: Do not manually delete an attribute that has a
corresponding search attribute from a view object, because it causes
unexpected search results.
29.2.9 What You May Need to Know about Preventing Conflicts with Oracle SES Default
Search Attributes
Oracle SES supports system-defined default search attributes that may conflict with
ECSF stored view object attributes. For example, for Purchase Order 123 you define a
stored view object attribute with the alias Language and value US. However, Oracle SES
contains a default search attribute also named Language, but it has en as its value.
When you reference the view object attribute in a Groovy expression, such as when
you define a search result action of URL type where
target="http://example.com/q=dj&lang="+Language, you expect the search result
action to display as http://example.com/q=dj&lang=US.
However, the search result action displays as http://example.com/q=dj&lang=en
because the Oracle SES default search attribute value overrides the value of the ECSF
stored view object attribute of the same name.
The attribute conflict does not consider case. For example, a
conflict still occurs if the stored view object attribute's alias is
LANGUAGE (all caps) and the Oracle SES default search attribute name is
Language.
Note:
Author
Description
Headline1
Headline2
Headline3
Host
Infosource
Infosource Path
Keywords
Language
LastModifiedDate
Mimetype
Reference Text
Subject
Title
Url
Urldepth
Author, LastModifiedDate, and Subject are the exceptions, and can be used to
enhance usability of the Oracle SES UI and to decrease the number of custom
attributes in Oracle SES.
To prevent a conflict between Oracle SES default search attributes and ECSF stored
view object attributes, you can either change the alias of the stored view object
attribute to something other than any name of the Oracle SES default search attributes,
or you can create a view object transient attribute and set it as a stored attribute, and
then reference the transient attribute in the expressions.
To resolve the conflict in the given example, you can change the alias value of the
Language view object attribute from Language (default) to Lang. The view object
attribute alias is used to retrieve the value of the view object attribute in expressions.
Alternatively, you can resolve the conflict by creating a view object transient attribute,
such as one named Lang, and use it in the expressions (for example,
target="http://example.com/q=dj&lang="+Lang). By default, when the values of
transient attributes are sent to Oracle SES, ECSF assigns the transient attribute a
unique alias. When their values return as part of query results, they will not conflict
with any default search attributes in Oracle SES. When expressions containing
transient attributes are evaluated, ECSF converts the transient attribute names to the
aliases and retrieves the data correctly.
29.2.10 What You May Need to Know About Preventing Search Attribute Naming
Conflicts
Because Oracle SES supports facets only on attributes of type STRING, if a facet is
defined on a nonstring attribute, then ECSF automatically converts the stored attribute
type to a string before sending the attribute to Oracle SES.
However, a conflict may occur when a stored attribute of the same name is generated
for a view object with no facets. Searchable attributes in Oracle SES are unique across
the entire instance, so if multiple searchable objects contain the same attribute name of
different types, then only the attribute (regardless of type) of the first searchable object
crawled is used by Oracle SES. ECSF does check for stored attribute conflicts. For more
information, see Section 29.2.10.1, "Checking for Stored Attribute Conflicts."
Consider the following example:
You create a view object oracle.apps.crm.cutomer360.CustomerPVO with a set of
attributes and types that are based on the underlying tables that use the Oracle
ADF standard UI. The view object attribute contains the following information
stored as Oracle ADF metadata:
Attribute Name
Attribute Alias
Attribute Type
Name
NAME
VARCHAR2
OrganizationId
ORGANIZATION_ID
NUMBER
Attribute Name
Attribute Alias
Attribute Type
Description
DESCRIPTION
VARCHAR2
You use the Search Designer to annotate a subset of these attributes (Name and
OrganizationId) to store in Oracle SES for search purposes. For more information, see
Section 28.1.1.2, "Search Designer."
When Oracle SES crawls oracle.apps.crm.cutomer360.CustomerPVO, ECSF sends a
document for each customer in the table. Each document contains the following
attribute details:
Attribute Alias
Attribute Type
NAME
VARCHAR2
ORGANIZATION_ID
NUMBER
In Oracle SES, NAME and ORGANIZATION_ID are created as customer attributes with the
respective types. Due to the global nature of custom attributes in Oracle SES, if an
attribute of the same name already exists, then no new attribute is created even if its
type is different. Values for the attributes with conflicting name and type pairs are not
stored in Oracle SES.
The issue surfaces when ORGANIZATION_ID is used as a facet (to enable users to narrow
down the results per organization tree). ECSF implements a logic that detects whether
an attribute is used for a facet. If it is used for a facet, then ECSF automatically changes
the attribute type from NUMBER to VARCHAR2 because Oracle SES does not support facets
on attributes with type NUMBER. This causes a conflict with the already existing
ORGANIZATION_ID stored attribute of type NUMBER.
To prevent this conflict and allow Oracle SES to index both attributes, you must
change the alias of the stored attribute that is used for facets. Go to the JDeveloper
ADF view object attribute editor and update the Alias property value, as shown in
Figure 298. For example, in the view object attribute editor, change the Alias value
from PARTY_ID to PARTY_ID_FACET.
Before creating new stored attributes, check the list of Oracle SES attribute names and
types to avoid conflicts. See Oracle Fusion Applications Reference for Oracle SES
Attributes.
You will have to change the SO so that the conflicting attribute either has a new name
or has the same type as the attributes already defined in SES.
group search on related items. Search categories are directly used for querying. If all of
the searchable objects in a search category are not accessible to the user, then that
category does not appear in the user's category list. In this case, ECSF runtime does
not return that category when SearchCtrl.getSearchGroups() is called. However, if
any one of the searchable objects in a search category is accessible to the user, then that
category does appear in the user's category list.
To secure searchable objects:
1.
2.
3.
Add the following parameter names and values, and click Add for each name and
value pair:
3.
Click OK.
The parameters are used to validate permissions in the ECSF security classes.
Searchable objects with no permissions set are accessible by all users.
1.
2.
Select Identity Store, and click New to add a new realm. Name it jazn.com.
3.
Navigate to jazn.com > Users, and click Add to add a user with the following
information:
Name: scott
Credentials: weblogic
The jazn-data.xml file is updated with the security realm, as shown in
Example 295.
Example 295
<jazn-realm default="jazn.com">
<realm>
<name>jazn.com</name>
<users>
<user>
<name>scott</name>
<credentials>{903}O/XvB3XDx97MYp4sUSWwT3Q5KPLIEciA</credentials>
</user>
</users>
</realm>
</jazn-realm>
Save.
1.
2.
Select Application Policy Store, and click New to add a new policy store. Enter
TestPermission for the display name.
3.
Select Application Roles, and click Add to add a new role. Name it admin.
4.
Select Application Roles, and shuttle the user scott from the Available section to
the Selected section.
5.
Select Application Policies, and click New to add a new policy. Enter View Orders
for the display name.
6.
Select the View Orders application policy, go to the Principals tab, and click Add
to add a principal with the following information:
Name: admin
Class: oracle.security.jps.service.policystore.ApplicationRole
Type: role
Leave the Realm Name field blank.
7.
Go to the Permissions tab, and click Add to add a permission with the following
information:
Name: PURCHASE_ORDER_VIEW_DETAILS
Class: oracle.adf.share.security.authorization.RegionPermission
Actions: view
The jazn-data.xml file is updated with the application policy store, as shown in
Example 296.
Example 296
<policy-store>
<applications>
<application>
<name>TestPermission</name>
<app-roles>
<app-role>
<name>admin</name>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<members>
<member>
<name>scott</name>
<class>oracle.security.jps.internal.core.principals.JpsXmlUserImpl</class>
</member>
</members>
</app-role>
</app-roles>
<jazn-policy>
<grant>
<grantee>
<display-name>
View Orders
</display-name>
<principals>
<principal>
<type>
role
</type>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>admin</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.adf.share.security.authorization.RegionPermission</class>
<name>PURCHASE_ORDER_VIEW_DETAILS</name>
<actions>view</actions>
</permission>
</permissions>
</grant>
</jazn-policy>
</application>
</applications>
</policy-store>
The application policy store includes the values that you specified.
Note:
Clicking the title (default action URL) opens the Sonoma - Elites page. An additional
action link allows the user to e-mail the owner.
You can perform the following tasks to define search result actions:
Use the Search navigation tab of the overview editor in JDeveloper, shown in
Figure 293, to define actions for search results.
To define search result actions for Oracle Fusion Applications Search, you must
complete additional configuration tasks. For information, see Section 15.6.5, "How to
Use the Actionable Results API with Oracle Fusion Applications Search."
Use the view object name and action name to look up the action definition.
2.
Use the primary key values to query for the row in the database.
Attribute values are obtained from search attributes. If an action refers to unstored
attributes, primary keys are used to obtain their values during redirect.
3.
4.
For each task parameter, evaluate the parameter value by passing the field and
value map and the expression into an evaluator, add it to the resolved
parameters list, then construct the URL using the same
ControllerContext.getTaskFlowURL API.
5.
Evaluate the parameterized URL by passing the field/value map and the
expression into an evaluator.
Click the Add icon in the Search Result Actions table header to open the Search
Result Actions dialog, shown in Figure 2910.
Figure 2910
3.
Note:
4.
From the Action Type dropdown menu, select Task (default) to specify a task to
be performed on the search result or select URL to specify a web page.
Only bounded task flows can be launched through the URL
mechanism.
Note:
5.
If you chose URL for Action Type in Step 4, then in the Action Target field,
define the action by entering a Groovy expression that generates the URL that
is invoked when the user clicks the action.
For URLs that point to an external site, you must configure the target
expression to generate a fully qualified URL, which includes both the protocol
(such as http://) and the host name (for example, example.com).
For internal link URLs that point to pages on the same application from which
the search is performed, configure the target expression to generate a relative
URL (for example, "/EmployeeDetailPage?empId=" + EmpId). Relative URLs
are invoked relative to the current host name and port number. This allows for
the action to succeed on any application server on which the search is running.
You can also click the Edit icon next to the Action Target field to use the Edit
Expression Editor dialog for entering the Groovy expression. For more
information, see Section 29.2.1, "How to Use Groovy Expressions in ECSF."
The URL must be no longer than 32,000 in length. You can reference only
stored attributes. For example, you can enter
"http://www.example.com/search?hl=en&q=" + SRCompanyZip.
Caution: Using unstored attributes results in an exception at query
time when the action is resolved. Also, do not refer to child
documents when defining the action definition.
6.
If you chose Task for Action Type in Step 4, then leave the Action Target field
blank. However, you must define the TaskName and TaskFile properties in the
Action definition. For information, see Section 29.4.1.4, "Defining Properties
for Bounded Task Flows."
In the Title field, enter a Groovy expression to be evaluated to a string for the
desired display title of the action as you would like it to appear on the Search
Results page. For more information, see Section 29.2.1, "How to Use Groovy
Expressions in ECSF."
You can also click the Edit icon next to the Title field to use the Edit Expression
Editor dialog for entering a Groovy expression.
7.
Select the Default Action checkbox to make this action the default action to be
performed on the search results.
Note:
8.
For tasks, enter a parameter name in the Parameter Name field and its
corresponding value in the Value field, then click Add.
Enter parameter values as Groovy expressions. You can use only stored attributes
(for example, SRNumber) as parameters.
Note: Using unstored attributes results in an exception at query time
when the action is resolved. Also, do not refer to child documents
when defining the action definition.
You can also click the Edit icon next to the Value field to use the Edit Expression
Editor dialog for entering a Groovy expression.
Minimally, the TaskName and TaskFile parameters must be provided. The value of
the TaskName parameter is a Groovy expression that returns the name of the task
(that is, a name surrounded by double quotation marks). The value of the
TaskFile parameter is a Groovy expression that returns the name of the task
definition file. Values of other parameters are Groovy expressions that return the
desired value. These parameters are passed into the task. For more information,
see Section 29.2.1, "How to Use Groovy Expressions in ECSF."
9.
To update an existing parameter, select the desired parameter in the table, change
its value, then click Update.
10. To delete an existing parameter, select the desired parameter in the table and click
Delete.
11. Click OK.
12. To create additional search result actions, repeat Steps 2 to 11.
13. Save the view object.
Open the task definition file, locate the <task-flow-definition> element, for
example, <task-flow-definition id='task-flow-definition'> and note the
value of the id attribute.
3.
Open the searchable object file and locate the TaskFile parameter, then edit the
value to reflect the location and filename of the task definition file, for example,
\WEB-INF\task-flow-definition.xml.
4.
Locate the TaskName parameter and edit the value to reflect the id attribute value
of the <task-flow-definition> element of the task definition file, for example,
'task-flow-definition'.
5.
Expand the Search Result Actions table header to expose the table of actions.
3.
Select the action you want to modify. This highlights the entire row.
4.
Click the Edit icon in the Search Result Actions table header to open the Search
Result Actions dialog, shown in Figure 2910.
The information of the action you selected is displayed.
5.
Make the necessary changes to the desired fields. For more information about the
fields, see Section 29.4.1.3, "Adding Search Result Actions."
You must recrawl the data if you reference a new attribute that
is marked as stored.
Note:
6.
Click OK.
7.
Expand the Search Result Actions table header to expose the table of actions.
3.
Select the action you want to delete. This highlights the entire row.
4.
Click the Delete (red X) icon in the Search Result Actions table header.
The action you selected on the Search navigation tab is removed from the table of
actions.
5.
Caution:
The search result actions you define during design time is parsed at runtime and
appear in a table on the search results page.
29.4.3 What You May Need to Know About Defining Search Result Actions
The Name, Action Type, Action Target, and Title fields are required fields. You must
input values for all three fields to save the action.
1.
Create a view object (base object) and identify the attributes you want to bind
to facets.
b.
Create a view object (LOV object) for each of the attributes you identified in
Step 1a to get a list of available values for the attributes.
c.
Create a view accessor on the base object for each LOV object to be used as a
facet, and assign each LOV object to its corresponding attribute.
d.
Define the facet hierarchy. Since the faceted navigation path is hierarchical,
you must form the structure so that the LOV objects form one facet definition.
For each LOV object to be used as child, create a bind variable and view
criteria.
While defining the facet hierarchy, you can constrain the LOV object by the
stored attribute.
2.
To illustrate the process of defining LOVs for facets, consider the following scenario:
You want to create facet relationships for the EmpView base object. EmpView contains
two stored attributes, StateID and CityID, on which you want to create facets. "City"
is the child facet of "State." The values shown in the "City" facet are constrained by the
value selected for "State." This scenario is used in the tasks listed in this section.
You can also configure stored transient attributes on the view object to define:
Related Links
The following document provides more information about the topic discussed in this
section:
For more information, see the "Working with List of Values (LOV) in View Object
Attributes" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
Note:
3.
In the Edit Attribute dialog for the stored attribute (StateID), select List of Values
and select Enable List of Values.
4.
5.
Specify which attribute on the view object contains the display value.
6.
In the Attribute Editor, select List of Values and select Edit List UI Hints.
In the List UI Hints dialog, add a child attribute to display. The first attribute
value is used as the display value.
3.
On the View Criteria page of the View Criteria Editor dialog, click the Add
Item button.
In the Criteria Items panel, define the criteria as follows:
Attribute: ParStateId
Operator: equal to
Parameter: StId
Usage: Required
Click the Edit button to edit the view accessor (CitiesView1) for CitiesView on
EmpView.
In the Edit View Accessor dialog, select the view criteria (CitiesViewCriteria) in
the Available list and click the Move icon to add it to the Selected list, as shown in
Figure 2911.
Figure 2911
4.
Map the StId bind variable on CitiesView to the StateId attribute of EmpView.
5.
Note:
You can define facets by creating search facets, modifying search facets, deleting root
search facets, and deleting child search facets. Use the Search navigation tab of the
overview editor in JDeveloper, shown in Figure 293, to define facets for faceted
navigation.
You can create search facets to specify the root facet, facet name, an attribute, and child
facets. Use the Facets dialog to add search facets.
Click the Add icon in the Facets table header to open the Facets dialog, shown in
Figure 2912.
Figure 2912
3.
Facets Dialog
In the Facet field, enter a valid facet name for the root facet.
No two facets can share the same name at the searchable object
level. This comparison is case insensitive.
Note:
4.
Click the icon next to the Facet Display Name field to open and use the Select Text
Resource dialog for selecting a text resource from an existing resource bundle, or
for creating and selecting a new text resource. For more information, see
Section 29.4.4.5, "Using the Select Text Resource Dialog to Select a Matching Text
Resource" or Section 29.4.4.6, "Using the Select Text Resource Dialog to Create and
Select a New Text Resource."
Note:
You can use resource bundles to localize ECSF. For information, see Section 33.10,
"Localizing ECSF Artifacts."
5.
From the Attribute Name dropdown menu, select a searchable attribute for the
root facet.
The Attribute Name dropdown menu lists only the searchable
attributes whose isStored property is set to true. For information, see
Section 29.2.6.1, "Making View Object Attributes Searchable."
Note:
No two facets can share the same attribute at the searchable object
level.
6.
7.
Note:
8.
Select an attribute for the child facet from the Attribute Name dropdown menu.
Note:
9.
Identify the attributes you want to bind to facets from the child VO and create
transient attributes on the current VO for each child attribute. (This assumes that
you already established a relationship between parent and child VOs using View
Link Accessors.)
3.
Create a view object (LOV object) for each of the attributes you identified to create
a list of available values for the attributes.
4.
Create a view accessor on the base object for each LOV object to be used as a facet,
and assign each LOV object to its corresponding attribute.
5.
6.
For the transient attributes, select the corresponding child view attribute name
from the Override Source drop-down list in the Searchable Attributes popup. See
Figure 297.
7.
29.4.4.5 Using the Select Text Resource Dialog to Select a Matching Text Resource
Use the Select Text Resource dialog to select a text resource from an existing resource
bundle.
To select a matching text resource:
1. From the Facets dialog, click the icon next to the Facet Display Name field to open
the Select Text Resource dialog.
2.
Note:
3.
Enter values in the Display Value, Key, and Description fields to narrow down
the list of matching text resources.
4.
Select the desired text resource in the Matching Text Resources table.
5.
Click Select. Click the Clear Selection button to clear your selection.
29.4.4.6 Using the Select Text Resource Dialog to Create and Select a New Text
Resource
Use the Select Text Resource dialog to create and select a new text resource.
To create and select a new text resource:
1. From the Facets dialog, click the icon next to the Facet Display Name field to open
the Select Text Resource dialog.
2.
Note:
3.
In the Display Value field, enter a string or any type of object to associate with the
key in the page's resource bundle.
4.
In the Key field, enter a string to uniquely identify a locale-specific object in the
resource bundle.
5.
In the Description field, enter a description of any length for the key and value
pair.
6.
Expand the Facets table header to expose the table of root facets.
3.
Select the root facet you want to modify. This highlights the entire row.
4.
Click the Edit icon in the Facets table header to open the Facets dialog, shown in
Figure 2912.
5.
6.
Change the values of the Facet Attributes fields. For more information about
the fields, see Section 29.4.4.3, "Creating Search Facets."
Add child facets. For more information, see Section 29.4.4.3, "Creating Search
Facets."
Delete child facets. For more information, see Section 29.4.4.9, "Deleting Child
Search Facets."
7.
Click OK.
8.
Expand the Facets table header to expose the table of root facets.
3.
Select the root facet you want to remove. This highlights the entire row.
4.
5.
Expand the Facets table header to expose the table of root facets.
3.
Select the root facet you want to modify. This highlights the entire row.
4.
Click the Edit icon in the Facets table header to open the Facets dialog, shown in
Figure 2912.
5.
6.
Click Delete.
7.
Click Yes, when prompted with "Are you sure you want to delete the
facets?"
The facet you selected is removed from the tree.
8.
Click OK.
9.
For a date attribute, you can create a transient attribute named HireDate that
contains the following Groovy expression:
if (Hiredate.getYear() >= 80 && Hiredate.getYear() < 90) '80s'; else if
(Hiredate.getYear() >= 91 && Hiredate.getYear() < 100) '90s'; else '2000s';
2.
Define a static LOV with the range codes and display values.
3.
4.
1.
3.
4.
Caution:
29.4.6 What You May Need to Know About Implementing Faceted Navigation
Facets can only be defined on attributes in the parent or top-level view object because
only attributes on the parent or top-level view object can be created as index attributes
in the underlying Oracle SES index. For example, if you want to create an "address"
facet consisting of the following tree, Country > State > City > Zip Code, all four
attributes (country, state, city, zip code) must be view object attributes in the parent or
top-level view object. Attributes that are used for facets must exist on the parent view
object, not on a child view object linked to the parent through a view link. If any of the
information is in a child attribute, then the attribute must be joined into the parent
view object.
Since facets can filter against only a single search category, faceted navigation is not
supported with federated search.
oracle.ecsf.crawl.batch.size
oracle.ecsf.crawl.datafeed.size
oracle.ecsf.max.links.depth
oracle.ecsf.split.mode
oracle.ecsf.split.threshold
These properties, described in Table 321, can also be set as system parameters to
apply the values to all searchable objects. For information, see Section 32.2.4, "How to
Modify the Run Configuration of the View-Controller Project."
To configure customer properties for searchable objects:
1. In the Application Navigator, open the desired view object.
2.
3.
4.
Add property name and value pairs. For more information about the properties,
see Table 321.
<Properties>
<CustomProperties>
<Property
Name="oracle.ecsf.searchableobject.public"
Value="true"/>
</CustomProperties>
</Properties>
When this value is set to true, the Security attribute values for anonymous user
property of the data source deployed to Oracle SES from this searchable object is set to
the ACL value or values retrieved from the searchable object's plug-in class.
30
Configuring ECSF Security
30
Permission Policy
<grant>
<grantee>
<codesource>
<url>file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/oracle.ecsf/-</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.ecsf,keyName=*</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.JpsPermission</class>
<name>IdentityAssertion</name>
<actions>execute</actions>
</permission>
</permissions>
</grant>
Make sure that the policy migrates to the target Oracle WebLogic Server domain.
Related Links
The following document provides more information about the topic discussed in this
section:
For more information, see Oracle Fusion Middleware Application Security Guide.
FUSION_APPS_CRM_SES_CRAWL_APPID
FUSION_APPS_FSCM_SES_CRAWL_APPID
FUSION_APPS_HCM_SES_CRAWL_APPID
FUSION_APPS_CRM_ECSF_SEARCH_APPID
FUSION_APPS_FSCM_ECSF_SEARCH_APPID
FUSION_APPS_HCM_ECSF_SEARCH_APPID
FUSION_APPS_ECSF_SES_ADMIN_APPID
Each pair of application identities, one pair for each product family, are used to
integrate ECSF with Oracle Fusion Applications. The Credential Store Framework
(CSF) stores the credentials to access the identities.
However, if you are developing applications on the Integrated WebLogic Server
instance, then you must manually configure the application identities to integrate
Note:
2.
3.
Make sure the permission policies for the identity store and the JPS
IdentityAssertion API are added to the jazn-data.xml file.
This creates entries in the cwallet with the correct map/key pairs for the users.
<grant>
<grantee>
<codesource>
<url>file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/oracle.ecsf/-</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.ecsf,keyName=*</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.wsm.security,keyName=FUSION_APPS_FSCM_ECSF_
SEARCH_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.wsm.security,keyName=FUSION_APPS_HCM_ECSF_
SEARCH_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.wsm.security,keyName=FUSION_APPS_CRM_ECSF_
SEARCH_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.apps.security,keyName=FUSION_APPS_CRM_SES_
CRAWL_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.apps.security,keyName=FUSION_APPS_HCM_SES_
CRAWL_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.apps.security,keyName=FUSION_APPS_FSCM_SES_
CRAWL_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=oracle.apps.security,keyName=FUSION_APPS_ECSF_SES_
ADMIN_APPID-KEY</name>
<actions>*</actions>
</permission>
<permission>
<class>oracle.security.jps.JpsPermission</class>
<name>IdentityAssertion</name>
<actions>execute</actions>
</permission>
</permissions>
</grant>
The permissions allow ECSF to read and write credential store entries that are not part
of the oracle.ecsf map.
<permission>
<class>oracle.adf.share.security.authorization.MethodPermission</class>
<name>ECSF_All_Services</name>
<actions>execute</actions>
</permission>
The grantee should be the users or roles that you want to authorize to use the search
feeds, as shown in Example 304.
Example 304
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.service.policystore.ApplicationRole</class>
<name>AuthorizedUserRole</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.adf.share.security.authorization.MethodPermission</class>
<name>ECSF_All_Services</name>
<actions>execute</actions>
</permission>
</permissions>
</grant>
The example shows how jazn-data.xml is modified to grant the permission to a role.
Create a separate user and add it to the Operators group to assign that user the
Oracle WebLogic Server security role of Operator to obtain execute privileges on
ECSF MBean operations.
3.
Create an ECSF query proxy user. For more information, see the "Managing Search
with Oracle Enterprise Crawl and Search Framework" chapter in the Oracle Fusion
Applications Administrator's Guide.
4.
Note:
31
Validating and Testing Search Metadata
31
Table and alias of the primary table exists in the view object.
Search attributes are valid, and all the search attributes exist in the view object.
Set up ECSF security. For information, see Chapter 30, "Configuring ECSF
Security."
3.
Create searchable objects. For information, see Chapter 29, "Creating Searchable
Objects."
4.
Run the ECSF feed servlet. For information, see Section 31.3.1, "How to Run the
ECSF Feed Servlet."
<servlet>
<servlet-name>SearchFeedServlet</servlet-name>
<servlet-class>oracle.ecsf.feed.SearchFeedServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>SearchFeedServlet</servlet-name>
<url-pattern>/searchfeedservlet/*</url-pattern>
</servlet-mapping>
<filter-mapping>
<filter-name>JpsFilter</filter-name>
<servlet-name>SearchFeedServlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
<dispatcher>INCLUDE</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>ServletADFFilter</filter-name>
<servlet-name>SearchFeedServlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
2.
3.
4.
Note:
You can click the Terminate (red square) button to stop the ECSF feed servlet.
For example, if JDeveloper is running on the Linux server wlsserver.com, and the
fully qualified package path of EmpVO is oracle.ecsf.EmpVO (case-sensitive), the
resulting Config Feed URL would be
http://wlsserver.com:8988/approot/searchfeedservlet/oracle.ecsf.EmpVO/C
onfigFeed.
2.
Example 312
- <rsscrawler xmlns="http://xmlns.example.com/search/rsscrawlerconfig">
<feedLocation>http://localhost:8988/approot/searchfeedservlet/runtime.EmpView/Cont
rolFeed</feedLocation>
<feedType>controlFeed</feedType>
<errorFeedLocation>/tmp</errorFeedLocation>
<securityType>attributeBased</securityType>
<securityAttribute name="DEPTNO" grant="true" />
</rsscrawler>
If the RSS feed does not appear, then either the runtime server is not set up
properly or the path to the view object is incorrect. The URL is case-sensitive.
If no attribute exists for the <securityAttribute> tag, you must mark at least one
searchable attribute as a Secure Attribute. For information, see Section 29.2.3,
"How to Make View Objects Searchable."
3.
After adding the metadata, make sure to restart the Integrated WebLogic Server
instance.
Change the feed URL by replacing localhost with the server name of the IP
address.
For example, if JDeveloper is running on the Linux server example.com, the
resulting Control Feed URL would be
http://example.com:8988/approot/searchfeedservlet/runtime.EmpView/Contr
olFeed.
3.
4.
Example 313
3.
Example 314
- <item>
- <link>
- <![CDATA[
http://ecsf.example.com/search/runtime.EmpView?EMPNO=7839
]]>
</link>
- <title>
- <![CDATA[
KING: 5000
]]>
</title>
- <itemDesc xmlns="http://xmlns.example.com/orarss">
- <documentMetadata>
- <accessURL>
- <![CDATA[
http://example.com/EmpNo=7839
]]>
</accessURL>
- <keywords>
- <![CDATA[
Employee department job salary data KING
]]>
</keywords>
- <summary>
- <![CDATA[
KING 1981-11-17T00:00:00.000Z
]]>
</summary>
<language>en</language>
- <docAttr name="ENAME">
- <![CDATA[
KING
]]>
</docAttr>
- <docAttr name="CITY_ID">
- <![CDATA[
2
]]>
</docAttr>
- <docAttr name="STATE_ID">
- <![CDATA[
1
]]>
</docAttr>
</documentMetadata>
- <documentAcl>
<securityAttr name="DEPTNO">NO_SECURITY</securityAttr>
</documentAcl>
- <documentInfo>
<status>STATUS_OK_FOR_INDEX</status>
</documentInfo>
- <documentContent>
- <content type="text/plain">
- <![CDATA[
Identification Number: 10.7839
]]>
</content>
- <contentLink type="text/html">
- <![CDATA[
http://example.com:8988/approot/searchfeedservlet/runtime.EmpView/Attachment?schem
aName=null&tableName=runtime.EmpView&columnName=Attachment&keyCount=1&keyName0=EMP
NO&keyValue0=7839
]]>
</contentLink>
</documentContent>
</itemDesc>
</item>
3.
Paste the resulting URL in your browser and refresh the web page.
32
Deploying and Crawling Searchable Objects
32
This chapter describes how to deploy searchable objects to the Oracle Enterprise Crawl
and Search Framework (ECSF) application.
This chapter includes the following sections:
2.
Create an application.
3.
If desired, change the application name and context root of the view-controller
project.
4.
5.
Add the ECSF Runtime Server library and the required Java archive (JAR) files to
Model and ViewController.
32.2.1 How to Deploy the ECSF Shared Library to Oracle WebLogic Server
The ECSF shared library eliminates the need for ECSF libraries to be packaged into
each application. Instead, applications that depend on ECSF libraries can reference the
ECSF shared library that is deployed to the Oracle WebLogic Server. The ECSF shared
library contains the following Java archive (JAR) files:
ecsf.jar
search_admin_wsclient.jar
search_client.jar
ses_admin_ows_proxy.jar
soap.jar
The ECSF extension in JDeveloper controls the reference to the ECSF shared library
that is deployed to Oracle WebLogic Server. When you add the ECSF Runtime Server
or ECSF Client library to a project, the reference to the ECSF shared library, shown in
Example 321, is automatically added to the WebLogic deployment descriptor file
(weblogic-application.xml).
Example 321
<library-ref>
<library-name>oracle.ecsf</library-name>
</library-ref>
On the Summary of Data Sources page, click the data source name SearchDB.
3.
4.
On the Connection Properties page, replace the default values for both the
Connection URL and Properties boxes with valid connection values.
5.
Click Save.
32.2.1.2 Deploying the ECSF Shared Library to the Standalone WebLogic Server
Instance
You must manually deploy the ECSF shared library to the standalone WebLogic Server
instance. The ECSF shared library creates a SearchDB data source in the Oracle
WebLogic Server domain. During the process of deploying the ECSF shared library,
you must provide the database connection information for the SearchDB data source,
which is deployed with the shared library.
To deploy the ECSF shared library to the standalone WebLogic Server instance:
1. Extend the Oracle WebLogic Server domain by using the Oracle Fusion
Middleware Configuration Wizard (execute $WL_HOME/common/bin/config.sh).
2.
3.
Configure the SearchDB data source by providing valid values for the following
fields:
4.
DBMS Host
DBMS Port
SID
Username
User Password
When a new version of the ECSF shared library is available, you must redeploy it.
a.
b.
Note:
In the New Gallery dialog, select the General category and select Applications.
3.
Select the Fusion Web Application (ADF) template and click OK.
4.
In the Create Fusion Web Application (ADF) dialog, enter a name and location for
the application in the Application Name and Directory fields.
5.
6.
Click Finish.
32.2.3 How to Change the Application Name and Context Root of the View-Controller
Project
If desired, change the application name and context root of the view-controller project
by modifying the Java EE application settings.
To change the Java EE Application settings:
1. In the Application Navigator, right-click the view-controller project and select
Project Properties.
2.
In the Project Properties dialog, select Java EE Application in the left panel.
3.
Change the value of the Java EE Web Application Name field to EcsfApp.
4.
Change the value of the Java EE Web Context Root field to approot.
5.
Click OK.
The view-controller application name is set to EcsfApp, and the context root is set
to approot.
3.
Select Default in the Run Configurations list, then click the Edit button.
4.
In the Edit Run Configuration dialog, select Launch Settings in the left panel.
5.
If desired, enter additional parameter values in the Java Options field. Table 321
lists the ECSF system parameters. Separate each parameter with a space.
Note:
Set the parameters using the Java System Properties. For example,
add -Dproperty=value when starting the JVM.
If a property is found in both the ecsf.properties file and the Java
System Properties, the value in the Java System Properties will be
used. In other words, the Java System Properties have higher
precedence.
These parameters values can also be specified at the searchable object level. For
information, see Section 29.5, "Configuring Custom Properties for Searchable
Objects."
Table 321
Parameter Name
Description
oracle.ecsf.admin.datao
bject.synchinterval
oracle.ecsf.connection.
name
oracle.ecsf.context
oracle.ecsf.crawl.batch
.size
-Doracle.ecsf.crawl.batch.si Defines the data batch size within a data feed. The
ze=n
value determines the number of database rows (n)
that are processed per batch within a data feed.
The default size is 200.
oracle.ecsf.crawl.dataf
eed.size
-Doracle.ecsf.crawl.datafeed Defines the size for the data feed. The value
.size=n
determines the number of documents (n) per data
feed. The default size is 1000.
oracle.ecsf.datasource.
name
oracle.ecsf.datesplitte
r.mode
oracle.ecsf.maxfacetdef
values
oracle.ecsf.max.links.d
epth
oracle.ecsf.service.ws.
timeout
oracle.ecsf.split.mode
-Doracle.ecsf.split.mode=db
Description
oracle.ecsf.split.thres
hold
oracle.ecsf.cache.expir
eseconds
oracle.ecsf.cache.expir
eseconds.ObjectCache
oracle.ecsf.cache.expir
eseconds.FacetDefsCache
oracle.ecsf.cache.expir
eseconds.GroupCache
oracle.ecsf.cache.expir
eseconds.GroupsCache
oracle.ecsf.cache.expir
eseconds.EngineInstance
sCache
6.
Click OK.
The run configuration is set to debug mode, and other ECSF system parameters
are set.
32.2.5 How to Add the ECSF Runtime Server Library and Required Java Archive Files
to the Model and View-Controller Projects
You must add the ECSF Runtime Server library and one of the following sets of
required Java archive (JAR) files to both the Model and view-controller projects:
oracle/jdeveloper/soa/modules/oracle.soa.fabric_
11.1.1/fabric-runtime.jar
oracle/wlserver_10.3/server/lib/wls-api.jar
oracle/jdeveloper/webservices/lib/soap.jar
Make sure that cwallet.sso and jazn-data.xml are part of
your application before adding the Java archive (JAR) files. You can do
so through the Application Navigator by navigating to Application
Resources, then Descriptors, then META-INF. The cwallet.sso file is
created when you create a database connection. To create
jazn-data.xml, right-click the META-INF folder select New Oracle
Deployment Descriptor, select jazn-data.xml, and click Finish.
Caution:
You do not need to add the Java archive (JAR) files that are included in a library that
you have already added.
Note:
3.
Use the Oracle SES administration user interface to inspect whether the crawls
were successful and verify how much data is crawled.
33
Advanced Topics for ECSF
33
This chapter provides information on advanced topics for Oracle Enterprise Crawl and
Search Framework (ECSF), including enabling and managing search, and
troubleshooting ECSF.
This chapter includes the following sections:
Section 33.9, "Using the External ECSF Web Service for Integration"
1.
Create a view link between the searchable object and the AttachmentsVO to make
AttachmentsVO a child of the searchable object.
When you design your view object for search, make sure that
you configure view links to generate only the Destination Accessor
and not the Source Accessor.
Note:
3.
On the searchable object, define a view link accessor that points to the view link.
For information, see Section 19.3.2, "How to Create Attachment View Links."
Tags are single words stored as space-separated strings in the application database and
are retrieved by using a view object called TagSVO (service view object). You must
create a view link to make TagSVO a child object. At crawl time, the view link is used to
locate TagSVO. Figure 331 illustrates crawl time with tags.
Purchase Order 123 has two tags, Computer and Dell. ECSF adds the tags for each
record of the searchable object to the indexable document before the document is sent
to Oracle SES for indexing. ECSF also creates a reserved attribute (of type string) called
ECSF_TAGS to store tags in Oracle SES.
At query time, users can specify tag values as keywords or as filters. When tag values
are input as keywords, the tag value is treated as a query string and returns results
that include the objects with the specified tag. When tag values are used as filters, the
tags are added to QueryMetaData and the query is run with filters on ECSF_TAGS. Only
the objects with the specified tags are returned. Figure 332 and Figure 333 illustrates
the difference between query time without a tag and query time with a tag.
Note:
In Figure 332, the indexed document for Purchase Order 123 contains two tags,
Computer and Dell. The query on John returns all the documents that contain John.
The results display the title, body, and all tags for the documents.
In Figure 333, query on the Purchase Order John and tag Dell returns only the
documents that contain John AND the Dell tag. The results display the title, body, and
all tags for the documents. If both Dell and Computer were specified as tags, then the
query would return only the documents that contain both tags (that is, Dell AND
Computer). You cannot specify tags using the OR condition (that is, Dell OR Computer),
so the query cannot return documents that contain either the Dell tag or the Computer
tag.
Enabling search on WebCenter Portal tags allows tags to be added to indexable
documents and stored in the reserved attribute called ECSF_TAGS in Oracle SES. Tags
can then be used as keywords or filters for search.
Perform the following tasks to enable search on WebCenter Portal tags:
1.
Create a view link between the searchable object and the TagSVO. For information,
see Section 15.6.4, "How to Implement Tags in Oracle Fusion Applications Search."
When you design your view object for search, make sure that
you configure view links to generate only the Destination Accessor
and not the Source Accessor.
Note:
The view link must use the accessor name tagSVO so that the search extension can
navigate to the child object when it crawls.
2.
3.
You can also perform the following tasks to customize search on WebCenter Portal
tags:
1.
2.
2.
You can implement code, such as the sample code shown in Example 331, in the
search extension to extend DefaultSearchPlugin.
Example 331
This extension adds three tags (Black, White, and Stripes) to a user named Zebra.
Adding tags for querying forces the query to find results where indexed documents
contain the added tags. When more than one tag is added, the resulting documents
must contain both tags. Documents containing only one of the tags are not returned.
Query SES retrieves tags all the time. The searcher adds tags to IndexedDocument by
using setTags. In case of null in the attribute, no tags are added.
IndexedDocument.getTags returns all the tags in the document.
}
}
protected List populate(SearchContext ctx)
{
List nextList = new ArrayList();
//the following code marks Zebra has been changed
PrimaryKey pk = new PrimaryKey();
Pk.put("ENAME", "Zebra");
NextList.add(pk);
setDone(true); //tells ECSF there are no more
return nextList;
}
}
Note:
Note:
A searchable object holds metadata about the source system. It can be either an Oracle
ADF view object with ECSF annotation or a class that extends
oracle.ecsf.meta.SearchableObject. For tree structure-based source systems, the
searchable object is not view object-based, so ECSF does not load the view object.
Instead, it loads a Java class that extends and implements the searchable object. When
requested with a ConfigFeed URL, ECSF identifies the searchable object that holds the
search metadata required by ECSF. Non-view object-based searchable objects can be
grouped into search categories. Figure 334 illustrates the data flow for search on tree
structure-based source systems.
Figure 334 Data Flow for Search Using ECSF Tree Crawler
The integration of ECSF with the source system allows an Oracle SES instance to crawl
the source system data. The Source System DataNode, which is exposed to the ECSF
tree crawler, formulates the data structure and pulls data from the source system
server using web services. ECSF converts the tree nodes into documents that Oracle
SES receives through RSS feeds and indexes. The source system implements a security
service. When data from the source system is indexed in the Oracle SES, it is guarded
against access by the security service.
A security extension is needed to implement source and document-level security. A
searchable object has a method of getting a search extension instance based on the
metadata. To associate a search extension with a searchable object, configure it from
the Search navigation tab of the overview editor in JDeveloper. For more information,
see Section 29.2.3, "How to Make View Objects Searchable."
ECSF also extends its attachment implementation to enable the implementer to open
the stream for data pulling attachments that are associated with a particular node. For
more information, see Section 33.2, "Enabling Search on Fusion File Attachments."
Enable search on tree structure-based source systems by:
1.
2.
3.
2.
3.
4.
Implement security.
5.
6.
7.
package oracle.ecsf.test.tree;
import oracle.ecsf.data.tree.SearchableTreeObject;
public class SearchableTreeDirectory extends SearchableTreeObject {
//override the security plug to be used
public void initializeConfig() {
setPlugInName(SecurityPlugin.class.getName());
//add a custom attribute
//see processNode method where you must set attribute value
//for this attribute for the indexable document
DocumentDefinition docdef = this.getDocument();
FieldDefinitionImpl field = new FieldDefinitionImpl("CUSTOM_ATTR");
field.setBinding("CUSTOM_ATTR");
//this flag indicates that this attribute be stored in SES
field.setStored(true);
docdef.addField(field);
}
//override the crawlable factory to be used
package oracle.ecsf.data.tree;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
import java.util.Date;
import oracle.ecsf.IndexableDocument;
import oracle.ecsf.meta.PrimaryKey;
import oracle.ecsf.data.tree.CrawlableTreeNode;
public class CrawlableTreeNodeImpl extends CrawlableTreeNode {
String[] filesToHandle=new String[]{"java", "xml"};
private File file;
//Creates a node with a fully qualified name.
public CrawlableTreeNodeImpl(String name) {
super(name);
{
super.init();
if (!isLeaf())
{
File[] files = file.listFiles();
if (files != null)
{
for (int i = 0; i < files.length; i++)
{
addChildNode(new CrawlableTreeNodeImpl(files[i].getAbsolutePath()));
}
}
}
}
private static boolean isLink(File file) {
try {
if (!file.exists()) {
return true;
} else {
String cnnpath = file.getCanonicalPath();
String abspath = file.getAbsolutePath();
return !abspath.equals(cnnpath);
}
} catch (IOException ex) {
System.err.println(ex);
return true;
}
}
public boolean isLeaf() {
return file == null || !file.isDirectory() || isLink(file);
}
}
In the processNode method, you must extract any metadata information about the
document (for example, setTitle, setKeyword, setContent) and populate the
indexable document that is passed in. You can also add any custom attributes to the
indexable documents, such as the isLeaf method that determines whether a node is a
folder or a document. This method is used by the crawlable factory to determine how
to traverse the tree.
package oracle.ecsf.data.tree;
import oracle.ecsf.meta.SearchableObject;
public class FileTreeCrawler extends AbstractTreeWalker {
//
//The application determine the root path.
//
String root="/home/cbrown";
/**
*Constructs a CrawlableFactory from a searchable object.
*/
public FileTreeCrawler()
{
super();
}
public FileTreeCrawler(SearchableObject searchableObject)
{
super(searchableObject);
}
//
//Creates root node
//
public CrawlableTreeNode createCrawlable() {
return new CrawlableTreeNodeImpl(root);
}
//
//Creates a node for a given path
//if you cannot construct the path.
//
public CrawlableTreeNode createCrawlable(String path) {
return new CrawlableTreeNodeImpl(path);
}
//Tests if a node is crawlable
protected boolean isIndexable(CrawlableTreeNode node) {
CrawlableTreeNodeImpl fNode = (CrawlableTreeNodeImpl) node;
return fNode.isIndexable();
}
}
ECSF uses the generic term ACL to describe how Oracle SES
and ECSF pass security information and perform security checks by
using the information described in the ACL.
Note:
ECSF is secured by a plugable security service, which is called when users try to
search the indexed content. By default, ECSF provides an implementation based on
Oracle Platform Security for Java. It is mainly used for authenticating and authorizing
users into the system. However, if you have a non-Oracle security provider, or you
want to use your own security implementation, you must extend the ECSF security
service. Example 337 illustrates the skeleton of a security extension.
Example 337
package oracle.ecsf.data.tree;
import oracle.ecsf.SearchContext;
import oracle.ecsf.SecurityService;
import oracle.ecsf.util.SecurityServiceFactory;
public class SecurityServiceImpl implements SecurityService{
public String[] listSupportedFormats() {
return new String[]{"BIEE"};
}
public String authenticate(SearchContext ctx, String userName, String
password, String format) {
return userName;
}
public String isUserValid(SearchContext ctx, String userName, String format) {
return userName;
}
public String[] getSecurityValues(SearchContext ctx, String userName, String
attrName, String objectId) {
//Get keys for an attribute.
return new String[]{};
}
}
The security extension is a Java class that implements a securable interface. There are
five methods available. Example 338 illustrates the skeleton of such class.
Example 338
package oracle.ecsf.data.tree;
import
import
import
import
oracle.ecsf.IndexableDocument;
oracle.ecsf.SearchContext;
oracle.ecsf.SearchSecurityException;
oracle.ecsf.Securable;
}
//The keys to the ACL for the document for ctx.getUserName()
public String[] getSecurityKeys(SearchContext ctx) {
return new String[]{};
}
//The ACL for the document, hashed against an attribute
public String[] getSecureAttrAcl(SearchContext ctx, IndexableDocument doc, String
attributeName) {
return new String[]{};
}
//The keys to the ACL for the document for ctx.getUserName(), hashed agains an attribute
public String[] getSecureAttrKeys(SearchContext ctx, String attributeName) {
return new String[]{};
}
//Returns configuration parameters for the extension, not used often
public String[] getSecurableParams()
throws SearchSecurityException {
return new String[]{};
}
}
package oracle.ecsf.data.tree;
import
import
import
import
import
java.io.BufferedReader;
java.io.File;
java.io.FileReader;
java.io.IOException;
java.io.OutputStream;
import java.util.HashMap;
import java.util.Map;
import oracle.ecsf.Attachment;
import oracle.ecsf.SearchContext;
import oracle.ecsf.meta.PrimaryKey;
public class AttachmentImpl implements Attachment {
PrimaryKey primaryKey;
public AttachmentImpl() {
}
public AttachmentImpl(Map map) {
primaryKey = new PrimaryKey();
primaryKey.putAll(map);
}
public String getType() {
return "text/xml";
}
After you implement this class, you can add any number of attachments to an
indexable document in the processNode method of CrawlableTreeNode. The
attachment must contain enough information in its primary key for you to open the
attachment when requested by the read method, where you simply use the
information stored in the primary key to read the document and write to the output
stream passed to you.
3.
4.
<servlet-class>oracle.ecsf.feed.SearchFeedServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>SearchFeedServlet</servlet-name>
<url-pattern>/searchfeedservlet/*</url-pattern>
</servlet-mapping>
5.
6.
Configuration URL:
http://yourhost:port/appname/pathname/searchableObjectName/ConfigFe
ed
Password: password
2.
Password: password
b.
Provide a name.
3.
4.
5.
c.
d.
e.
Click Finish.
b.
c.
d.
e.
b.
c.
Select the Use Identity Plug-in checkbox for the authentication option.
(Optional) Include the Oracle SES client Java archive (JAR) in your class path, as
shown in Example 3311, to query Oracle SES through API.
Example 3311 Class Path with Oracle SES Client Java Archive
public SearchHits doSearch(String soName, String query, int pageSize, int page)
{
SearchHits searchHits = null;
String searchGroupName = GROUP_NAME;
long engineInstId = -1;
SearchContext searchContext = ContextFactory.getSearchContext();
QueryMetaData qmd = new QueryMetaDataImpl();
qmd.setQueryString(query);
qmd.setPageSize(pageSize);
qmd.setCurrentPage(page);
SearchGroup group = new SearchGroup(searchGroupName, searchGroupName, -1, null,
SearchContext.LOCAL);
SearchGroup[] groups = new SearchGroup[] { group };
qmd.setSearchGroups(groups);
SearchableGroup sg = MetaDataManager.getSearchableGroup(-1, searchGroupName);
sg.addSearchableObject(soName);
SearchableObject so = MetaDataManager.getSearchableObject(soName);
searchContext.setSearchableObject(so);
SearchEngine engine = SearchEngineManager.getSearchEngine(engineInstId);
try
{
Searcher searcher = engine.getSearcher(searchContext);
searchHits = searcher.search(searchContext, qmd);
}
catch (Throwable e)
{
return null;
}
return searchHits;
}
if (group.getName().equals(s))
{
return group;
}
}
return null;
}
public SearchableObject getSearchableObject(long engineId, String s)
{
SearchableObject so = loadSOFromClass(s);
if (so != null)
{
so.setSearchEngineInstanceId(engineId);
}
return so;
}
protected SearchableObject loadSOFromClass(String className)
{
try
{
if (className.equals(SearchableObject.class.getName()))
{
return null;
}
Class cls =
Thread.currentThread().getContextClassLoader().loadClass(className);
if (cls != null)
{
Object object = null;
try
{
object = cls.newInstance();
}
catch (InstantiationException e)
{
return null;
}
catch (IllegalAccessException e)
{
return null;
}
if (object instanceof SearchableObject)
{
//this is the only path a searchable object will be created
SearchableObject so = (SearchableObject)object;
so.setDocument(new VODocumentImpl("root"));
return so;
}
else
{
return null;
}
}
else
{
return null;
}
}
catch (ClassNotFoundException e)
{
return null;
}
}
public void reload()
{
//do nothing
}
private List<SearchableGroup> groups = null;
private List<MetaEngineInstance> engines= new ArrayList<MetaEngineInstance>();
}
oracle.ecsf.meta.AbstractDocumentDefinition;
oracle.ecsf.meta.DocumentDefinition;
oracle.ecsf.meta.FieldDefinitionImpl;
oracle.ecsf.meta.SearchableObject;
oracle.ecsf.util.ECSFLoggerFactory;
*/
public final void setDocument(AbstractDocumentDefinition document)
{
super.setDocument(document);
initDoc(document);
}
private void initDoc(AbstractDocumentDefinition documentDefintion)
{
FieldDefinitionImpl field = new FieldDefinitionImpl("Ename");
field.setBinding("ENAME");
field.setPrimaryKey(false);
field.setStored(true);
documentDefintion.addField(field);
field = new FieldDefinitionImpl("Empno");
field.setBinding("EMPNO");
field.setPrimaryKey(true);
field.setStored(true);
documentDefintion.addField(field);
field = new FieldDefinitionImpl(DocumentDefinition.ECSF_SO_NAME);
field.setBinding(DocumentDefinition.ECSF_SO_NAME);
field.setPrimaryKey(false);
field.setStored(true);
documentDefintion.addField(field);
}
}
map.put("SES_QUERY_PROXY_PASSWORD", "tiger");
map.put("SES_QUERY_SESSION_TIMEOUT", "10");
map.put("ECSF_DATA_SERVICE",
"http://wlsserver.com:7101/approot/searchfeedservlet/");
map.put("ECSF_SECURITY_USERNAME", "scott");
map.put("ECSF_SECURITY_PASSWORD", "tiger");
map.put("ECSF_SECURITY_SERVICE",
"http://wlsserver.com:7101/approot/searchfeedservlet/");
map.put("ECSF_REDIRECT_SERVICE",
"http://wlsserver.com:7101/approot/searchfeedservlet/");
return map;
}
//add search group and search object used for SESAdmin
public List<SearchableGroup> getSearchableGroups(long engineId)
{
if(searchGroups == null)
{
searchGroups = new ArrayList(super.getSearchableGroups(engineId));
SearchableGroup sgAdmin = new SearchableGroup(GROUP_NAME_ADMIN);
sgAdmin.setIsExternal(false);
sgAdmin.setEngineInstanceId(ENGINE_ID);
SearchableObject so = super.loadSOFromClass(OBJECT_NAME_ADMIN);
sgAdmin.addSearchableObject(so);
searchGroups.add(sgAdmin);
}
return searchGroups;
}
private List<SearchableGroup> searchGroups = null;
private static final long ENGINE_ID = -1L;
private static final String GROUP_NAME_ADMIN = "runtime.EmpViewAdminTest";
private static final String OBJECT_NAME_ADMIN = "runtime.EmpViewAdminTest";
}
RecentSearchManager Class
The RecentSearchManager will manage the creation, deletion and retrieval of
recent searches from the database.
SavedSearchManager Class
Advanced Topics for ECSF 33-27
* @return RecentSearch
* @throws SearchException
*/
public RecentSearch createRecentSearch(SearchContext ctx,
String searchDescription,
QueryMetaData queryDetails,
String callerCtx)
throws SearchException
/**
* Deletes the specified Recent Search from the database
*
* @param ctx - the SearchContext
* @param recentSearch - the Recent Search to delete
* @throws SearchException
*/
public void deleteRecentSearch(SearchContext ctx, SavedSearch savedSearch)
throws SearchException
/**
* Deletes all of the recent searches for the current user specified in the
SearchContext
*
* @param ctx - the SearchContext
* @throws SearchException
*/
public void deleteRecentSearchesForUser(SearchContext ctx)
throws SearchException
/**
* Deletes all of the recent searches for the current user specified
* in the SearchContext with the specified callerCtx
*
* @param ctx the - SearchContext
* @param callerCtx - the caller context
* @throws SearchException
*/
public void deleteRecentSearchesForUser(SearchContext ctx, String callerCtx)
throws SearchException
This property can be set using the Java -D option or the ecsf.properties file.
If the oracle.ecsf.recent.search.max.num property is set to an
invalid number or 0, recent searches are disabled and a message is
printed to the log.
Note:
This will maintain the constraint of having a unique name for each recent SavedSearch
record. The UI will want to display the keyword string as the Recent Search name. The
keyword string can be obtained from the SavedSearch dataobject using its
getKeywordSrchStr method:
String recentSearchDisplayName = recentSearch. getKeywordSrchStr();
The callerCtx passed into some of the RecentSearchManager methods is a column used
by the UI to tag searches. For example, the Global Search UI will only want to display
recent searches that were performed inside the Global Search UI, so the callerCtx will
be used when creating and retrieving searches.
Database Schema for Recent Searches
Recent Search uses the ECSF_SVSEARCH and ECSF_SVSEARCH_DETAILS database
tables. To support Recent Search, these schema changes have been made:
RecentSearch Dataobject
The RecentSeach and RecentSearchDetails dataobjects are used. A RecentSearch
dataobject is just like SavedSearch except for the details method:
/**
* Retrieve the RecentSearchDetails for this recent search.
*
* @return recent search details
*/
public RecentSearchDetails getRecentSearchDetails()
2.
Updating the application deployment profile with the Target Directory for
Searchable Objects
3.
4.
5.
6.
7.
8.
9.
33.6.1 How to Create the SearchDB Connection on Oracle WebLogic Server Instance
The Oracle WebLogic Server instance to which the application is deployed must have a
SearchDB connection. The application deployment descriptors are set so that the
application does not automatically generate and synchronize weblogic-jdbc.xml
descriptors during deployment. This setting prevents you from receiving the
deployment error No credential mapper entry found for password indirection
when you package or deploy from the command line or from Oracle JDeveloper.
Because of this, you must manually create the SearchDB connection on Oracle
WebLogic Server instance.
To create the SearchDB connection:
1. In the Domain Structure tree of the Oracle WebLogic Server Administration
Console, navigate to Services, then JDBC, then Data Sources.
2.
See if there is any data source with Java Naming and Directory Interface (JNDI)
value jdbc/SearchDBDS. If not, proceed to the next step.
3.
4.
On the Connection Properties page, complete the fields with the following values:
5.
Click Next, and complete the configuration according to your data source.
33.6.2 How to Update the Application Deployment Profile with the Target Directory for
Searchable Objects
All searchable objects and their dependencies must be packaged within the Search
application enterprise archive (EAR) file for each product family. You must set the
target directory for the Java archive (JAR) files containing the searchable objects and
their dependencies in the application deployment descriptor so that they are packaged
with the enterprise archive.
3.
From the Edit EAR Deployment Profile Properties menu navigate to File Groups
> VOLib > Contributors, click Add, and set the directory to point to {FULL_PATH_
TO_BUILD_FILE}/deploy/lib/, for example, /ade/view_
name/fusionapps/crm/deploy/lib.
This directory is empty, but during the pre-enterprise archive step in the build file
the directory becomes populated with all of the dependent Java archive (JAR) files.
Including this directory in the application deployment descriptor ensures that
these dependent Java archive (JAR) files are packaged with the enterprise archive.
4.
Click OK.
33.6.3 How to Update the Application to Reference the ECSF Service Shared Library
The ECSF Service shared library eliminates the need for ECSF libraries to be packaged
into the Search application for each product family. Instead, applications that depend
on ECSF libraries can reference the ECSF shared library that is deployed to the Oracle
WebLogic Server instance. The ECSF Service shared library contains the following Java
archive (JAR) files:
ecsf_MiddleTier.war
ecsf_MiddleTier.jar
ecsf_Common.jar
You must update the Oracle WebLogic Server deployment descriptor file
(weblogic-application.xml) by adding the reference to the ECSF Service shared
library (oracle.ecsf.service), as shown in Example 3317.
Example 3317 Reference to the ECSF Service Shared Library
<library-ref>
<library-name>oracle.ecsf.service</library-name>
</library-ref>
<library-context-root-override>
<context-root>searchservice</context-root>
<override-value>REPLACE _CONTEXT_ROOT</override-value>
</library-context-root-override>
Replace REPLACE _CONTEXT_ROOT with the context root that is desired for the Search
application's ECSF Service.
The ECSF Service shared library is automatically deployed to the Integrated WebLogic
Server instance by the ECSF extension in JDeveloper through the JDeveloper
Application Development Runtime Service (ADRS). However, you must manually
deploy the ECSF Service shared library to the standalone Oracle WebLogic Server.
Select the Libraries and Classpath category and click the Add Library button.
3.
In the Add Library dialog, select ECSF Runtime Server from the list of available
libraries.
4.
Click OK to save your selection and close the Add Library dialog.
3.
Select Default in the Run Configurations list, then click the Edit button.
4.
In the Edit Run Configuration dialog, select Launch Settings in the left panel.
5.
6.
Click OK.
3.
33.6.7 How to Update the Search Application with New Searchable Objects or
Dependencies
The Search application must be updated if there are new searchable objects to add to
the application or if any of the dependencies for existing searchable objects change.
If there are no new searchable objects but dependencies have changed, you only need
to run the dependentJar ant target and package and deploy the enterprise archive (for
information, see Section 33.6.6, "How to Package and Deploy the Search Application").
However, if you are adding new searchable objects to the application, then you must
add the new searchable objects to the Search application build file and run the
dependentJar ant target, then repackage and redeploy the enterprise archive (for
information, see Section 33.6.6, "How to Package and Deploy the Search Application").
2.
3.
4.
Updating connections.xml
Oracle WebLogic Scripting Tool updates the files directly on the server you specify, so
no redeployment is necessary.
Under serviceProviders:
<serviceProvider type="KEY_STORE" name="keystore.provider"
class="oracle.security.jps.internal.keystore.KeyStoreProvider">
</serviceProvider>
Under serviceInstances:
<serviceInstance name="keystore" provider="keystore.provider"
location="./default-keystore.jks">
<description>Default JPS Keystore Service</description>
<property name="keystore.type" value="JKS"/>
<property name="keystore.csf.map" value="oracle.wsm.security"/>
<property name="keystore.pass.csf.key" value="keystore-csf-key"/>
<property name="keystore.sig.csf.key" value="sign-csf-key"/>
<property name="keystore.enc.csf.key" value="enc-csf-key"/>
</serviceInstance>
The key (in this example, test.user) for the new entry is used in connections.xml.
<XmlRefAddr addrType="WebServiceConnection">
<Contents>
<wsconnection
description="http://localhost:7101/HcmSearchService/AppModuleSearchService?WSDL"
service="{/oracle/ecsf/service/query/common/}AppModuleSearchService">
<model name="{/oracle/ecsf/service/query/common/}AppModuleSearchService"
xmlns="http://example.com/ws/model">
<service name="{/oracle/ecsf/service/query/common/}AppModuleSearchService">
<port name="AppModuleSearchServiceSoapHttpPort"
binding="{/oracle/ecsf/service/query/common/}AppModuleSearchServiceSoapHttp">
<soap
addressUrl="http://localhost:7101/HcmSearchService/AppModuleSearchService"
xmlns="http://schemas.xmlsoap.org/wsdl/soap/"/>
</port>
</service>
</model>
</wsconnection>
</Contents>
</XmlRefAddr>
</RefAddresses>
</Reference>
<Reference name="{/oracle/ecsf/service/query/common/fscm/}SearchService"
className="oracle.adf.model.connection.webservice.impl.WebServiceConnectionImpl" xmlns="">
<Factory className="oracle.adf.model.connection.webservice.api.WebServiceConnectionFactory"/>
<RefAddresses>
<XmlRefAddr addrType="WebServiceConnection">
<Contents>
<wsconnection
description="http://localhost:7101/FscmSearchService/AppModuleSearchService?WSDL"
service="{/oracle/ecsf/service/query/common/}AppModuleSearchService">
<model name="{/oracle/ecsf/service/query/common/}AppModuleSearchService"
xmlns="http://example.com/ws/model">
<service name="{/oracle/ecsf/service/query/common/}AppModuleSearchService">
<port name="AppModuleSearchServiceSoapHttpPort"
binding="{/oracle/ecsf/service/query/common/}AppModuleSearchServiceSoapHttp">
<soap
addressUrl="http://localhost:7101/FscmSearchService/AppModuleSearchService"
xmlns="http://schemas.xmlsoap.org/wsdl/soap/"/>
</port>
</service>
</model>
</wsconnection>
</Contents>
</XmlRefAddr>
</RefAddresses>
</Reference>
Web service security must be enforced by policy at the domain or instance level by
configuration.
3.
Save.
4.
When the SearchContext scope is set to GLOBAL, the parameters defined for the remote
engine instance in the database are used to access metadata objects and perform query
related functions on the remote engine instance. For more information, see the
"Managing Search with Oracle Enterprise Crawl and Search Framework" chapter in
the Oracle Fusion Applications Administrator's Guide.
In the example, ECSF runtime gets the runtime.EmpView search category (search
group) from an engine instance.
Federation occurs on the client through the Searcher class. For each Oracle SES
instance, ECSF runtime groups the search categories belonging to an Oracle SES
instance and creates a federation node for it. Separate queries are issued in separate
threads for each Oracle SES instance. The results from these queries are merged by
ECSF runtime and returned to the user.
You cannot federate both Oracle SES instances and ECSF
service components in the same query. ECSF runtime can only create
federation nodes for either each Oracle SES instance (for federated
Oracle SES) or each ECSF service component (for federated search).
Note:
Example 3322 illustrates how you can integrate federation across Oracle SES
instances.
Example 3322 Sample API for Integrating Federated Oracle SES
SearchContext ctx = ContextFactory.getSearchContext();
ctx.setScope(SearchContext.LOCAL);
SearchGroup[] sgs =
new SearchGroup[] { new SearchGroup("runtime.EmpView", "runtime.EmpView", 1),
new SearchGroup("runtime.EmpView", "runtime.EmpView", 17) };
queryMetaData.setSearchGroups(sgs);
try
{
searchHits = searchCtrl.runQuery(ctx, queryMetaData);
}
catch (Exception e)
{
bException = true;
}
In the example, two Oracle SES search engine instances are defined.
IndexableDocument.DELETE
IndexableDocument.UPDATE
IndexableDocument.INSERT
Method
Description
getSavedSearch(String userName,
String savedSearchRequest)
getSavedSearches(String userName,
String savedSearchRequest)
deleteSearch(String userName,
String savedSearchRequest)
getSavedSearchDetails(String
userName, String
savedSearchRequest)
getEngineInstances(String userName,
String engineInstanceRequest)
<wsdl:message name="AppModuleSearchService_saveSearch">
<wsdl:part name="parameters" element="types:saveSearch"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_saveSearchResponse">
<wsdl:part name="parameters" element="types:saveSearchResponse"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getSavedSearches">
<wsdl:part name="parameters" element="types:getSavedSearches"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getSavedSearchesResponse">
<wsdl:part name="parameters" element="types:getSavedSearchesResponse"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getSavedSearchDetails">
<wsdl:part name="parameters" element="types:getSavedSearchDetails"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getSavedSearchDetailsResponse">
<wsdl:part name="parameters"
element="types:getSavedSearchDetailsResponse"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getSavedSearch">
<wsdl:part name="parameters" element="types:getSavedSearch"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getSavedSearchResponse">
<wsdl:part name="parameters" element="types:getSavedSearchResponse"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getEngineInstances">
<wsdl:part name="parameters" element="types:getEngineInstances"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getEngineInstancesResponse">
<wsdl:part name="parameters" element="types:getEngineInstancesResponse"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getDisplayName">
<wsdl:part name="parameters" element="types:getDisplayName"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_getDisplayNameResponse">
<wsdl:part name="parameters" element="types:getDisplayNameResponse"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_deleteSearch">
<wsdl:part name="parameters" element="types:deleteSearch"/>
</wsdl:message>
<wsdl:message name="AppModuleSearchService_deleteSearchResponse">
<wsdl:part name="parameters" element="types:deleteSearchResponse"/>
</wsdl:message>
<wsdl:portType name="AppModuleSearchService">
<wsdl:documentation/>
<wsdl:operation name="search">
<wsdl:input message="tns:AppModuleSearchService_search"/>
<wsdl:output message="tns:AppModuleSearchService_searchResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="saveSearch">
<wsdl:input message="tns:AppModuleSearchService_saveSearch"/>
<wsdl:output message="tns:AppModuleSearchService_saveSearchResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="getSavedSearches">
<wsdl:input message="tns:AppModuleSearchService_getSavedSearches"/>
<wsdl:output message="tns:AppModuleSearchService_
getSavedSearchesResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="getSavedSearchDetails">
<wsdl:input message="tns:AppModuleSearchService_
getSavedSearchDetails"/>
<wsdl:output message="tns:AppModuleSearchService_
getSavedSearchDetailsResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="getSavedSearch">
<wsdl:input message="tns:AppModuleSearchService_getSavedSearch"/>
<wsdl:output message="tns:AppModuleSearchService_
getSavedSearchResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="getEngineInstances">
<wsdl:input message="tns:AppModuleSearchService_getEngineInstances"/>
<wsdl:output message="tns:AppModuleSearchService_
getEngineInstancesResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="getDisplayName">
<wsdl:input message="tns:AppModuleSearchService_getDisplayName"/>
<wsdl:output message="tns:AppModuleSearchService_
getDisplayNameResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
<wsdl:operation name="deleteSearch">
<wsdl:input message="tns:AppModuleSearchService_deleteSearch"/>
<wsdl:output message="tns:AppModuleSearchService_
deleteSearchResponse"/>
<wsdl:fault name="ServiceException"
message="errors:ServiceException"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="AppModuleSearchServiceSoapHttp"
type="tns:AppModuleSearchService">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="search">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/search"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="saveSearch">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/saveSearch"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="getSavedSearches">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/getSavedSearches"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="getSavedSearchDetails">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/getSavedSearchDetails"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="getSavedSearch">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/getSavedSearch"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="getEngineInstances">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/getEngineInstances"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="getDisplayName">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/getDisplayName"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
<wsdl:operation name="deleteSearch">
<soap:operation
soapAction="/oracle/ecsf/service/query/common/deleteSearch"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
<wsdl:fault name="ServiceException">
<soap:fault name="ServiceException" use="literal"
encodingStyle=""/>
</wsdl:fault>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="AppModuleSearchService">
<wsdl:port name="AppModuleSearchServiceSoapHttpPort"
binding="tns:AppModuleSearchServiceSoapHttp">
<soap:address
location="http://localhost:7101/Application1-ViewController-context-root/AppModule
SearchService"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
</xsd:schema>
The SavedSearch request XSD describes the set of rules that the request XMLs must
follow to be valid. Examples of valid request XMLs include the following:
getSavedSearch()
<request>
<name>ECSF_JUNIT_SVSEARCH</name>
<callerctx>null</callerctx>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
getSavedSearches()
<request>
<callerctx>%</callerctx>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
saveSearch()
<request>
<savedSearch name="ECSF_JUNIT_SVSEARCH" id="1" compid="2">
<description>
<![CDATA[Updated Description]]>
</description>
<callerctx>
<![CDATA[]]>
</callerctx>
<query>
<![CDATA[]]>
</query>
<ispublic>
<![CDATA[false]]>
</ispublic>
<userid>
<![CDATA[junit]]>
</userid>
<detailsid>
<![CDATA[1]]>
</detailsid>
<queryMetaData>
<query>
<![CDATA[%]]>
</query>
<page>1</page>
<lang>en</lang>
<pageSize>10</pageSize>
<categories>
<category name="runtime.EmpView" eid="1" compid="0"></category>
</categories>
</queryMetaData>
</savedSearch>
<name></name>
<callerctx>null</callerctx>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
deleteSearch()
<request>
<savedSearch name="DeleteSavedSearch" id="100010033142848" compid="2">
<description>
<![CDATA[Junit Saved Search]]>
</description>
<callerctx>
<![CDATA[CRM]]>
</callerctx>
<query>
<![CDATA[%]]>
</query>
<ispublic>
<![CDATA[false]]>
</ispublic>
<userid>
<![CDATA[junit]]>
</userid>
<detailsid>
<![CDATA[100010033142849]]>
</detailsid>
<queryMetaData>
<query>
<![CDATA[%]]>
</query>
<page>1</page>
<lang>en</lang>
<pageSize>10</pageSize>
<categories>
<category name="runtime.EmpView" eid="1" compid="3"></category>
</categories>
</queryMetaData>
</savedSearch>
<name></name>
<callerctx>null</callerctx>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
getSavedSearchDetails()
<request>
<savedSearch name="SavedSearch" id="100010033142848" compid="2">
<description>
<![CDATA[Junit Federation Saved Search]]>
</description>
<callerctx>
<![CDATA[CRM]]>
</callerctx>
<query>
<![CDATA[%]]>
</query>
<ispublic>
<![CDATA[false]]>
</ispublic>
<userid>
<![CDATA[junit]]>
</userid>
<detailsid>
<![CDATA[100010033142849]]>
</detailsid>
</savedSearch>
<callerctx>null</callerctx>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
<xsd:sequence>
<xsd:element name="category" maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="eid" type="xsd:integer" use="required"/>
<xsd:attribute name="compid" type="xsd:integer"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="tags" type="xsd:string" minOccurs="0"/>
<xsd:element name="filters" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="filter" maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="operator" type="xsd:string"
use="required"/>
<xsd:attribute name="type" type="xsd:string"
use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
The QueryMetaData request XSD describes the set of rules that the request XMLs must
follow to be valid. An example of a valid request XML for search() is:
<request>
<queryMetaData>
<query>
<![CDATA[*]]>
</query>
<page>1</page>
<lang>en</lang>
<pageSize>10</pageSize>
<categories>
<category name="runtime.EmpView" eid="1" compid="2"></category>
</categories>
</queryMetaData>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
The engineInstanceRequest request XSD describes the set of rules that the request
XMLs must follow to be valid. An example of a valid request XML for
getEngineInstances() is:
<request>
<enginetypeid>-1</enginetypeid>
<locale>en_us</locale>
<scope>LOCAL</scope> /*use GLOBAL for global scope*/
</request>
getSavedSearch()
getSavedSearches()
saveSearch()
deleteSearch()
getSavedSearchDetails
search()
getEngineInstances()
If any of the query web service requests result in an exception, the exception is
wrapped in a service error XML response message.The service error XML strings are
based on the following XSD:
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="qualified">
<xsd:element name="serviceError">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="code" type="xsd:string" minOccurs="0"/>
<xsd:element name="message" type="xsd:string"/>
<xsd:element name="stack" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
33.9.4.1 getSavedSearch()
The web service response message for the method String getSavedSearch(String
userName, String savedSearchRequest) is based on the following XSD:
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="qualified">
<xsd:element name="savedSearch">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="description" type="xsd:string"/>
<xsd:element name="callerctx" type="xsd:string"/>
<xsd:element name="query" type="xsd:string"/>
<xsd:element name="ispublic" type="xsd:boolean"/>
<xsd:element name="userid" type="xsd:string"/>
<xsd:element name="detailsid" type="xsd:integer" minOccurs="0"/>
<xsd:element ref="queryMetaData"/>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="id" type="xsd:integer" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="queryMetaData">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="query" type="xsd:string"/>
<xsd:element name="page" type="xsd:integer"/>
<xsd:element name="lang" type="xsd:string"/>
<xsd:element name="pageSize" type="xsd:integer"/>
<xsd:element name="searchCtrl" type="xsd:string" minOccurs="0"/>
<xsd:element name="soname" type="xsd:string" minOccurs="0"/>
<xsd:element name="facetPaths" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="facetPath" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" maxOccurs="unbounded"
minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="value" type="xsd:string"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="categories" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="category" maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="eid" type="xsd:integer" use="required"/>
<xsd:attribute name="compid" type="xsd:integer"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="tags" type="xsd:string" minOccurs="0"/>
<xsd:element name="filters" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="filter" maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="operator" type="xsd:string"
use="required"/>
<xsd:attribute name="type" type="xsd:string"
use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
33.9.4.2 getSavedSearches()
The web service response message for the method String getSavedSearches(String
userName, String savedSearchRequest) is based on the following XSD:
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="qualified">
<xsd:include schemaLocation="saved-search.xsd"/>
<xsd:element name="savedSearches">
<xsd:complexType>
<xsd:sequence>
33.9.4.3 saveSearch()
The web service response message for the method String saveSearch(String
userName, String savedSearchRequest) is the same as the response for
getSavedSearch(). For information, see Section 33.9.4.1, "getSavedSearch()."
33.9.4.4 deleteSearch()
The web service response message for the method String deleteSearch(String
userName, String savedSearchRequest) is the string success.
33.9.4.5 getSavedSearchDetails
The web service response message for the method String
getSavedSearchDetails(String userName, String savedSearchRequest) is based
on the following XSD:
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="qualified">
<xsd:element name="savedSearchDetails">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="queryMetaData"/>
</xsd:sequence>
<xsd:attribute name="savedSearchId" type="xsd:integer" use="required"/>
<xsd:attribute name="id" type="xsd:integer" use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="queryMetaData">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="query" type="xsd:string"/>
<xsd:element name="page" type="xsd:integer"/>
<xsd:element name="lang" type="xsd:string"/>
<xsd:element name="pageSize" type="xsd:integer"/>
<xsd:element name="searchCtrl" type="xsd:string" minOccurs="0"/>
<xsd:element name="soname" type="xsd:string" minOccurs="0"/>
<xsd:element name="facetPaths" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="facetPath" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="value" maxOccurs="unbounded"
minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="value" type="xsd:string"
use="required"/>
</xsd:complexType>
</xsd:element>
33-58 Developer's Guide
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="categories" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="category" maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="eid" type="xsd:integer" use="required"/>
<xsd:attribute name="compid" type="xsd:integer"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="tags" type="xsd:string" minOccurs="0"/>
<xsd:element name="filters" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="filter" maxOccurs="unbounded">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="operator" type="xsd:string"
use="required"/>
<xsd:attribute name="type" type="xsd:string"
use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
33.9.4.6 search()
The web service response message for the method String search(String userName,
String queryMetaDataRequest) is based on the following XSD:
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="qualified">
<xsd:include schemaLocation="query-metadata.xsd"/>
<xsd:element name="searchResults">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="hitsMetaData" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="query" type="xsd:string"/>
<xsd:element name="page" type="xsd:integer"/>
<xsd:element name="pages" type="xsd:integer"/>
<xsd:element name="hits" type="xsd:integer"/>
<xsd:element ref="queryMetaData"/>
<xsd:element name="categories" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="category" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="searchableObjects" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="searchableObject"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="id" type="xsd:integer"
use="required"/>
<xsd:attribute name="lastTimeCrawled"
type="xsd:integer" use="optional"/>
<xsd:attribute name="displayName"
type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="id" type="xsd:integer"
use="required"/>
<xsd:attribute name="eid" type="xsd:integer"
use="required"/>
<xsd:attribute name="external" type="xsd:string"
use="required"/>
<xsd:attribute name="displayName" type="xsd:string"
use="required"/>
<xsd:attribute name="scope" type="xsd:string"
use="required"/>
<xsd:attribute name="applid" type="xsd:string"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="altwords" type="xsd:string" minOccurs="0"/>
<xsd:element name="timespent" type="xsd:integer"/>
<xsd:element name="facets" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="facet" maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="results" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="result" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="title" type="xsd:string"/>
<xsd:element name="displayUrl" type="xsd:string"/>
<xsd:element name="score" type="xsd:integer"/>
<xsd:element name="searchableObject" minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="eid" type="xsd:integer"
use="required"/>
</xsd:complexType>
</xsd:element>
<xsd:element name="content" type="xsd:string"/>
<xsd:element name="keywords" type="xsd:string" minOccurs="0"/>
<xsd:element name="lang" type="xsd:string"/>
<xsd:element name="attributes">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="attribute" maxOccurs="unbounded"
minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:string">
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="binding" type="xsd:string"
use="required"/>
<xsd:attribute name="type" type="xsd:string"
use="required"/>
<xsd:attribute name="displayName"
type="xsd:string" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="tags" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
33.9.4.7 getEngineInstances()
The web service response message for the method String
getEngineInstances(String userName, String engineInstanceRequest) is based
on the following XSD:
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.example.com"
targetNamespace="http://www.example.com"
elementFormDefault="qualified">
<xsd:element name="engineInstances">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="engineInstance" maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="category" maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="searchableObjects" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="searchableObject"
maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="fieldDefs" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="fieldDef"
maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:attribute name="name"
type="xsd:string" use="required"/>
<xsd:attribute name="binding"
type="xsd:string" use="required"/>
<xsd:attribute name="dataType"
type="xsd:string" use="required"/>
<xsd:attribute name="isStored"
type="xsd:boolean" use="required"/>
<xsd:attribute name="isSecure"
type="xsd:boolean" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="facetDefs" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="facetDef"
maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="facetEntryDef"
maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
Advanced Topics for ECSF 33-63
<xsd:attribute name="value"
type="xsd:string" use="required"/>
<xsd:attribute name="displayValue"
type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name"
type="xsd:string" use="required"/>
<xsd:attribute name="binding"
type="xsd:string" use="required"/>
<xsd:attribute name="displayName"
type="xsd:string" use="required"/>
<xsd:attribute name="isleaf"
type="xsd:boolean" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="actionDefs" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="actionDef"
maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="target"
type="xsd:string"/>
<xsd:element name="title"
type="xsd:string"/>
<xsd:element name="params"
minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="param"
maxOccurs="unbounded" minOccurs="0">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension
base="xsd:string">
<xsd:attribute
name="name" type="xsd:string" use="required"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name"
type="xsd:string" use="required"/>
<xsd:attribute name="isDefault"
type="xsd:string" use="required"/>
<xsd:attribute name="type"
type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string"
use="required"/>
<xsd:attribute name="id" type="xsd:integer"
use="required"/>
<xsd:attribute name="displayName" type="xsd:string"
use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="eid" type="xsd:integer" use="required"/>
<xsd:attribute name="id" type="xsd:integer" use="required"/>
<xsd:attribute name="external" type="xsd:boolean"
use="required"/>
<xsd:attribute name="displayName" type="xsd:string"/>
<xsd:attribute name="scope" type="xsd:string" use="required"/>
<xsd:attribute name="applid" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="id" type="xsd:integer" use="required"/>
<xsd:attribute name="engineType" type="xsd:string" use="required"/>
<xsd:attribute name="engineTypeId" type="xsd:integer" use="required"/>
<xsd:attribute name="displayName" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Note:
In the Application Navigator, right-click the project in which you want to create
the web service proxy, and choose New.
2.
In the New Gallery, expand Business Tier, select Web Services and then Web
Service Proxy, and click OK.
3.
On the Select Web Service Description page of the wizard, enter the URL for the
WSDL that was generated when the application was deployed on the Oracle
WebLogic Server, for example,
http://myhost.us.example.com:7101/CrmSearchService/AppModuleSearchServi
ce?WSDL, then tab out of the field.
If the Next button is not enable, click Why Not? to understand what problem
JDeveloper encountered when trying to read the WSDL document. If necessary, fix
the problem after verifying the URL and repeat this step.
When the wizard displays an enabled Next button, then Oracle JDeveloper has
recognized and validated the WSDL document.
4.
For Specify Default Mapping Options, enter or choose a Java package name for
the generated web service proxy class.
5.
Click Next.
6.
Continue through the pages of the wizard to specify details about the web service
proxy. For more information about each page of the wizard, press F1 or click Help.
7.
Click Finish.
8.
jps-config.xml
cwallet.sso
default-keystore.jks
java.io.File;
java.io.FileInputStream;
java.io.FileNotFoundException;
java.io.IOException;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Properties;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import
import
import
import
import
oracle.ecsf.SearchException;
oracle.ecsf.SearchHits;
oracle.ecsf.client.SearchGroup;
oracle.ecsf.client.dataobject.SavedSearch;
oracle.ecsf.client.dataobject.SavedSearchDetails;
import oracle.ecsf.impl.QueryMetaDataImpl;
import oracle.ecsf.meta.MetaEngineInstance;
import oracle.ecsf.service.query.common.AppModuleSearchService;
import oracle.ecsf.service.query.common.AppModuleSearchService_Service;
import oracle.ecsf.service.query.ws.marshaller.ServiceUtil;
import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;
((BindingProvider)appModuleSearchService).getRequestContext().put(BindingProvider.
USERNAME_PROPERTY, "weblogic");
((BindingProvider)appModuleSearchService).getRequestContext().put(BindingProvider.
PASSWORD_PROPERTY, wlsPassword);
}
catch (Exception e)
{
e.printStackTrace();
System.out.println("Excpetion " + e);
}
}
/**
* invoke the getEngineInstances() method exposed in WebService.
*/
public void testGetEngineInstance()
{
ServiceUtil sUtil = new ServiceUtil();
try
{
String query =
"<request><enginetypeid>2</enginetypeid><locale>en-US</locale><scope>LOCAL</scope>
</request>";
String response = appModuleSearchService.getEngineInstances("weblogic",
query);
Collection<MetaEngineInstance> instances =
sUtil.toEngineInstances(response);
}
catch (Exception e)
{
}
}
/**
* invoke the search() method exposed in WebService.
*/
public void testSearch()
{
ServiceUtil sUtil = new ServiceUtil();
String request =
"<request><queryMetaData><query><![CDATA[*]]></query><page>1</page><lang>en</lang>
<pageSize>10</pageSize><categories><category name=\"EmpSearch\"
eid=\"100010024205617\"
compid=\"100010026129681\"></category></categories></queryMetaData><request>";
try
{
String response = appModuleSearchService.search("weblogic", request);
SearchHits hits = sUtil.toSearchHits(response);
}
catch (Exception e)
{
}
}
/**
* invoke the getSavedSearch() method exposed in WebService.
*/
public void testGetSavedSearch()
{
ServiceUtil sUtil = new ServiceUtil();
try
{
String request =
"<request><name>TestServiceproxy</name><callerctx>GLOBAL</callerctx><locale>en-US<
/locale><scope></scope></request>";
String response = appModuleSearchService.getSavedSearch("weblogic",
request);
SavedSearch ss = sUtil.toSavedSearch(response);
}
catch (Exception e)
{
}
}
/**
* invoke the getSavedSearches() method exposed in WebService.
*/
public void testgetSavedSearches()
{
ServiceUtil sUtil = new ServiceUtil();
try
{
String request =
"<request><name></name><callerctx>LOCAL</callerctx><locale>en-US</locale><scope>LO
CAL</scope></request>";
String response = appModuleSearchService.getSavedSearches("weblogic",
request);
ArrayList<SavedSearch> savedSearches = sUtil.toSavedSearches(response);
}
catch (Exception e)
{
}
}
/**
* invoke the savedSearch() method exposed in WebService.
*/
public void testSaveSearch()
{
ServiceUtil sUtil = new ServiceUtil();
try
{
SavedSearch savedSearch = createSavedSearch("TestServiceproxy");
String request = sUtil.toString(savedSearch, true);
appModuleSearchService.saveSearch("weblogic", request);
}
catch (Exception e)
{
}
}
/**
* invoke the getSavedSearchDetails() method exposed in WebService.
*/
public void testGetSavedSearchDetails()
{
ServiceUtil sUtil = new ServiceUtil();
try
{
String ssRequest =
"<request><name>TestServiceproxy</name><callerctx>GLOBAL</callerctx><locale>en-US<
/locale><scope></scope></request>";
String ssResponse = appModuleSearchService.getSavedSearch("weblogic",
ssRequest);
String request = "<request>" + ssResponse +
"<callerctx>null</callerctx><locale>en_us</locale><scope>LOCAL</scope></request>";
String response =
appModuleSearchService.getSavedSearchDetails("weblogic", request);
SavedSearchDetails ssDetails = sUtil.toSavedSearchDetails(response);
}
catch (Exception e)
{
}
}
/**
* invoke the deleteSearch() method exposed in WebService.
*/
public void testDeleteSavedSearch()
{
try
{
String ssRequest =
"<request>QA<name>TestServiceproxy</name><callerctx>GLOBAL</callerctx><locale>en-U
S</locale><scope></scope></request>";
String ssResponse = appModuleSearchService.getSavedSearch("weblogic",
ssRequest);
String request = "<request>" + ssResponse +
"<callerctx>null</callerctx><locale>en_us</locale><scope>LOCAL</scope></request>";
String response = appModuleSearchService.deleteSearch("weblogic",
request);
}
catch (Exception e)
{
}
}
private SavedSearch createSavedSearch(String sSearchName) throws
SearchException
{
QueryMetaDataImpl queryMetaData = new QueryMetaDataImpl();
queryMetaData.setQueryString("%");
queryMetaData.setPageSize(10);
queryMetaData.setCurrentPage(1);
SearchGroup[] sgs = new SearchGroup[] { new SearchGroup("EmpSearch",
"EmpSearch", engineInstanceId, null, null) };
queryMetaData.setSearchGroups(sgs);
SavedSearch savedSearch =
new SavedSearch(SavedSearch.VAL_INVALID_ID, "weblogic", null, null, null,
sSearchName, "search created for WS interop", null,
queryMetaData.getQueryString(), false, "GLOBAL");
SavedSearchDetails ssd = new SavedSearchDetails(1L, "weblogic", null, null,
null, SavedSearch.VAL_INVALID_ID, queryMetaData, null);
savedSearch.setSavedSearchDetails(ssd);
return savedSearch;
}
private void initializeWLSParams()
{
//load wls host/port and ses wls host/port from ecsf.properties
The sample client class illustrates how each of the methods are called and how the
XMLs are deserialized.
Messages that you create during design time (for example, facet display names)
and are displayed to the users who perform the queries.
Messages you create during deployment (for example, searchable object names,
search category names, and index schedule names displayed during crawl
management).
Crawlable content.
ECSF must determine the locale to display the messages in the appropriate language
for the user.
ECSF also reserves a Groovy entity formatter that provides two functions:
2.
Use the format() function in the Groovy expressions for the Title, Body, and
Keywords properties.
3.
4.
Use the getLabel() function in the Groovy expressions for the Title, Body, and
Keywords properties.
Click the Add icon in the Custom Properties table header and select Translatable
Property to open the Select Text Resource dialog.
3.
Note:
4.
In the Display Value field, enter a string to associate with the key in the page's
resource bundle. For example, enter
Identification Number: {0}. {1} {2} {3} {4} {5} {6}.
5.
In the Key field, enter a string to uniquely identify a locale-specific object in the
resource bundle. For example, enter EMPVIEW_BODY.
6.
In the Description field, enter a description of any length for the key and value
pair. For example, enter body value for crawling.
7.
then you can use the following Groovy expression for the Body property:
formatter.format("EMPVIEW_BODY", Deptno, Empno ((DeptView.size() > 0) ? "Dept:" :
""), DeptView.Dname, ((StatesEAView.size() > 0) ? "State:" : ""),
StatesEAView.Name, TestTransient)
The resource bundle key name, as well as up to ten parameters are added to the
formatted string.
For date attributes, you can write a Groovy expression to call
formatter.format(String attributeName), without a resource bundle key as an
input parameter, to correctly format the date attribute value as part of the Groovy
expression.
Select the desired attribute in the Attributes table and click the Edit selected
attribute(s) icon.
3.
In the Edit Attribute dialog, select Control Hints to open the Control Hints page.
4.
Click the icon next to the Label Text field to open and use the Select Text Resource
dialog.
5.
Note:
6.
In the Display Value field, enter a string to associate with the key in the page's
resource bundle.
7.
In the Key field, enter a string to uniquely identify a locale-specific object in the
resource bundle.
8.
In the Description field, enter a description of any length for the key and value
pair.
9.
The facet display name is translated per the resource bundle supported by Oracle
Application Development Framework (Oracle ADF). The facet entry display names are
translated per the LOV definition with context locale binding.
For example:
Organization
Vision USA
Vision Canada
Organization is translated via the Oracle ADF resource bundle with key
ORGANIZATION_ID.
Figure 338 Select Text Resource
To translate Vision USA and Vision Canada, you need to create a view object based on
the VL table that supports localization, for example, HR_ALL_ORGANIZATION_UNITS_VL.
After this view object is created and used as the LOV for the BUSINESS_UNIT_ID of the
base searchable object, the value for the field name is pulled from the VL table with the
correct locale of the current user. For information on how to create facets, see
Section 29.4.4, "How to Implement Faceted Navigation."
When your facet is localized, Oracle Fusion Applications Search UI requests facet
definitions from ECSF when users performs a search. ECSF will load the facet
definition, including facet names from the resource bundle based on user's locale.
When the user clicks the facet, ECSF will execute the LOV for the facet and retrieve the
data from the database based on the current user's language setting. In the example,
the organization name will be displayed to the user in his language. When the user
clicks on a particular node, such as Vision USA, ECSF will perform a query against the
search engine with a filter on Organization Id = 204 where 204 is the organization
ID for Vision USA.
Note:
If the display name is not available for the current locale, the facet
name is used.
ECSF uses LOVs to support facets, and the LOV display values must be translatable.
The data sources of the LOVs used for facets can be view objects with static data or
view objects with dynamic data (pulled from database through SQL). Display values
of LOVs whose data sources are view objects with static data are displayed using the
resource file corresponding to the application's current locale. Display values of LOVs
populated with dynamic content can be translated based on the locale in the user's
context.
You can translate the LOV display values based on the locale in the user's context by
adding a language code column to the view object. The following instructions are
based on the example provided in Section 29.4.4, "How to Implement Faceted
Navigation." It assumes that you have an EmpView base view object with a working
LOV on the StatesView view object already defined.
To translate LOV display values:
Add a LANG column (VARCHAR2) to the STATES table.
1.
2.
Populate the LANG column for all rows with a 2-character ISO639 code (for
example, en or fr).
3.
Add the LANG column to the States entity object and StatesView view object.
Alternatively, you can re-create it from scratch.
4.
Create a view criteria on StatesView (on the view object, navigate to Query >
View Criteria > + and click the Add Criteria button) with the following values:
5.
Attribute: Lang
Operator: equal to
For Parameter, click New to create a bind variable with the following values:
Name: UserLang
ValueType: Expression
6.
7.
Navigate to EmpView > View Accessors, select StatesView1, and click Edit.
8.
In the Edit View Accessor dialog, select the view accessor (StatesViewCriteria)
in the Available list and click the Move icon to add it to the Selected list.
9.
Edit the UserLang bind variable from StatesView by entering the following
Groovy expression that evaluates to the user's current language:
adf.context.locale.getLanguage()
The view criteria (similar to a defined WHERE clause) on StatesView and a bind
variable named UserLang are created. The EmpView base view object is configured
to use the view criteria when querying StatesView and the value of the bind
variable is set to the user's current language. During runtime, only the records
where LANG matches the locale.getLanguage() of the locale is returned.
translation table so that it can be shared across runtime, the ECSF Command Line
Administration Utility, and Fusion Applications Control.
For Fusion Applications Control, the display name for
searchable objects, search categories, and index schedules is in the
language of the object created by the administration users.
Note:
Table 332
ID
FirstName
LastName
EmailAddress
John
Wayne
john.wayne@example.co 94065
m
Chris
Smith
chris.smith@example.co
m
Table 333
ZipCode
94066
ParentID
FIRST_NAME
LAST_NAME
John
Doe
Jake
Ray
Bob
Barley
Chris
Carpenter
The following shows the resulting data sent to Oracle SES during runtime:
Employee John Wayne with email address john.wayne@example.com works in zipcode
94065 direct report named John Doe has a direct report named Jake Ray
Employee Chris Smith with email address chris.smith@example.com works in zipcode
94066 direct report named Bob Barley has a direct report named Chris Carpenter
Resource bundles are used to store language variations, while translation is the
responsibility of Oracle Fusion Applications i18n support infrastructure.
33.10.6.3 Crawl
You can specify the locale of the data to be indexed by using any of the following
methods:
Language field
You can specify a view object attribute as a language field for a searchable object by
using the Search page. For information, see Section 29.2.3.1, "Setting Search Property
Values for View Objects."
The value of this field for each instance is the language for the instance.
If you do not specify a language field for a given searchable object, ECSF uses the
language preference of the crawler user. This implementation is application specific.
ECSF obtains a session user through identity manager, and obtains the locale for the
user while crawling data. There must be a crawler user with a proper locale profile,
including language preference, created for Oracle Fusion Applications. This user's
language preference is used as the default language if a language field does not exist.
If no crawler language is available, JVM's default locale (Locale.getDefault()) is
used to identify the language, and the JVM default language is used.
33.10.6.4 Query
The user who calls the ECSF query time API must bind the locale to SearchContext. If
the locale is not set in the search context, ECSF attempts to get from ADFContext. If that
fails, the default locale, shown in Example 3332, is used.
Example 3332 Default Locale for Searcher
ADFContext adfContext = ADFContext.getCurrent();
Locale mLocale = (adfContext != null && adfContext.getLocale() != null) ?
adfContext.getLocale() : Locale.getDefault();
Table 334
Name
Type
Description
Searchable Group
Drop-down
Note: The engine instance SES proxy user is used for the search and the search
keyword is "*".
Result
Indicates if any search hits and facets are returned. The actual data are not displayed
due to security reasons.
Name
Type
Description
Searchable Object
Drop-down
Results
Searchable object configuration, including its display name, view object name, ID,
schema name, registered engine instance, associated schedule, and associated
categories.
Results of the body, title, keywords, and default action title validations.
Display of top-level facets. Actual data are obfuscated due to security reasons.
Name
Type
Description
Drop-down
Name
Type
Description
Searchable Group
Drop-down
String
User Name
String
Query String
String
Results
Result hit count: The number of hits for the first page of results (up to 10).
Estimate hit count: The estimated total hit count will for this query.
Search results: The title, body, and attribute values for the first page of results (up
to 10 records) will be shown.
Name
Type
Description
Searchable Object
Drop-down
Incremental Crawl
Checkbox
Number of Batches to
test
Input (integer)
Note: The engine instance crawl user is used for this test.
Results
Statistics on each work unit (batch) including the number of documents crawled,
the time taken, and the rate of documents processed by ECSF.
Total statistics for all work units processed.
Name
Type
Description
Engine Instance
Name
Drop-down
Results
Name
Type
Description
Searchable Object
Drop-down
Incremental Crawl
Checkbox
Note: The engine instance crawl user is used for this test.
Result
Complete control feed (including list of data feeds).
Name
Type
Description
Input (String)
Note: The part of the URL that points to the ECSF data service will be ignored. Instead
the data feed will be invoked against the data service stored in the database for the
object's associated engine instance.
Result
Complete XML data feed.
Name
Type
Description
Engine Instance
Drop-down
Result
Values of the search engine instance parameters. Usernames will be obfuscated for
security reasons.
Name
Type
Description
User Name
Input (String)
Results
33.11.4 Security
These tests are used to diagnose issues in the security layer of the ECSF application.
Name
Type
Description
User Name
Input (String)
Permission
(optional)
Input (String)
Specify a permission to check for the user. The format of the permission
should be TYPE:NAME:ACTIONS.
Engine Instance
Name
Drop-down
The engine instance is used when retrieving credentials for non APPID
users.
Results
Checks that the user exists in the system.
Checks that the user has access to the oracle.ecsf credential map.
Displays if the user has access to the Diagnostics service if it does not have access
to all services.
Checks that the credentials for the user can be obtained from the credential store.
Name
Type
Description
Engine Instance
Name
Drop-down
Troubleshooting ECSF
Result
Checks that the system can write to the credential store by creating and removing
credentials for a dummy user.
Name
Type
Description
Searchable Object
Drop-down
User Name
Input (String)
Attribute Name
(optional)
Input (String)
The security attribute to use for the test. If no attribute is given then the
default security attribute will be used.
Results
Troubleshooting ECSF
Through Oracle SES, start full indexing from the Fusion Applications Control. For
information, see the "Starting Full Indexing" section in Oracle Fusion Applications
Administrator's Guide.
Through the browser, append ?forceInitialCrawl=true to the config feed.
33.12.1.3 Configuration or Data Feed Execution Thread Is Busy for Longer than the
Configured Warning Timeout
You receive an error indicating that the execution time of the configuration or data
feed execution thread is exceeding the timeout settings, for example:
Error: name has been busy for "elapsedTime" seconds working on the request
"curReq", which is more than the configured time (StuckThreadMaxTime) of "maxTime"
seconds.
Following are two possible causes and solutions for this issue:
Problem
A SQL script being executed by ECSF for the configuration feed or data feed is taking
a long time to execute.
Solution
Enable SQL tracing to find long-running SQL processes, and tune the SQL script to
reduce the execution time.
Problem
ECSF is unexpectedly running longer than the configured time.
Solution
Increase the Oracle WebLogic Server warning timeout setting.
33.12.1.4 Class Not Found Errors When Running the ECSF Servlet
You receive Class Not Found errors when you run the ECSF servlet.
Problem
When you created the ECSF application, you did not select the Fusion Web
Application (ADF) template.
Solution
Add the Fusion Web Application (ADF) template through Application Properties.
Troubleshooting ECSF
33.12.1.5 Out of Memory Error when Deploying the ECSF Application to Oracle
WebLogic Server or Running the Application
You receive a java.lang.OutOfMemoryError: PermGen space exception when you
deploy the ECSF application to Oracle WebLogic Server instance or when you run the
application.
Problem
MaxPermSize is set too low.
Solution
Increase MaxPermSize by starting the WebLogic JVM using the -XX:MaxPermSize=256m
parameter.
If you start the ECSF servlet from within JDeveloper using the Integrated WebLogic
Server:
1.
2.
Open setDomainEnv.sh.
3.
Problem
The ECSF Client library is missing from the project class path.
Solution
Update the project class path with the ECSF Client library.
Troubleshooting ECSF
33.12.1.8 How to Check the Space Availability for SES Crawls in the Database
The table spaces required are:
SEARCH_DATA
SEARCH_INDEX
SEARCH_TEMP
The DBF filepath will depend on the environment being used. To learn the exact DBF
file to be used, use the select command shown above. For example:
/slot/ems7248/oracle/db/apps_st/data/SEARCH_DATA_3.dbf
To delete an additional datafile:
ALTER TABLESPACE SEARCH_DATA DELETE DATAFILE
st/data/SEARCH_DATA_9.dbf';
'/slot/ems7248/oracle/db/apps_
The same steps can be used to add additional data files for other table spaces.
Troubleshooting ECSF
Click OK.
Troubleshooting ECSF
Solution
Increase the WS timeout using this parameter in the startup section on the WLS
console for the Search Server
-Doracle.ecsf.service.ws.timeout=500000
33.12.1.13 Query Does Not Return Search Results but No Errors Are Displayed on
the UI
Cause
The crawl for the data sources under this category was not successful.
Solution
Log into SES administration and check that the schedule for the data source indexed
successfully.
Troubleshooting ECSF
Check if the ESS and search_server1 managed servers are running on the Common
domain. If these are not running, the crawls will fail.
Check if the END points mentioned in the SES Source page are accessible.
Check if the database has sufficient space to accommodate the crawled data.
Check first query to increase the table space.
Verify the security attributes for the Searchable View Object (SVO). Also verify if
the passwords for CRAWL_APPIDs are correct.
Check that these users are not locked: FUSION_APPS_FSCM_SES_CRAWL_
APPID, FUSION_APPS_CRM_SES_CRAWL_APPID, and FUSION_APPS_HCM_
SES_CRAWL_APPID.
33.12.1.17 How to Get the Password for the SES Administration Page
The SES Administration page uses "searchsys" as the default user for logging in. The
password for SES can be discovered using WebLogic Server Scripting Tools (WLST)
commands.
Connect to WLST.
Sample output:
Already in Domain Runtime Tree
[Name : searchsys, Description : null, expiry Date : null]
PASSWORD:welcome1
Troubleshooting ECSF
oracle.ecsf.AdminLogger
oracle.ecsf.ClientLogger
oracle.ecsf.RuntimeLogger
Related Links
The following document provides more information about the topic discussed in this
section:
For more information, see the "Configuring Settings for Log Files" chapter in the
Oracle Fusion Middleware Administrator's Guide.
Troubleshooting ECSF
Part VI
Part VI
In addition to these three core categories, other chapters within this part provide
guidance on a few less common patterns that might be useful to applications
developers.
Each chapter in this section describes a use case and its associated recommended
design pattern, along with procedures for implementing the design pattern,
recommended validation procedures, and troubleshooting tips.
When carrying out the procedures described in the following
chapters, use the Default/All technologies role for any SOA-related
activity.
Note:
Chapter 34, "Initiating a SOA Composite from an Oracle ADF Web Application"
Chapter 41, "Working with Data from a Remote ADF Business Components
Service"
Chapter 42, "Invoking an Asynchronous Service from a SOA Composite"
Chapter 46, "Implementing an Oracle ADF Task Flow for a Human Task"
34
Initiating a SOA Composite from an Oracle
ADF Web Application
34
This chapter describes what a user action or other activity in an Oracle ADF web
application needs to do to invoke a SOA composite. The invocation is asynchronous
and does not require a response. Inside the SOA composite, an Oracle Mediator
component can provide routing and transformation, a BPEL component can provide
business process orchestration, a human task service can provide workflows, and a
decision service can provide complex business rules based decision making.
When to implement: A user action or other activity in an Oracle ADF web application
needs to invoke a SOA composite. The invocation is asynchronous and does not
require a response. Inside the SOA composite, an Oracle Mediator component can
provide routing and transformation, a BPEL component can provide business process
orchestration, a human task service can provide workflows, and a decision service can
provide complex business rules based decision making.
Design Pattern Summary: A business component in the ADF Business Components
Framework publishes a business event to execute a SOA composite application. The
SOA composite application subscribes to the event using the Oracle Mediator
component, and from there it can be routed to any other service component, such as
BPEL.
Involved components:
34-1
Other Approaches
to subscribe to the event and to then invoke the BPEL process service component. The
mediator service component acts as a binding between the EDN and the BPEL process
service component. Whenever the event is raised by ADF Business Components
(whether through a GUI action or programatically), the BPEL process service
component is invoked. Figure 341 illustrates how these work together.
Figure 341 Mediator Service Component Subscribes to an Event and Invokes BPEL
Service Component
Events raised by ADF Business Components are asynchronous with no return value.
The event infrastructure leverages the WLS JMS provider, so any unconsumed events
can be de-queued by the SOA platform at some later time if the platform isn't running,
assuming the JMS implementation leverages Oracle Advanced Queuing. For
information about integrating Oracle Advanced Queuing with Oracle BPEL Process
Manager or Oracle Mediator, see the chapter "Oracle JCA Adapter for AQ" in the
Oracle Fusion Middleware User's Guide for Technology Adapters.
How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application
34.3 Example
A web application built using ADF Business Components and Oracle ADF Faces
allows users to register bugs found in software. An ADF Business Components entity
object is used to create a bug, and contains an event whose payload is the attribute
values for the created bug. The event is configured to be raised whenever the Create
operation is called on the entity object.
A mediator service component subscribes to the event and accepts the event payload.
A routing rule is configured for the mediator service component that routes the
payload for the event to a BPEL process service component. This component then
sends an email that contains the information from the payload to the bug's creator.
There are some cases in which one might need to propagate the end user ID of the
event raiser across the invoked services for auditing purposes. It is recommended to
propagate this information in the event payload. When raising events for CUD
operations (create, update, delete), include the last_updated_by history column in the
event definition. As this column exists in every Oracle Fusion Applications table, the
user raising the event will always be propagated.
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
34-3
How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application
Set the event point to be the database operation (create, update, delete) that
will raise the event. You can also create any conditions needed to determine
when the event should be raised.
Note:
Create the page in the view that will invoke the operation defined as the event
point for the event (for example, through a command button bound to the commit
operation or through the implicit call to the commit operation as a task flow return
activity).
In the example bug application, this is a UI command component bound to the
Commit operation on the BugReport entity object. Because this operation commits
the data to the database, and the Commit operation's corresponding DML operation
(create) is used to sync the ADF Business Components cache with the database,
the ADF Business Components framework raises the event.
For more information about creating the view, see "Part IV: Creating a Databound
Web User Interface" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
3.
For verification purposes, you can either run the Oracle ADF web application from
the Integrated Oracle WebLogic Server container included with Oracle JDeveloper,
or you can deploy the Oracle ADF web application to a standalone container. This
step includes procedures for running the Oracle ADF web application within the
embedded container and the SOA composite on a standalone Oracle WebLogic
Server container. See Step 4 for procedures on deploying to a standalone container.
How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application
a.
Make sure that EDN data sources have been configured. Using Oracle
WebLogic Server Administration Console, verify that EDNDataSource and
EDNLocalTxDataSource have been configured.
Oracle ADF and SOA data sources for EDN must point to the
same schema. The EDN schema cannot be shared by more than one
SOA runtime environment (such as outside a cluster).
Note:
b.
Navigate to Domain Configurations > Services > JDBC > Data Sources to
verify the existence of EDN data sources.
c.
If the EDN data sources have not been configured, create new EDN data
sources. Select EDNDataSource and click New. Enter the following details:
Name: EDNDataSource
JNDI Name: jdbc/EDNDataSource
Database Type: Oracle and Database Driver > Oracle Thin Driver XA:
Versions 9.0.1.9.2.0.10.11.
Driver Class Name: oracle.jdbc.xa.client.OracleXADataSource.
Click Next. In the next window, uncheck Supports Global Transactions.
Click Next and configure the following:
Database Name: DB_NAME_FUSION_EDN
Host Name/Port: Enter the host name and port for server running the FUSION_
EDN database
Database User Name/Password: Enter a username and password.
Test the data source. Set as DefaultServer and click Finish.
Define EDNLocalTxDataSource as above, but use EDNLocalTxDataSource for
the data source and jdbc/EDNLocalTxDataSource for the JNDI name.
d.
Map the data source in the web.xml and weblogic.xml files associated with the
event publishing application. Add the lines shown in Example 341to the
WEB-INF/web.xml file.
Example 341
<resource-ref>
<res-ref-name>jdbc/EDNDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope> </resource-ref>
e.
Create an XML file called weblogic.xml with the following contents, and save
it in the WEB-INF directory. This maps the global JMS resources to local JNDI
names. The names in this file are the defaults expected by the remote
connection factory, so you do not need to specify them. An example is shown
in Example 342.
Example 342
<?xml version="1.0"?>
<resource-description>
34-5
How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application
<res-ref-name>jdbc/EDNLocalTxDataSource</res-ref-name>
<jndi-name>jdbc/EDNLocalTxDataSource</jndi-name>
</resource-description>
<resource-description>
<res-ref-name>jdbc/EDNDataSource</res-ref-name>
<jndi-name>jdbc/EDNDataSource</jndi-name>
</resource-description>
4.
How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application
6.
Use the Create BPEL Process dialog to configure the payload. Use the Input
Element finder icon to select the payload from the schema created for the
event.
In the sample application, the input element would be the BugCreatedInfo
payload under the BugReport.xsd node, as shown in Figure 343.
7.
You create an activity that accepts the payload from the input element as its
input parameters. In the sample application, an email activity is created that
takes various input parameters from the payload as assigns them to the
email's parameters.
In the mediator service component, add a routing rule and configure it so that it
invokes the BPEL process service and contains a subscription to the ADF Business
Components event. Ensure the following:
34-7
Alternative Approaches
You select the initiate operation on the client of the BPEL process service
component as the target service, as shown in Figure 344.
8.
Optionally, use the Transformation map to map the mediator service component's
schema to the input schema of the BPEL process service component. However, this
should not be necessary, as you should be using the same schema for both.
9.
Deploy the SOA composite application to the SOA infrastructure. For details, see
the chapter "Deploying SOA Composite Applications" in the Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
10. Use Oracle Enterprise Manager Fusion Middleware Control Console to view the
1.
Alternative Approaches
javax.xml.namespace.QName;
oracle.fabric.blocks.event.BusinessEventConnection;
oracle.fabric.blocks.event.BusinessEventConnectionFactory;
oracle.fabric.common.BusinessEvent;
oracle.integration.platform.blocks.event.BusinessEventBuilder;
oracle.integration.platform.blocks.event.BusinessEventConnectionFactorySupport;
oracle.xml.parser.v2.XMLDocument;
org.w3c.dom.Element;
oracle.jbo.server.TransactionEvent;
oracle.jbo.server.JTATransactionHandler;
2.
Example 345
34-9
Alternative Approaches
For more information about this approach, see the chapter "Integrating Web Services
Into a Fusion Web Application" in Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
In this pattern, SOA composite services are exposed as web services. You generate a
JAX-WS proxy client to invoke the SOA composite exposed as a web service from your
ADF Business Components application module.
You use the web services wizard to generate a web service proxy, and then call the web
service using method calls.
An indirection for the web service proxy node enables retrieving the location of the
web service WSDL, username and password from connections.xml. To use the
indirection, access the proxy via
oracle.adf.model.connections.webservice.WebServiceConnection.
An example is shown in Example 346.
Example 346
Using WebServiceConnection
WebServiceConnection wsc =
(WebServiceConnection)ADFContext.getCurrent().getConnectionsContext().lookup(conne
ctionName);
Hello hello = wsc.getJaxWSPort(Hello.class);
Use the username or SAML token policies for identity propagation and security. For
more information, see Chapter 52, "Securing Web Services Use Cases."
<component name="BugReportMediator">
<implementation.mediator src="BugReportMediator.mplan" />
<business-events>
<subscribe xmlns:sub1="/model/events/edl/BugReport"
name="sub1:bugCreated"
consistency="oneAndOnlyOne"
runAsRoles="$publisher"/>
</business-events>
</component>
Note:
2.
To validate the subject propagation in the SOA composite application, add the
following code as shown in Example 348 to the BPEL file for the BPEL process
flow:
Example 348
Run the Oracle ADF web application and invoke the method that raises the event.
3.
View the ADF Business Components runtime log in the JDeveloper log console to
view the event and payload.
4.
Use Fusion Middleware Control Console for tracking composite instances and for
a variety of debugging, monitoring and testing functions.
Open Fusion Middleware Control Console to verify the process instance has been
created. Use the Audit tab to verify that the payload is correct.
34.7.2.1 SendEvent
SendEvent is a command line utility for sending an event to a database-based Oracle
Event Delivery Network instance. SendEvent can send an empty event (of a given
queue name) or an entire event from a file. Running the command displays a list of
command line options.
Some examples are shown in Example 349 and Example 3410.
In Example 349, an empty event with namespace uuid:1111 and local name MyEvent
is sent to the event bus.
Example 349
oracle.integration.platform.blocks.event.SendEvent -dbconn
host.example.com:1521:SID -dbuser user -dbpass password -eventName
{uuid:1111}MyEvent
In Example 3410, the event contained in the file AnEvent.xml is sent to EDN.
Example 3410 Sending an Event to EDN
oracle.integration.platform.blocks.event.SendEvent -dbconn
host.example.com:1521:SID -dbuser user -dbpass password -event AnEvent.xml
34.7.2.2 BusinessEventConnectionFactorySupport
You can use BusinessEventConnectionFactorySupport in your Oracle ADF web
application to test your event publishing code. Rather than sending an event to a
queue, you can configure your Oracle ADF web application to print the event
information to the log using BusinessEventConnectionFactorySupport.
To do so, set the system property edn.debug.event-connection to true when running
your application. When the application sends an event, the information for that event
is logged, including the event body in its entirety. This enables you to see the events
that will be sent to EDN when the application runs on a SOA server.
The log name is oracle.integration.platform.blocks.event.debug, but in most
configurations the information prints to stdout by default.
To set the system property:
When Oracle WebLogic Server starts up, add the system property shown in
Example 3411 to the JAVA_OPTIONS environment variable.
Example 3411 Setting the EDN Debug System Property
-Dedn.debug.event-connection=true
34.8.1 Deployment
If deployment of the SOA composite application fails, then verify the following:
The location element in the EDL file located in the directory is relative to the
directory that contains the EDL file.
If you get an invalid XPath expression exception, use a static value instead of a
value from the payload.
34.9 What You May Need to Know About Initiating a SOA Composite from
an Oracle ADF Web Application
Before you implement these design patterns, you should be aware of the following:
If you change the event name or event payload, the mediator will not respond to
the raising of the event. If you need to make changes, you should create a new
event. During development, you need to change the mediator (if the name of the
event changes) and/or the BPEL process being invoked (if the payload changes).
35
Initiating a SOA Composite from a PL/SQL
Stored Procedure
35
This chapter describes what a PL/SQL stored procedure needs to do to initiate a SOA
composite application.
When to implement:.When a PL/SQL stored procedure needs to initiate a SOA
composite application.
Design Pattern Summary: A PL/SQL stored procedure raises an event through the
Event Delivery Network within the database. A mediator in the SOA composite
application subscribes to the event and routes it as appropriate.
Involved components:
SOA composite application that includes Oracle Mediator and other components
as needed.
Example
35.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
3.
Create the SOA composite application component that will be invoked (for
example, a BPEL process service component), and create a wire between the
Oracle Mediator component reference and the component service.
4.
From a PL/SQL stored procedure, call the EDN-DB API method publish_event
with the event namespace and the event payload as a CLOB type. An example is
shown in Example 351.
Example 351
DECLARE
NAMESPACE VARCHAR2(200);
LOCAL_NAME VARCHAR2(200);
PAYLOAD CLOB;
BEGIN
NAMESPACE := 'http://xmlns.oracle.com/SubEventMediator/EventDefinition1';
LOCAL_NAME := 'CustomerEvent';
PAYLOAD := to_clob('<eb:business-event xmlns:eb=
"http://oracle.com/fabric/businessEvent"
xmlns:ob="http://xmlns.oracle.com/SubEventMediator/EventDefinition1">
<eb:name>ob:CustomerEvent</eb:name><eb:content><CU:CustomerData
xmlns:CU="http://xmlns.oracle.com/Esb/CustomerData"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CustomerId>A22-9AXC2</CustomerId><CustomerName>
Deserae International</CustomerName><Type>Gold</Type><Description>Accounting
Outsourcing Partner</Description><Address>3228 Massilon Blvd</Address>
<City>Juniper</City><State>Massachusetts</State><Zip>01854</Zip><Country>US
</Country><Phone>877-555-9876</Phone><Status>Active</Status>
<CreditRating>5</CreditRating><Discount>0</Discount><Terms>30n4</Terms>
<EnrollDate>01/1/01</EnrollDate><LastOrderDate>05/05/05/</LastOrderDate>
<Currency>USD</Currency><ContactName>Jan Forester</ContactName><ContactTitle>VP
Finance</ContactTitle><ContactPhone>877-555-9000</ContactPhone><AccountRep>
Geoff Seattle</AccountRep><CampaignRating>2</CampaignRating>
<ReferedBy>Houston America Taxco</ReferedBy>
</CU:CustomerData></eb:content></eb:business-event>');
EDN_PUBLISH_EVENT( NAMESPACE => NAMESPACE, LOCAL_NAME => LOCAL_NAME, PAYLOAD =>
PAYLOAD);
END;
Test your Oracle ADF application using various testing and debugging methods
described in the chapter "Testing and Debugging ADF Components" of the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework. For information about testing the ADF Business Components service,
see the chapter "Integrating Web Services Into a Fusion Web Application" in the
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
2.
Deploy the SOA composite application to the standalone WLS where the SOA
infrastructure has been installed. Because you created a published event from the
SOA composite application to the ADF Business Components service, the ADF
Business Components service need not to also be deployed to the SOA
infrastructure.
3.
Test the deployed SOA composite service using Oracle Enterprise Manager Fusion
Middleware Control Console. Every deployed service has its own test page, so you
can quickly test that the service functions as you expect. For more information
about using the Fusion Middleware Control Console to test deployed SOA
composite applications, see the following chapter:
"Automating Testing of SOA Composite Applications" in the Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
35.6.2 Verifying the SOA Composite Deployment Using Oracle Enterprise Manager
Fusion Middleware Control Console
You can use Oracle Enterprise Manager Fusion Middleware Control Console to verify
that the SOA composite was successfully deployed. In Oracle Enterprise Manager
Fusion Middleware Control Console, you can select the SOA composite instance and
display the result of the event.
Using Oracle Enterprise Manager Fusion Middleware Control Console, you can:
To verify that the SOA composite was successfully deployed and the event was
received:
1. Using a web browser, access the Oracle Enterprise Manager Fusion Middleware
Control Console using a URL such as the following:
http://<host name>:<port number>/em
2.
3.
In the Last 5 Instances pane, click the most recent instance as shown in
Figure 351.
4.
In the Flow Trace window that displays, click the Oracle Mediator component, as
shown in Figure 352.
What You May Need to Know About Initiating a SOA Composite from a PL/SQL Stored Procedure
Enable logging for Oracle Mediator using logging.xml. See the troubleshooting
section in the chapter "Deploying SOA Composite Applications" of the Oracle SOA
Suite Developer's Guide for more information.
For the events functionality, use the Event Delivery Network database log page at
http://host:port/soa-infra/events/edn-db-log. The EDN schema name is FUSION_
EDN.
35.8 What You May Need to Know About Initiating a SOA Composite from
a PL/SQL Stored Procedure
Before you implement these design patterns, be aware of the following:
Run the sample provided before implementing your own version of this use case.
Running the sample ensures that the EDN database queue works as expected.
36
Orchestrating ADF Business Components
Services
36
This chapter describes how to use a SOA composite application to invoke business
methods within an Oracle ADF web application. In this pattern, the Oracle ADF web
application business methods make changes to data, whereas the SOA composite does
not.
When to implement: This pattern describes how to use a SOA composite application
to invoke business methods within an Oracle ADF web application. In this pattern, the
Oracle ADF web application business methods make changes to data, whereas the
SOA composite does not. For example:
A BPEL process service component must retrieve data from a database using an
ADF Business Components service. However, the BPEL process service
component will not post any changes back to the database.
A BPEL process service component must access an exposed service method on an
ADF Business Components service, and that method contains only business logic
and does not update data.
A BPEL process service component must access an exposed service method on an
ADF Business Components service. The exposed service method on the business
component service does not require a conversational callback style of interaction.
Instead, it provides a single invocation, wrapping all of the business logic and
view object manipulation. An example of this is a service method that deletes an
order and all line items, given an order ID as a parameter.
See Chapter 37, "Manipulating Back-End Data from a SOA Composite" for information
regarding patterns in which both the Oracle ADF web application and SOA composite
must update data without conflicting.
Design Pattern Summary: A BPEL process service component uses an invoke activity
to invoke a partner link that accesses a SOAP service created for a business
component.
Involved components:
Other Approaches
This approach is recommended because SOAP bindings do not require that the Oracle
ADF web application and the SOA components be co-located in the same container.
36.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
How to Invoke an ADF Business Components Service from a BPEL Process Service Component
Optionally, create any SDO classes for view objects. For detailed procedures, see
the chapter "Integrating Service-Enabled Application Modules" in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Any top-level view objects referenced in a service interface created from an
application module will automatically be service-enabled. However, creating the
SDO classes for individual view and entity objects allows you to configure the
SDO name or namespace, or selectively service-enable child view objects.
3.
Configure the service interface for the application module. For detailed
procedures, see the chapter "Integrating Service-Enabled Application Modules" in
the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
You can elect to include in your service interface custom methods, top-level
service view instances, and any find operations based on view criteria.
At the end of this step, Oracle JDeveloper creates the WSDL files that will be used
by the BPEL process service component to access any required methods or data.
Figure 362 shows the WSDL created for StoreFrontService in the sample
application. This service accesses the customer and order information needed by
the SOA composite application.
4.
Implement the security as described in Section 36.5, "Securing the Design Pattern.".
5.
For verification purposes, you can either run the Oracle ADF web application from
the Integrated Weblogic Server container included with Oracle JDeveloper, or you
can deploy the Oracle ADF web application to a standalone container. To deploy
to a standalone container:
a.
Create a deployment profile for the web application. For details, see the
chapter "Deploying Fusion Web Applications" of the Oracle Fusion Middleware
Fusion Developer's Guide for Oracle Application Development Framework.
b.
How to Invoke an ADF Business Components Service from a BPEL Process Service Component
c.
d.
Example 361
Note:
6.
Add the WSDL file for the ADF Business Components service to the Resource
Palette of Oracle JDeveloper. If you are using the embedded server, you first need
to run your application. You then create a new URL connection in the Resource
Palette to the embedded server. The URL is:
http://host:7101/ApplicationName-ProjectName-context-root/AppModuleService Name
The URL for the embedded server is generated at the bottom of the WSDL file.
Alternatively, you can open the file and copy the soap:address URI.
If you have deployed the Oracle ADF web application to a standalone server, then
create a new Application Server connection in the Resource Palette. For more
information about using the Resource Palette, see the Oracle JDeveloper Online
Help.
7.
8.
In the SOA composite application, create the reference web service binding to the
WSDL file for the ADF Business Components service. When creating the binding,
be sure to select the WSDL from the Resource Palette.
The ADF Business Components service must be running in
order for it to be discoverable.
Note:
Figure 363 shows the composite.xml file for the sample application.
How to Invoke an ADF Business Components Service from a BPEL Process Service Component
A Partner Link for the ADF Business Components is automatically created when
the reference is wired to the BPEL process.
For more information about creating bindings, see the chapter "Developing SOA
Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
9.
10. Create an Invoke activity that invokes the partner link for the ADF Business
Components.
For more information about creating Invoke activities, see the chapter "Getting
Started with Oracle BPEL Process Manager" in the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
11. Create an Assign activity to assign any values (for example, a static XML
fragment) to variables for the BPEL process service component. These can then be
passed to the ADF Business Components service.
For more information about creating Assign activities, see the chapter "Getting
Started with Oracle BPEL Process Manager" in the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
12. Repeat adding assign and invoke activities as needed. Figure 364 shows the BPEL
Figure 364 BPEL Flow for Invoking an ADF Business Components Service
13. Implement the security as described in Section 36.5, "Securing the Design Pattern".
Secure the ADF Business Components web service data control and the SOA
composite using SAML policies.
Secure the ADF Business Components web service and the SOA composite with
username token policies.
What You May Need to Know About Orchestrating ADF Business Components Services
For information about securing the design pattern, see Section 52, "Securing Web
Services Use Cases."
Deploy the SOA composite application to the standalone WLS where the SOA
infrastructure has been installed. Because you created a web service binding from
the SOA composite application to the ADF Business Components web service, the
ADF Business Components web service need not be deployed to the SOA
infrastructure.
3.
Test the deployed SOA Composite service using Fusion Middleware Control
Console. Every deployed service has its own test page, so you can quickly test that
the service functions as you expect. For more information, see "Managing SOA
Composite Application Instances" in the Oracle Fusion Middleware Administrator's
Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
You can test your SOA composite using Fusion Middleware Control Console. For more
information, see the section "Automating Testing for SOA Composite Applications" in
the chapter "Managing SOA Composite Application Instances" in the Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process
Management Suite.
36.8 What You May Need to Know About Orchestrating ADF Business
Components Services
Before you implement these design patterns, you should be aware of the following:
Any time you invoke an ADF Business Components service, the database transaction
for that operation is committed when it completes.
There is no session propagation between the BPEL process and Oracle ADF. While the
identity is passed in when security policies are in place, a new Oracle Fusion Data
Security session is created with each invocation of the ADF Business Components
service operations.
Orchestrating ADF Business Components Services 36-7
What You May Need to Know About Orchestrating ADF Business Components Services
If you invoke ADF Business Components service operations that use event-raising
entities, those events are not raised.
37
Manipulating Back-End Data from a SOA
Composite
37
This chapter describes what updates created in a SOA composite application need to
do to perform create, read, update, or delete (CRUD) operations on back-end data
stored in a database.
When to implement: When updates created in a SOA composite application need to
perform create, read, update, or delete (CRUD) operations on back-end data stored in
a database.
Design Pattern Summary: Entity variables within a BPEL process service component
access ADF Business Components view objects through a service to fetch data on the
back end. The BPEL process service component then manipulates the data, and the
changes synchronize with the ADF Business Components service when the BPEL
service dehydrates. This is also known as master detail with indexing.
An example of master detail with indexing is entity variables created on master detail
records such as an order header with lines, accessing the lines individually with array
subscripting.
Involved components:
SOA Composite with a BPEL process service component and a SOAP binding.
ADF Business Components, including view objects, with a published web service
interface.
The transaction locking strategy for SDO is optimistic. If the BPEL engine tries to
update an SDO or entity variable and the current revision number is out of date, an
exception will be thrown by the ADF Business Components service.
Example
37.2 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
Optionally create any SDO classes for view objects. For detailed procedures, see
the chapter "Integrating Service-Enabled Application Modules" in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
When modeling your view objects, it is important to determine which may need to
be available for binding to SOA composite entities. It is possible to automatically
enable services in top-level view objects referenced in a service interface create
from an application module. However, you must create the SDO classes for
individual view objects so as to configure the SDO name or namespace, or
selectively service-enable child view objects.
3.
Configure the service interface for the application module. For detailed
procedures, see the chapter "Integrating Service-Enabled Application Modules" in
the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
You can elect to include in your service interface custom methods, top-level
service view instances, and any find operations based on view criteria.
At the end of this step, JDeveloper creates the WSDL files that will be used by the
BPEL process service component to access any required methods or data.
4.
Deploy the services to the Integrated Oracle WebLogic Server by right-clicking the
nameServiceImpl class and selecting Run. Alternatively, define an ADF Business
Components service interface profile and deploy it to the standalone Oracle
WebLogic Server. For more information, see the sections "How to Test the Web
Service Using Integrated Oracle WebLogic Server" and "How to Deploy Web
Services to Oracle WebLogic Server" in the chapter "Integrating Service-Enabled
Application Modules" in the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
5.
Add the WSDL file for the ADF Business Components service to the Resource
Palette. If you are using the integrated server, you must first run your application.
In the Resource Palette, create a new URL connection to the integrated server. The
URL is:
http://localhost:7001/ApplicationName-ProjectName-context-root/AppModuleService
Name
The URL for the embedded server is generated at the bottom of the WSDL file.
Alternatively, you can open the file and copy the soap:address URI.
If you have deployed the Oracle ADF web application to a standalone server, then
create a new Application Server connection in the Resource Palette. For more
information about using the Resource Palette, see JDeveloper Online Help.
The ADF Business Components service must be running in
order for it to be discoverable.
Note:
6.
7.
In the SOA composite application, create a reference binding from the BPEL
process to the WSDL file for the ADF Business Components service. When
creating the reference binding, be sure to select the WSDL from the Resource
Palette.
The ADF Business Components service must be running in
order for it to be discoverable.
Note:
For more information about creating bindings, see the section "Adding Service
Binding Components" in the chapter "Developing SOA Composite Applications
with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle
SOA Suite and "Using ADF Model in a Fusion Web Application" in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
8.
In the BPEL process service component, create an entity variable. This type of
variable delegates BPEL data manipulation operations to an underlying data
provider implementation, in this case the business component.
For more information about creating entity variables, see the chapter
"Manipulating XML Data in a BPEL Process" of the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite
When you create the entity variable, ensure that you select the business
component as the Partner Link.
9.
Add a Bind activity to the BPEL process service component. This activity
establishes the key to pass to the ADF Business Components service when the
SDO will be fetched from the database.
Example 371 shows the XML for a bind activity that establishes OrderId as the
key that will be passed to retrieve orders.
Example 371
For more information about Bind activities, see the section "Adding Service
Binding Components" in the chapter "Developing SOA Composite Applications
with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle
SOA Suite and "Using ADF Model in a Fusion Web Application" in the Oracle
Manipulating Back-End Data from a SOA Composite 37-3
<assign>
<copy>
<from expression="$orderEVar/fdsm:OrderTotal + 1" />
<to variable="orderEVar" query="fdsm:OrderTotal" />
</copy>
</assign>
When the BPEL process service component hits a breakpoint activity (receive,
onMessage, wait, onAlarm) the instance is dehydrated. When dehydration
happens, or the scope where entity variables are declared completes, all related
entity variables that have been loaded flush their changes back to the business
component, and from there to the database. For more information, see
Section 37.7.1, "When Entity Variables Flush Changes Back to ADF Business
Components."
You can use sensor variables to monitor the service data object. For more
information, see the following links:
"Using Oracle BPEL Process Manager Sensors" in the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite
"Monitoring BPEL Process Service Components and Engines" in the Oracle
Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle
Business Process Management Suite
"Managing SOA Composite Application Instances" in the Oracle Fusion
Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business
Process Management Suite.
11. Deploy the ADF Business Components web service to the Integrated Oracle
WebLogic Server with SOA infrastructure. Then deploy the SOA composite
application.
What You May Need to Know About Manipulating Back-end Data from a SOA Composite
Deploy the SOA composite application to the standalone WLS where the SOA
infrastructure has been installed. Because you created a web service binding from
the SOA composite application to the ADF Business Components web service, the
ADF Business Components web service need not be deployed to the SOA
infrastructure.
3.
Test the deployed SOA Composite service using Fusion Middleware Control
Console. Every deployed service has its own test page, so you can quickly test that
the service functions as you expect. For more information, see "Managing SOA
Composite Application Instances" in the Oracle Fusion Middleware Administrator's
Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
Tip: The use of entity variables greatly affects the ability to unit test
the process in an isolated environment. Unit tests of processes that use
entity variables usually require managing the backend database state.
37.7 What You May Need to Know About Manipulating Back-end Data
from a SOA Composite
Before you implement these design patterns, you may want to know more about when
variables flush changes back to the business component, how to test variables without
invoking ADF Business Components, support for XPath operations, and how to
invoke multiple services.
37.7.1 When Entity Variables Flush Changes Back to ADF Business Components
There are three points within the flow when an entity variable flushes its changes back
to the ADF Business Components service:
When the BPEL instance dehydrates. This happens whenever a breakpoint activity
is reached (for example receive, onMessage, wait, onAlarm) or execution reaches
the end of the flow definition.
When the BPEL instance dehydrates due to reaching its activity processing
threshold. By default, the threshold is set to 600 activities. The property
dspMaxRequestDepth in the file bpel-config.xml sets the threshold.
When execution reaches the end of the scope, if the entity variable has been
declared locally (for example within a scope). If the entity variable is declared
globally, it flushes changes when the instance completes.
To illustrate, Example 373 includes a locally declared entity variable.
Manipulating Back-End Data from a SOA Composite 37-5
What You May Need to Know About Manipulating Back-end Data from a SOA Composite
Example 373
<scope name="myScope">
<variables>
<variable name="orderEVar" element="fdsm:orderInfo2SDO"
bpelx:entity.si="OrderService" />
</variables>
<bpelx:bindEntity name="BindEntity_1" variable="orderEntityVar">
<bpelx:key keyname="ns4:OrderId">bpws:getVariableData(
'inputVariable','payload','
/client:BPELEntityVarADFBCProcessRequest/client:orderID')</bpelx:key>
</bpelx:bindEntity>
<assign> ... </assign>
</scope>
Because the variable was defined locally within the scope myScope, after that scope
completes, the variable declaration is no longer accessible from the outer enclosing
scope. At this point, changes made to the variable from the Assign activity will be
flushed to the ADF Business Components service.
Example 374 shows an entity variable defined globally, hence its scope will
complete when the instance completes.
Example 374
<process ...>
<variables>
<variable name="orderEVar" element="fdsm:orderInfo2SDO"
bpelx:entity.si="OrderService" />
</variables>
<sequence>
<receive ...>
<bpelx:bindEntity name="BindEntity_1" variable="orderEntityVar">
<bpelx:key keyname="ns4:OrderId">bpws:getVariableData(
'inputVariable','payload','
/client:BPELEntityVarADFBCProcessRequest/client:orderID')</bpelx:key>
</bpelx:bindEntity>
<assign ...>
</sequence>
</process>
All entity variables are stored in the BPEL dehydration store. However, BPEL only
stores the key data required for the variable and not the variable in its entirety. When
What You May Need to Know About Manipulating Back-end Data from a SOA Composite
loading these variables upon re-hydration, BPEL runs a find request on the variable to
reload the variable data. However, the Oracle ADF web application may have changed
the variable, leading to potential loss of data integrity.
You can check the variable for data integrity by running
bpelx:entity.doVersionCheck = "true".
doVersionCheck checks for ObjectVersionId. If this returns a different value from that
in the BPEL store, a fault is raised.
Example 375 illustrates the verification of variable data integrity.
Example 375
The version fields must exist in the data object returned. If the
Xpath query fails, an exception is thrown. Make sure the custom
version fields are defined in the XSD and that the names match.
Note:
37.7.3 Invoking an ADF Business Components Service and Entity Variables in the
Same BPEL Process Service Component
The pattern described in this chapter and the pattern described in Chapter 36,
"Orchestrating ADF Business Components Services" can be easily combined.
What You May Need to Know About Manipulating Back-end Data from a SOA Composite
38
Accessing a PL/SQL Service from a SOA
Composite
38
This chapter describes what a SOA composite application needs to do to access logic
implemented as PL/SQL in the database.
When to implement: A SOA composite application needs to access logic implemented
as PL/SQL in the database.
Design Pattern Summary: The SOA composite application accesses an ADF Business
Components service, which in turn accesses the PL/SQL stored procedure.
Involved components:
38.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
Write a method in your application module that accesses the PL/SQL stored
procedure. For step-by-step instructions, see the section "Invoking Stored
Procedures and Functions" in the chapter "Advanced Business Components
Techniques" of theOracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework
3.
4.
2.
Deploy the SOA composite application to the standalone WLS where the SOA
infrastructure has been installed. Because you created a published event from the
SOA composite application to the ADF Business Components service, the ADF
Business Components service need not to also be deployed to the SOA
infrastructure.
3.
Test the deployed SOA composite service using Oracle Enterprise Manager Fusion
Middleware Control Console. Every deployed service has its own test page, so you
can quickly test that the service functions as you expect. For more information
about using the Fusion Middleware Control Console to test deployed SOA
composite applications, see the following chapter:
"Automating Testing SOA Composite Applications" in the Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
39
Invoking Custom Java Code from a SOA
Composite
39
This chapter describes what a SOA composite application needs to do to invoke logic
implemented by a Java class.
When to implement: A SOA composite application needs to invoke logic
implemented by a Java class.
Design Pattern Summary: The logic is accessed using a web service that the SOA
composite component accesses directly. The logic can be placed within an existing
ADF Business Components service, or the Java class can be published as a web service.
Involved components:
Example
Manipulating data.
Calling self-contained Java classes that do not have dependencies on other system
resources.
Calling functions provided by the BPEL service engine, such as adding an
auditTrail component, and so on.
Calling Enterprise JavaBeans.
WARNING: Do not use the bpelx:exec command to access the
application database or a SOAP service.
To access the application database, use a JCA database adapter. To access a SOAP
service, use a BPEL Invoke activity.
For more information about using the bpelx:exec command, see the chapter
"Incorporating Java and Java EE Code in a BPEL Process" in the Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
Another alternative is to call custom Java classes using custom XPath functions. For
more information about using XPath functions to call a Java class, see the sub-section
"Creating User-Defined XPath Extension Functions" in the appendix "XPath Extension
Functions" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
39.3 Example
Download the sample code for this use case from the following location. Oracle SOA
Suite samples.
Generate the service interface for the business component and from the SOA
component, invoke the service through a SOAP binding, as described in
Chapter 36, "Orchestrating ADF Business Components Services."
What You May Need to Know About Invoking Custom Java Code from a SOA Composite
Deploy the SOA composite application to the standalone WLS where the SOA
infrastructure has been installed. Because you created a published event from the
SOA composite application to the ADF Business Components service, the ADF
Business Components service need not to also be deployed to the SOA
infrastructure.
3.
Test the deployed SOA composite service using Oracle Enterprise Manager Fusion
Middleware Control Console. Every deployed service has its own test page, so you
can quickly test that the service functions as you expect. For more information
about using the Fusion Middleware Control Console to test deployed SOA
composite applications, see the following chapter:
"Automating Testing of SOA Composite Applications" in the Oracle Fusion
Middleware Developer's Guide for Oracle SOA Suite.
39.8 What You May Need to Know About Invoking Custom Java Code
from a SOA Composite
If you have already created a business component and the method semantics of the
needed logic fit with the other service methods already implemented in the
application module, you should add another method for the needed logic to the
application module. If the method relies on entity and or view objects on the business
component, then adding the method to the business component is the only approach
available.
If you have not created a business component or the method semantics do not fit with
the other service methods already implemented in the application module, you may
want to create a Java web service instead.
What You May Need to Know About Invoking Custom Java Code from a SOA Composite
40
Managing Tasks from an Oracle ADF
Application
40
This chapter describes what your ADF application needs to do to assign tasks to users
or groups.
When to implement: When your ADF application needs to assign tasks to users or
groups.
Design Pattern Summary: An ADF task flow in a web application contains a page
where a user action invokes an ADF Business Components object that performs some
logic. Because of this user action, a task must be assigned to another user. For example,
an employee uses an ADF web application to submit an expense report. The page used
to create the expense report is within an ADF task flow. When the expense report is
submitted, a task must be raised to the employee's manager so that they can approve
or reject the expense report. To make this happen, when the ADF Business
Components object is invoked, it invokes a BPEL process service component that uses
a human task service component to assign the task to the manager. After the human
task service component is invoked, the manager uses the Worklist application to
complete the task, in this case the approval or rejection of the expense report. The
Worklist application also uses an ADF task flow to present those pages to the manager.
This design pattern uses BPEL so as to enable orchestration after the task is submitted.
Involved components:
ADF web application that includes an ADF Business Components object and an
ADF task flow that contains the UI pages where the end user submits data.
SOA composite with a mediator component that listens for events raised by the
ADF application. The mediator invokes a BPEL service component that uses an
included human task component.
BPEL is not a requirement for working with human tasks.
However, BPEL is used when orchestrating tasks after the end-user
submits the human task, for example to approve or reject forms filled
out by the end-user.
Note:
Instead of using the worklist application, you could use a custom task application or
APIs.
You can do any required validation of the data in the ADF Business Components
layer as opposed to the process.
You can pass only minimal data from the ADF web application into the process.
Using this approach, you can pass just header level information required to route
the task, (for example an expense ID, amount, requester). All other information
remains in the database and is accessed in the task form by reference. The task
form is used to display relevant details to the user. The data is therefore not carried
through the process.
40.3 Example
Following is an example that illustrates the design pattern.
An Expense application contains an ADF task flow used to create an expense report
and submit it for approval. When the user submits the expense report, a BPEL process
service component is invoked that contains a human task service component, which
assigns the task of approving expense report to the user's supervisor. The human task
service component notifies the supervisor that an expense report must be approved.
When the supervisor logs into the Worklist application, he sees notification of an
expense report that requires approval. The Worklist application contains an ADF task
flow that allows the supervisor to either approve or reject the expense report.
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
1.
Create and deploy the ADF web application that contains the UI necessary to
invoke the SOA composite that contains the human work flow.
2.
Create the SOA composite that contains a mediator, BPEL process service
component, and human task component that will assign the task to the user.
3.
Create the ADF task flow based on the human task component. This will provide
the UI necessary for the user to resolve the task.
1.
2.
3.
In the SOA composite application, create a human task service component that
uses the payload of the message received from the mediator service component to
provide any parameters needed to create the task in the workflow.
For detailed procedures on creating a human task service, see the chapter
"Creating Human Tasks" in the Oracle Fusion Middleware Developer's Guide for
Oracle SOA Suite.
When creating the human task service, note the following:
The task will require details about the assignee, task parameters, and so on.
However, you do not need to capture the entire object used to create the task
in the task parameters. You only need to include enough information to make
the assignment decision and to then query the object using the service
interfaces for the ADF Business Components application module.
For example, in the expense report sample application, you might create
parameters for the expense report number, the "submitted by" value, and
optionally the amount. This would be the only information needed to
dynamically assign the task to the submitter's manager.
4.
You can assign tasks statically or dynamically. Make sure that any user to
whom the task is assigned is seeded in the identity management store (for
more information, see Section 40.6, "Securing the Design Pattern").
You should model any email or other notifications as part of the task
metadata. For example, you may want to model an email to the supervisor
when the task is assigned to them and an email to the initiator when the task is
completed. For more information about notifying users of changes to task
status, see the chapter "Creating Human Tasks" in the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
In the BPEL process, add a human task activity and wire it to the human task
service component. In the human task activity, specify which BPEL variables map
to the data required for the task.
After you create the human task activity, a switch statement is automatically
inserted that contains various branches based on the previously specified outcome
Other Approaches
of the human task. Based on how the outcome impacts the specific use case,
additional business logic should be inserted inside the branches.
For example, in the expense report example, you might include a branch that calls
the ADF Business Components object to update the state of the expense report to
Approved. This can be done by exposing the ADF Business Components
application module as a service and then invoking it from BPEL as a SOAP
service. For more information, see Chapter 37, "Manipulating Back-End Data from
a SOA Composite."
5.
Create an ADF task flow based on the human task service component. This will be
the flow used in the worklist application that displays the pages the user views to
complete the task.
For detailed procedures, see the chapter "Creating Human Tasks" in the Oracle
Fusion Middleware Developer's Guide for Oracle SOA Suite.
Note the following:
6.
When creating the task flow, select the .task file created in Step 3. This
automatically generates a task data control that can access the task parameters
and perform actions on the task such as Approve and Reject.
On the JSP pages, use the drop handlers on the task data control to insert
sections such as Task Header, Comments and Attachments, Approval History,
and so on.
Use the ADF Business Components data control to pull in any transactional
data, such as line items. You can use the object id (available in task
parameters) in the query API for the ADF Business Components.
Drag and drop any custom actions (for example, approve or reject) on the
form. You can also include system actions (for example, escalate, reassign,
delegate) on the form.
Note that by default, the first page in the task flow is sent in email
notifications. The buttons on the page are replaced with ReplyTo links for
actions such as Approve and Reject, allowing the user to approve or reject the
object in the task from the email. You can also model a different page for email
approval.
Deploy the SOA composite and the ADF task flow for the human task service to
the standalone WLS where the SOA infrastructure has been installed.
Deploy the task from the application menu and the SOA composite from the
project menu.
Note:
The human task service uses Java platform security (JPS) for accessing user/role
profile information. JPS supports multiple providers, such as XML and XS.
The default authentication provider in Oracle WebLogic Server is WLSAuthenticator,
while the authorization provider is based on the JPS policy store.
The default security configuration uses the Oracle WebLogic Server embedded LDAP
as the identity store and system-jazn-data.xml as the policy store. This configuration
is held in the workflow-identity-config.xml file, as shown in Example 401.
Example 401
Use Oracle Enterprise Manager Fusion Middleware Control Console to view the
SOA composite application and ensure it was properly deployed. For more
information about using Fusion Middleware Control Console, see the chapter
"Deploying SOA Composite Applications" of the Oracle Fusion Middleware
Developer's Guide for Oracle SOA Suite.
3.
Run the ADF application and invoke the method that raises the event.
Alternatively, you can use the Composite initiate page in Enterprise Manager to
send a test message to the BPEL process service component. Note that this
bypasses the mediator service component and directly calls the BPEL process
service component which in turn invokes the human task service component.
The web service ending point for each of the services in the composite is
http://HOST_NAME:PORT/fabric/application name/composite_name/service_name
For example:
http://localhost:8888/fabric/OrderBookingApp/OrderProcessing/Client
4.
View the ADF Business Components runtime log to view the event and payload.
For more information about the log, see the chapter "Testing and Debugging ADF
Components" of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
5.
6.
Log in to the worklist application to view the task created for the supervisor. The
worklist application is located at http://hostname/integration/worklistapp/
Click Approve or Reject to complete this task.
If successful, the status of the task will be updated on the home page the Worklist
application.
7.
In Fusion Middleware Control Console, check that the human task has completed.
This ensures that the waiting BPEL process can proceed with the subsequent steps.
40.8.1 Worklist Notification Locale Does Not Honor the Regional Applications Session
Setting
When logging into the worklist application, both the worklist and human task details
honor the regional setting in the Applications Core session. However, the notification
locale does not honor the regional setting of the Applications Core session.
Login to the worklist application with weblogic as the user. Navigate to the
Administration Tasks tab. This will list all the tasks in the system. Locate the task
that was created and validate the state (it should be ASSIGNED) and the
assignees.
Alternatively, log in to Oracle Enterprise Manager Fusion Middleware Control
Console at http://HOST_NAME:PORT/em and click the instance ID to display an
audit track window. In the audit track view, click the BPEL instance and select the
Flow-Debug tab to display the BPEL audit trail. Check the following values in the
initiateTaskResponse:
Check the following log files and the shell where the server was started to make
sure that there are no errors (for information about logging, see Section 40.8.4,
"Logging").
MW_HOME/user_projects/domains/<domain name>/config/config.xml
MW_HOME/user_projects/domains/soainfra/logs/startsoa.log
MW_HOME/user_projects/domains/soainfra/servers/AdminServer/tmp/_WL_
user/soa-infra/77op2b/war/WEB-INF/application.log
Any exception where the exception stack trace has classes from package
oracle/bpel/services/workflow indicates a workflow exception.
For design time issues, make sure you start JDeveloper using jdev.exe instead of
jdevw.exe in a Windows environment. This brings up a console window in the
background that shows any error messages or stack traces.
If you see any errors during deployment of the ADF task flow, check the
following:
The ADF task flow for the human task service is deployed on the same
instance as the SOA server. If it is deployed to a server without SOA
infrastructure, make sure to correctly follow the steps for deploying task
flows.
Check if the taskflow.properties file exists in your project and has the
following settings:
human.task.lookup.type=LOCAL
Check that all shared libraries are installed to the WLS instance where the task
flow is deployed, including adf.oracle.domain,
adf.oracle.domain.webapp, JSF, JSTL and oracle.soa.workflow or any
shared library specified in weblogic-application.xml. You can verify this by
logging into Oracle WebLogic Server Console as an administrator, and clicking
Deployments.
If you see the task in the task list but you get an error when clicking on the task
title, try the following:
Enable logging for ADF as described in Section 40.8.4, "Logging." Set the log
level to FINE and deploy the task flow again. After you do this, you should
see error messages in the log file.
If you get any errors on the task details screen when performing any
operations, check the following log files:
*
MW_HOME/user_projects/domains/DOMAIN_NAME/servers/ADMIN_SERVER_
NAME/logs/DOMAIN_NAME.logl
MW_HOME/user_projects/domains/DOMAIN_NAME/servers/SERVER_
NAME/logs/SERVER_NAME.log
40.8.4 Logging
You can set logging for the Workflow application and for the ADF task flow.
What You May Need to Know About Managing Tasks from an ADF Application
40.9 What You May Need to Know About Managing Tasks from an ADF
Application
Tasks are linked to the composite instance that created them. When a new version of
the BPEL process service component or workflow service component is deployed, any
existing composite and associated task instances are marked stale. You can clean up
stale composites using Oracle Enterprise Manager Fusion Middleware Control
Console. Cleaning up stale composite instances automatically deletes the associated
task instances as well.
For more information, please refer to the chapter "Managing SOA Composite
Application Instances" in the Oracle Fusion Middleware Administrator's Guide for Oracle
SOA Suite and Oracle Business Process Management Suite.
41
Working with Data from a Remote ADF
Business Components Service
41
This chapter describes what to do when you need to work with data from a remote
Oracle ADF Fusion Business Service in the format of an ADF Business Components
component, such as rendering the data in a UI table, or creating a view link to it.
When to implement: When you need to work with data from a remote Oracle ADF
Fusion Business Service in the format of an ADF Business Components component,
such as rendering the data in a UI table, or creating a view link to it.
Design Pattern Summary: Create service-based entity objects and view objects and
use these entity objects and view objects as normal ADF Business Components either
in your business logic or for rendering on UI pages to simplify the task.
Involved components:
ADF Business Components service that accesses data from a different pillar.
Entity object based on the ADF Business Components service, and view object on
top of the entity object.
41-1
Example
you just need to invoke a method as part of your business logic and you do not need
to bind the input/output of the method to UI components.
41.3 Example
Currently, no example is available.
Create a new entity object using the Create Entity Object wizard.
Note: Instead of using a database schema object for the entity's data
source, select Service Interface. For more information see the section
"Accessing Remote Data Over the Service-Enabled Application
Module" in the chapter "Integrating Service-Enabled Application
Modules" in Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
Example 411
3.
Create a view object on top of the entity object that you created in the previous
step. This step is the same as creating a normal entity object-based view object. For
more information, see the chapter "Defining SQL Queries Using View Objects" in
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
4.
<Reference name="{http://xmlns.oracle.com/apps/adfsvc/deptempService/}DeptEmpService"
className="oracle.jbo.client.svc.Service" xmlns="">
<Factory className="oracle.jbo.client.svc.ServiceFactory"/>
<RefAddresses>
<StringRefAddr addrType="serviceInterfaceName">
<Contents>oracle.apps.adfsvc.deptempService.DeptEmpService</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceEndpointProvider">
<Contents>ADFBC</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiName">
<Contents>DeptEmpServiceBean#oracle.apps.adfsvc.deptempService.DeptEmpService</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaName">
<Contents>DeptEmpService.xsd</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaLocation">
<Contents>oracle/apps/adfsvc/deptempService/</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiFactoryInitial">
<Contents>weblogic.jndi.WLInitialContextFactory</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiProviderURL">
<Contents>t3://localhost:7101</Contents>
</StringRefAddr>
</RefAddresses>
</Reference>
5.
Get the service interface common.jar file from the service provider, and add the
file to your library. This is also required during runtime. The common.jar file is
generated when the service provider uses an ADF Business Component Service
Interface deployment profile to deploy.
41-3
These limitations mean that you cannot create a flattened join of multiple entities if
one of them is a service-based entity object. The workaround is to use a view link to
traverse from one view object to another.
42
Invoking an Asynchronous Service from a
SOA Composite
42
Note:
Figure 421 illustrates the process flow of BPEL process invoking an asynchronous
service.
Other Approaches
The client BPEL process invokes an asynchronous service through the WSDL partner
link. The service runs as required, and returns a response to the waiting client BPEL
process.
Invoke services synchronously. This approach is not supported due to time out
issues.
Invoke services asynchronously, without registering a callback handler service.
This approach is not supported, as a callback handler is required when
asynchronously invoking a service.
Invoke a one-way service. This approach is not supported for Oracle ADF services.
Invoke a service asynchronously, registering another service as the callback
handler. This approach is not supported. Use business events instead.
Caution: These approaches are not supported and should not be
implemented.
42.3 Example
An interface table is populated by third-party entities using legacy interfaces, such as
FTP and files. After the interface table is populated, a periodic Oracle Enterprise
Scheduler job runs, checking for new interface table rows. If the job finds new table
rows, it raises a business event that initiates a BPEL process. The BPEL process
orchestrates any required services such as those used to import and notify users,
obtain necessary approvals, and so on.
In this scenario, one or more services or tasks require several minutes or even hours to
complete, as is typical among asynchronous service interfaces. The BPEL process
invokes the service and enters a dormant state in which the process progress and
variable data are stored in the database, which frees memory and thread resources for
other BPEL processes. When the long-running service completes, the asynchronous
callback revives the process. The BPEL process continues from where it left off.
You can find the sample code for this use case here:
Oracle SOA Suite samples
How to Invoke a SOA Composite Application from Within a SOA Composite Application
2.
Create the service reference to the asynchronous web service you want to invoke.
3.
Populate the BPEL process with scope, invoke, receive, assign and fault-handling
activities.
Before defining the service reference, create your composite and BPEL process with the
requisite input and output payload types. Figure 422 shows an example of a
minimalist composite with a new BPEL process.
Figure 422 Composite Before Web Service Reference Definition
Defining the service reference to the asynchronous web service endpoint involves the
following tasks:
1.
2.
3.
4.
Name: Enter the name of the web service reference for this composite.
Type: Select Reference. A Reference is a service that this composite will be
invoking.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
WSDL URL: Select the full URL to the WSDL of the asynchronous web service
to be invoked. Use the service explorer to navigate to and select the WSDL.
Port Type: Select the execute port type of the end point service. This value is
often automatically defaulted by the UI. This is the port type invoked by the
composite.
Callback Port Type: Select the callback port type of the end point service. This
value is often defaulted automatically by the UI. This is the port type used to
call back the composite.
Figure 423 shows an example of a filled in Create Web Service dialog.
42.4.2 Wiring the BPEL Process to the New Web Service Reference
To invoke a web service, a BPEL process must include a local partner link definition.
You can define a partner link in one of two ways.
Drag the interface pin from the BPEL process to the service reference.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
2.
In the right-hand swim lane of the BPEL process, right-click the area under Partner
Links.
The Create Partner Link dialog is displayed, as shown in Figure 424.
3.
4.
Name: Enter the name of the partner link. This defaults to the service name.
WSDL URL: Enter the full URL for the WSDL file of the asynchronous web
service to be invoked.
Partner Link Type: Enter the service partner link type. This value is
automatically filled in using the service name, as derived from the WSDL
referenced in the WSDL URL field.
Partner Role: From the dropdown list, select the ServiceNameProvider role.
This is the role of the producer service for which you entered the WSDL.
My Role: From the dropdown list, select the ServiceNameRequester role. This
is the role of the BPEL process as the consumer of the asynchronous service.
Alternatively, click and drag the pin from the BPEL component to the service
reference.
a.
Hover the mouse over the BPEL component and the input and output icons.
b.
Drag the input and output icons to the matching icons on the service reference
component, as shown in Figure 425.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
42.4.3 Invoking the Asynchronous Web Service from the BPEL Flow
By default, an asynchronous BPEL flow contains two activities: the receive activity that
starts the process and the invoke activity that initiates the callback response.
Asynchronous services do not throw faults, such that they must always return a valid
payload whenever possible. In the event of a business failure at the endpoint service,
services should return a payload that contains a failed status.
Invoking the asynchronous web service from the BPEL flow involves the following
steps:
1.
2.
Add a scope activity to include the asynchronous service invocation and variable
assignment activities.
3.
Add fault handlers to trap any system failures that may occur during any activities
within a scope, so as to permit logging, incident creation and error management as
required by the use case. Asynchronous services do not throw WSDL-defined
faults, necessitating a fault handler.
4.
Add logging. All BPEL processes within Oracle Fusion web applications are
required to implement translatable, tokenized, message-level logging for
fault-handling scenarios.
5.
6.
Invoke: This activity defines the partner link and invoke operation, and
defines the BPEL variable containing the payload to be submitted.
b.
Receive: This activity defines the partner link and operation to be invoked,
and defines the variable to store the response payload when the asynchronous
callback is made.
c.
Assign (1): The first assign activity copies BPEL process input data, XML
fragments and XPath expression results to the payload that is sent to the
asynchronous service.
d.
Assign (2): The second assign activity copies the contents of the asynchronous
response payload to the BPEL output variable, which is then sent back to the
calling process.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
2.
3.
Scope: By default, the main BPEL flow is the top-level scope of the process.
However, should any of the activities generate a fault within that scope,
compensation or recovery options are limited. Leverage nested scopes to
contain errors and implement resilient functionality.
Fault Handlers: Each nested and top-level scope should have qualified and
catch-all fault handlers to catch business- or system-level faults and respond
accordingly to the use case.
Logging: Add assign activities as needed. Alternatively, add copy operations
to pre-existing assign activities to implement logging.
In the Composite Editor, double-click the BPEL component to open the BPEL
process editor.
b.
Drag a new scope activity onto the process and name according to the
activities it will contain, for example, InvokeAsyncServiceName.
c.
To the scope activity, add the service invocation and variable assignment
activities.
Add a catch-all fault handler to trap any errors that may occur during assign,
invoke, receive or dehydration activities that may occur within the scope. Use
either of the following:
Reply Normally: Returns a payload with an error status and completes in all
cases.
Wait State: Sends the asynchronous response, which then sends a user
notification or updates an Oracle ADF record, and enters a correlated wait
state. The wait state allows another entity to invoke the in-flight process that
provides additional instructions.
4.
5.
Define an invoke activity for the asynchronous web service. In the scope
previously defined, drag an Invoke activity to the flow.
6.
Double-click the activity. In the Invoke Activity dialog, enter the following
information.
Partner Link: Select a partner link from the list of partner links that were
previously defined in the BPEL process metadata. To select a partner link,
browse through the expanded list of partner links for the asynchronous
service defined earlier.
Operation: Select an operation from the list of all the available synchronous
and asynchronous operations defined on the web service of the partner link.
Be sure to select the relevant asynchronous operation.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
Note:
For Oracle ADF Services, the operation names end with Async.
Input: Click the Add button to create a scope-local variable to contain the
payload intended for the asynchronous service invocation.
7.
Define a receive activity to handle the asynchronous callback from the endpoint
service, and store the response payload in a variable for use by the process. Drag a
receive activity immediately following the invoke activity.
8.
Partner Link: Select a partner link from the list of partner links that were
previously defined in the BPEL process metadata. To select a partner link, click
the Browse button and browse through the expanded list of partner links for
the asynchronous service defined earlier.
Operation: Select an operation from the list of all the available synchronous
and asynchronous operations defined on the partner link's web service. Be
sure to select the appropriate asynchronous callback operation.
Variable: Click the Add button to define a scope-local variable to contain the
payload received from the asynchronous service invocation.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
9.
Drag an assign activity onto the flow (within the scope) just above the invoke
activity you created earlier. Drag a second assign activity onto the flow just below
the receive activity you created earlier.
Double-click the activity, click the General tab and enter a meaningful name such
as AssignInputforAsync<ServiceName> or CopyOutputfrom<ServiceName>.
11. Select the Copy Operation tab and click the Add button to open the Create Copy
Operation dialog.
In the Create Copy Operation dialog, select Copy Operation.
12. Depending on the type of data you want to assign to the invoke input variable,
Variable: Select the contents of an element from the source variable, such as
the default BPEL inputVariable, as shown in Figure 428.
How to Invoke a SOA Composite Application from Within a SOA Composite Application
Figure 429
How to Invoke a SOA Composite Application from Within a SOA Composite Application
Note:
Figure 4210
Partner Link: The contents and properties of a Partner Link (useful for
dynamic partner links).
42.4.4 What Happens When You Invoke an Asynchronous Service from within a SOA
Composite Application
Defining the web service reference generates a local, abstract WSDL (.wsdl) file named
after the service for which it was created. This WSDL file contains partner link
information used by BPEL, as well as a reference to the asynchronous web service
WSDL URL for looking up message type and schema information. Typically, the
WSDL file name is the same as the service name, with the suffix .wsdl appended at the
end.
Note:
You will see a list of all successfully deployed composites in this SOA
environment.
2.
Click the service endpoint link beneath the name of the deployed composite. This
renders the service test client page, which then can be used to enter payload data
and invoke the composite.
3.
4.
5.
Login to Oracle Enterprise Manager Fusion Middleware Control Console and take
the following actions.
a.
b.
Expand the soa-infra node for the correct SOA server and select the name of
the deployed composite.
What You May Need to Know About Invoking an Asynchronous Service from Another SOA Composite
c.
Click the instance ID link for the most recent instance of this composite. The
Flow Trace window displays.
d.
In the Flow Trace window, find the entry for your BPEL process component.
Click the BPEL process component to open the Audit Flow view.
The Audit Flow view displays the activities that were executed in the BPEL
process, along with payload details that you can view by clicking the activity.
42.7.1 Deployment
If failures occur during compilation or deployment, observe the Oracle JDeveloper
console and compiler output to resolve any issues.
If deployment is successful but the composite does not display in the soa-infra
composites list, check the server's diagnostic log and console output for any exceptions
and resolve them.
42.7.2 Runtime
If faults occur when invoking the composite, the logging activities and fault-handling
branches should provide meaningful content in the applications diagnostic log
(defined in logging.xml) or be present in the callback payload.
Use the Audit Flow view to diagnose the problem and correct your BPEL process, then
redeploy. For more information about using the Audit Flow view, see the deployment
steps in Section 42.6, "Verifying the Deployment."
What You May Need to Know About Invoking an Asynchronous Service from Another SOA Composite
43
Synchronously Invoking an ADF Business
Components Service from an Oracle ADF
Application
43
This chapter describes what to do when you need to invoke an ADF Business
Components service either from an ADF Business Components object or from a UI.
Use only with synchronous processes with an immediate response.
When to implement: When you need to invoke an ADF Business Components service
either from an ADF Business Components object or from a UI. Use only with
synchronous processes with an immediate response.
Design Pattern Summary: Use ServiceFactory to generate a dynamic proxy to the
target ADF Business Components service, then use the proxy to invoke the desired
service method.
Involved components:
Using JAX-WS generates many proxy classes that you need to maintain, which
increases maintenance costs.
oracle.jbo.client.svc.ServiceFactory uses a local Java call if the service is
co-located, which offers performance benefits.
Example
43.3 Example
Currently, no example is available.
Note:
2.
Example 431
<Reference
name="{http://xmlns.oracle.com/apps/adfsvc/deptempService/}DeptEmpService"
className="oracle.jbo.client.svc.Service" xmlns="">
<Factory className="oracle.jbo.client.svc.ServiceFactory"/>
<RefAddresses>
<StringRefAddr addrType="serviceInterfaceName">
<Contents>oracle.apps.adfsvc.deptempService.DeptEmpService</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceEndpointProvider">
<Contents>ADFBC</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiName">
<Contents>DeptEmpServiceBean#oracle.apps.adfsvc.deptempService.DeptEmpService
</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaName">
<Contents>DeptEmpService.xsd</Contents>
</StringRefAddr>
<StringRefAddr addrType="serviceSchemaLocation">
<Contents>oracle/apps/adfsvc/deptempService/</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiFactoryInitial">
<Contents>weblogic.jndi.WLInitialContextFactory</Contents>
</StringRefAddr>
<StringRefAddr addrType="jndiProviderURL">
<Contents>t3://localhost:7101</Contents>
</StringRefAddr>
How to Invoke an ADF Business Components Service from an Oracle ADF Application
</RefAddresses>
</Reference>
3.
Get the service interface common JAR file from the service provider and add it to
your library.
This file is required during runtime. The common JAR file is generated when the
service provider uses a ADF Business Components service interface deployment
profile for deployment.
For more information, see the chapter "Integrating Service-Enabled Application
Modules" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
4.
Example 432
In your ADF Business Components service or managed Java bean class, invoke the
desired service using ServiceFactory, as shown in Example 432.
ServiceFactory Code
OrganizationService svc =
(OrganizationService)ServiceFactory.getServiceProxy(OrganizationService.NAME);
List orgs = new ArrayList(2);
Org org1 = (Org)DataFactory.INSTANCE.create(Org.class);
org1.setOrganizationId(new Long(10000));
org1.setOrgName("OrgName");
org1.setName("TranslatedName");
org1.setDescription("Your org Description"); //... and set more attributes
orgs.add(org1);
svc.processOrganizatiion("Merge", orgs, null);
Query Samples
// Retrieve only Dname, Loc from Dept and exclude Empno from Emp.
DeptEmpService mSvc = (DeptEmpService)ServiceFactory.getServiceProxy(DeptEmpService.NAME);
FindCriteria fc = (FindCriteria)DataFactory.INSTANCE.create(FindCriteria.class);
List l = new ArrayList();
l.add("Dname");
l.add("Loc");
l.add("Emp");
fc.setFindAttribute(l);
List cfcl = new ArrayList();
ChildFindCriteria cfc =
(ChildFindCriteria)DataFactory.INSTANCE.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
List cl = new ArrayList();
cl.add("Empno");
cfc.setFindAttribute(cl);
cfc.setExcludeAttribute(true);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult res = mSvc.findDept(fc, null);
// Exclude PurchaseOrderLine from PurchaseOrder.
PurchaseOrderService svc =
(PurchaseOrderService )ServiceFactory.getServiceProxy(PurchaseOrderService .NAME);
FindCriteria fc = (FindCriteria)DataFactory.INSTANCE.create(FindCriteria.class);
List l = new ArrayList();
fc.setExcludeAttribute(true);
l.add("PurchaseOrderLine");
Synchronously Invoking an ADF Business Components Service from an Oracle ADF Application 43-3
fc.setFindAttribute(l);
PurchaseOrderResult res = svc.findPurchaseOrder(fc, null);
// Retrieve only the 2nd Emp along with Dept with Deptno=10.
FindCriteria fc = (FindCriteria)DataFactory.INSTANCE.create(FindCriteria.class);
// Create the view criteria item.
List value = new ArrayList();
value.add(new Integer(10));
ViewCriteriaItem vci =
(ViewCriteriaItem)DataFactory.INSTANCE.create(ViewCriteriaItem.class);
vci.setValue(value);
vci.setAttribute("Deptno");
List<ViewCriteriaItem> items = new ArrayList(1);
items.add(vci);
// Create view criteria row.
ViewCriteriaRow vcr = (ViewCriteriaRow) DataFactory.INSTANCE.create(ViewCriteriaRow.class);
vcr.setItem(items);
// Create the view criteria.
List group = new ArrayList();
group.add(vcr);
ViewCriteria vc = (ViewCriteria)DataFactory.INSTANCE.create(ViewCriteria.class);
vc.setGroup(group);
// Set filter.
fc.setFilter(vc);
List cfcl = new ArrayList();
ChildFindCriteria cfc =
(ChildFindCriteria)DataFactory.INSTANCE.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
cfc.setFetchStart(1);
cfc.setFetchSize(1);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult dres = svc.findDept(fc, null);
pw.println("### Dept 10 and 2nd Emp ###");
44
Implementing an Asynchronous Service
Initiation with Dynamic UI Update
44
Oracle ADF UI
ADS
JMS
SOA Mediator
SOA BPEL
44-1
44.3 Example
The following is an example that illustrates the design pattern.
In an order workbench, an end user selects an order and submits it to a scheduling
system for fulfillment. The scheduling system services take several seconds to several
minutes to acknowledge scheduling and when the user clicks the button to initiate the
scheduling process, must be notified in the UI upon successful scheduling for
fulfillment without the need to repeatedly refresh the page by hand.
In this implementation, entering the UI data and clicking Schedule programmatically
raises a business event, initiates a BPEL process which goes through processing and
approvals as needed, then finally invokes an order ADF Business Components service
to complete the process and publish the JMS message to trigger the ADS UI update.
2.
The BPEL process updates the database and submits Oracle Enterprise Scheduler
jobs.
3.
At the end of the BPEL process, a web service is invoked to publish the message.
4.
5.
6.
Figure 441 Technology Flow Diagram (with Optional Oracle Enterprise Scheduler Job
Submission)
This procedure assumes that the JMS Module does not already
exist.
1.
In the Oracle WebLogic Server Console, navigate to Messaging > JMS Modules.
2.
3.
4.
In the Targets panel, choose the AdminServer target and click Next.
5.
Choose "Would you like to add resources to this JMS system module?" and click
Finish.
6.
7.
8.
9.
Click Finish.
10. Verify the new connection factory in the Summary of Resources table and click
New.
11. Choose Queue and click Next.
12. Name the queue FusionAppsADSJMSQueue, provide the JNDI name
44-3
DemoDataChangeEntry.java
package ads.demo.common;
import java.io.Serializable;
public class DemoDataChangeEntry implements Serializable {
public enum ChangeType
{
/**
* Indicates the change is row value updates
*/
UPDATE,
/**
* Indicates the change is a new row insertion
*/
INSERT,
/**
* Indicates the change is a new row insertion before a row
*/
INSERT_BEFORE,
/**
* Indicates the change is a new row insertion after a row
*/
INSERT_AFTER,
/**
* Indicates the change is a new row insertion inside a parent
*/
INSERT_INSIDE,
/**
* Indicates the change is row deletion
*/
REMOVE,
/**
* Indicates the change is range refresh
*/
REFRESH
}
public DemoDataChangeEntry() {
super();
}
public DemoDataChangeEntry(Object[] pk, ChangeType type,
String[] attributes, Object[] values) {
_pk = pk;
_type = type;
_attributes = attributes;
_values = values;
}
private
private
private
private
Object[] _pk;
ChangeType _type;
String[] _attributes;
Object[] _values;
DemoDataUpdateEvent.java
package ads.demo.common;
import java.io.Serializable;
import java.util.List;
public class DemoDataUpdateEvent implements Serializable {
public DemoDataUpdateEvent() {
}
public DemoDataUpdateEvent(List<DemoDataChangeEntry> entries) {
_entries = entries;
}
private List<DemoDataChangeEntry> _entries;
public List<DemoDataChangeEntry> getEntries() {
return _entries;
}
44-5
JMSHelper.java
package ads.demo.common;
import java.util.Hashtable;
import
import
import
import
import
import
javax.jms.JMSException;
javax.jms.MessageListener;
javax.jms.ObjectMessage;
javax.jms.Queue;
javax.jms.QueueConnection;
javax.jms.QueueConnectionFactory;
import javax.jms.QueueReceiver;
import javax.jms.QueueSender;
import javax.jms.QueueSession;
import javax.jms.Session;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
public final class JMSHelper {
private static JMSHelper _instance = new JMSHelper();
public static JMSHelper getInstance() {
return _instance;
}
public ObjectMessage createObjectMessage() throws JMSException {
return qsession.createObjectMessage();
}
public void sendMessage(ObjectMessage message) throws JMSException {
qsender.send(message);
}
public QueueReceiver createQueueReceiver(MessageListener listener,
String messageFilter) throws JMSException {
QueueReceiver qreceiver = qsession.createReceiver(queue, messageFilter);
qreceiver.setMessageListener(listener);
return qreceiver;
}
private JMSHelper() {
try {
init();
} catch (Exception e) {
e.printStackTrace();
}
}
// Defines the JMS context factory.
QueueConnectionFactory qconFactory;
QueueConnection qcon;
QueueSession qsession;
QueueSender qsender;
Queue queue;
/**
* Creates all the necessary objects for sending
* messages to a JMS queue.
*
* @param ctx JNDI initial context
* @param queueName name of queue
* @exception NamingException if operation cannot be performed
* @exception JMSException if JMS fails to initialize due to internal error
*/
private void init()
throws NamingException, JMSException
{
InitialContext ctx = new InitialContext();
qconFactory = (QueueConnectionFactory) ctx.lookup(JMS_QUEUE_FACTORY);
qcon = qconFactory.createQueueConnection();
qsession = qcon.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
queue = (Queue) ctx.lookup(ADS_QUEUE);
qsender = qsession.createSender(queue);
qcon.start();
}
/**
* Closes JMS objects.
* @exception JMSException if JMS fails to close objects due to internal error
*/
private void close() throws JMSException {
qsender.close();
qsession.close();
qcon.close();
}
}
44-7
2.
3.
package ads.demo.view;
import ads.demo.common.DemoDataChangeEntry;
import ads.demo.common.DemoDataUpdateEvent;
import ads.demo.common.JMSHelper;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageListener;
import javax.jms.ObjectMessage;
import javax.jms.QueueReceiver;
import oracle.adf.model.binding.DCBindingContainer;
import oracle.adf.model.binding.DCIteratorBinding;
import oracle.adf.share.ADFContext;
import oracle.adf.view.rich.event.ActiveDataEntry;
import oracle.adf.view.rich.event.ActiveDataListener;
import oracle.adf.view.rich.event.ActiveDataUpdateEvent;
import oracle.adf.view.rich.model.ActiveDataModel;
import oracle.adfinternal.view.faces.model.binding.FacesCtrlHierBinding;
import oracle.jbo.Key;
import org.apache.myfaces.trinidad.model.CollectionModel;
...
public class ActiveDataCollectionModel extends CollectionModel implements ActiveDataModel,
...
public void startActiveData(Collection<Object> rowKeys,
int startChangeCount,
ActiveDataListener listener) {
_listeners.add(listener);
_currEventId = startChangeCount;
if (_listeners.size() == 1) {
// register as receiver for JMS Queue, listening to change event
try {
String messageFilter = "JMSCorrelationID = '" + getUuid() + "'";
qreceiver = JMSHelper.getInstance().createQueueReceiver(this,
messageFilter);
} catch (Exception e) {
e.printStackTrace();
}
}
}
public void stopActiveData(Collection<Object> rowKeys,
ActiveDataListener listener) {
_listeners.remove(listener);
if (_listeners.isEmpty()) {
// clean JMS
try {
qreceiver.close();
} catch (JMSException e) {
e.printStackTrace();
}
}
}
public int getCurrentChangeCount() {
return _currEventId;
}
public void onMessage(Message message) {
try {
DemoDataUpdateEvent myEvent = null;
if (message instanceof ObjectMessage) {
myEvent =
(DemoDataUpdateEvent)((ObjectMessage)message).getObject();
// Convert the event to ADS DataChangeEvent
}
List<ActiveDataEntry> dces = new ArrayList<ActiveDataEntry>(1);
for (DemoDataChangeEntry entry : myEvent.getEntries()) {
oracle.jbo.Key jboKey = new Key(entry.getPk());
ActiveDataEntry.ChangeType newType = convertChangeType(entry.getType());
Object[] path = new Object[] { Collections.singletonList(jboKey) };
ActiveDataEntry dce =
new DemoActiveDataEntry(newType, path,
new Object[0],
entry.getAttributes(),
entry.getValues());
dces.add(dce);
}
_currEventId++;
ActiveDataUpdateEvent event = new DemoActiveDataUpdateEvent(new Object(), _currEventId,
dces);
_refreshControl = true;
// Deliver event
for (ActiveDataListener listener : _listeners) {
try {
listener.dataChanged(event);
} catch (Throwable e) {
e.printStackTrace();
}
}
} catch (Exception e) {
44-9
e.printStackTrace();
}
}
private int _currEventId = 0;
private final List<ActiveDataListener> _listeners =
new LinkedList<ActiveDataListener>();
private boolean _refreshControl = false;
private String _treeBindingName;
private String _iterBindingName;
private ActiveDataEntry.ChangeType
convertChangeType(DemoDataChangeEntry.ChangeType
type) {
if (type == DemoDataChangeEntry.ChangeType.UPDATE) {
return ActiveDataEntry.ChangeType.UPDATE;
} else if (type == DemoDataChangeEntry.ChangeType.REFRESH) {
return ActiveDataEntry.ChangeType.REFRESH;
} else {
return ActiveDataEntry.ChangeType.UPDATE;
}
// Return ActiveDataEntry.ChangeType.UPDATE;
}
private CollectionModel getModel() {
CollectionModel cm =
(CollectionModel)ADFContext.getCurrent().getRequestScope().get("collectionModel_" +
this.hashCode());
DCBindingContainer bindings =
(DCBindingContainer)ADFContext.getCurrent().getRequestScope().get("bindings");
if (_refreshControl) {
DCIteratorBinding iterBinding =
bindings.findIteratorBinding(_iterBindingName);
iterBinding.executeQuery();
_refreshControl = false;
}
if (cm == null) {
FacesCtrlHierBinding hierBinding =
(FacesCtrlHierBinding)bindings.findCtrlBinding(_treeBindingName);
cm = hierBinding.getCollectionModel();
ADFContext.getCurrent().getRequestScope().put("collectionModel_" +
this.hashCode(), cm);
}
return cm;
}
...
There are two reasons for implementing the getModel() method this way:
package ads.demo.view;
import java.util.HashMap;
import java.util.Map;
import oracle.adf.view.rich.event.ActiveDataEntry;
public class DemoActiveDataEntry extends ActiveDataEntry {
public DemoActiveDataEntry(ActiveDataEntry.ChangeType change,
Object[] path, Object[] insertKeyPath,
String[] names, Object[] values) {
super();
if (names != null) {
44-11
package ads.demo.view;
44-12 Developer's Guide
import java.util.Collections;
import java.util.List;
import oracle.adf.view.rich.event.ActiveDataEntry;
import oracle.adf.view.rich.event.ActiveDataUpdateEvent;
public class DemoActiveDataUpdateEvent extends ActiveDataUpdateEvent {
public DemoActiveDataUpdateEvent(Object object) {
super(object);
}
public DemoActiveDataUpdateEvent(Object source, int eventId,
List<ActiveDataEntry> changeList)
{
super(source);
_changeList = changeList;
_eventId = eventId;
}
/**
* Get the change list of this event
*
* @return the change list of this event
*/
public List<ActiveDataEntry> getChangeList()
{
return _changeList;
}
/**
* Get the event ID
* Return the event ID
*/
public int getEventId()
{
return _eventId;
}
public long getEventTime()
{
return System.currentTimeMillis();
}
public String toString()
{
return super.toString() + " eventId:" + _eventId + " changeList:" + _
changeList;
}
private List<ActiveDataEntry> _changeList =
private int _eventId = 0;
Collections.emptyList();
44.4.3 Registering the Active Data Collection Model with the Oracle ADF UI Page
To enable the active data feature and "hook" your collection model, you need to
register the class as a managed JavaBean.
44-13
ADS requires UI components to have the same model across requests. Therefore,
register the ActiveDataCollectionModel as a view scoped managed JavaBean. If you
stay on the same page, the table is based on the same model.
To register your collection model as a managed JavaBean:
1. Open adfc-config.xml.
2.
Add the managed JavaBean named adsBean and provide the package to your
collection model class, as shown in Example 448.
Example 448
<managed-bean>
<managed-bean-name>adsBean</managed-bean-name>
<managed-bean-class>ads.demo.view.ActiveDataCollectionModel</managed-bean-class>
<managed-bean-scope>view</managed-bean-scope>
<managed-property>
<property-name>treeBindingName</property-name>
<property-class>java.lang.String</property-class>
<value>EmpView1</value>
</managed-property>
<managed-property>
<property-name>iterBindingName</property-name>
<property-class>java.lang.String</property-class>
<value>EmpView1Iterator</value>
</managed-property>
</managed-bean>
44.4.4 Registering the Component Managed JavaBean for Supporting Method Actions
To trigger the synchronous functionality of the use case pattern, raise a business event
in response to the click of an Oracle ADF button. To support a response to the click of a
button, create a managed JavaBean with which you can associate methods as the
action for these buttons.
To build your Oracle ADF component managed JavaBean:
In the prototype use case, there is a table that contains a list of employees and their
entity object attributes. Add two buttons at the top of the table in a panel collection
toolbar which, when clicked, uses the selected employee to initiate an approval
process. When completed, the approval process dynamically updates the table, as
shown in Figure 442.
The table component requires the managed JavaBean shown in Example 449.
Example 449
package ads.demo.view;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Map;
import javax.faces.application.FacesMessage;
import javax.faces.context.FacesContext;
import javax.faces.event.ActionEvent;
import
import
import
import
oracle.adf.model.OperationBinding;
oracle.adf.model.binding.DCBindingContainer;
oracle.adf.share.ADFContext;
oracle.adf.view.rich.component.rich.data.RichTable;
import oracle.jbo.Key;
import org.apache.myfaces.trinidad.model.RowKeySet;
public class TableHandlerBean {
private RichTable _table;
public TableHandlerBean() {
super();
}
public void setTable(RichTable _table) {
this._table = _table;
}
public RichTable getTable() {
return _table;
}
44-15
FacesContext.getCurrentInstance().addMessage(null, msg);
}
}
44.4.6 Creating the Data Model and Adding Application Module Methods
The data model should exist before the page is built to simplify laying out the
components required to display the data contained in that model. The application
module needs additional methods to support incoming service methods and,
optionally, the methods for raising the business event.
For more information about creating a data model with application modules, see the
chapter "Implementing Business Services with Application Modules" in Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
.
44-17
To extend the methods of your application module for the service interface:
Make sure to expose one or more application module methods in the application
module service. This facilitates the callback from BPEL upon completion of the
process, triggering the ADS UI update. These methods publish the message to the JMS
queue following the message structure shown here.
The message payload should take the format of DataUpdateEvent, which comprises
one or more DataChangeEntry items.
key: Object[]
insertKey: Object[]
In this pattern, payRaise and payCommision are supported for one or more selected
employees. Use methods with simple string interfaces invoked by BPEL to complete
the payRaise or payCommision event for each particular employee. Call the
sendMessage method to publish the JMS message to notify ADS of the UI update.
Sample BPEL methods are shown in Example 4412.
Example 4412 BPEL Methods
// Simplified interface method for service call per employee
public void performSingleRaise(String correlationId, String key) {
ArrayList thelist = new ArrayList<String>();
thelist.add(key);
performRaise(correlationId, thelist);
} //
44-19
new event type and a conditional branch in BPEL. If the pattern requires completely
separate event definitions, the code becomes more complex, the number of managed
metadata source files increases, and the composite becomes more complex as well.
While this is a simpler approach, it is not as flexible from an integration perspective.
Define your event types such that they support your current use case and potentially
support additional integration in the future. Example 4413 shows a simplified event
definition, while Example 4414 shows an event schema definition.
Example 4413 Simplified Event Definition
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions xmlns="http://schemas.oracle.com/events/edl"
targetNamespace="http://xmlns.oracle.com/apps/ta/adsdemo/events/edl">
<schema-import namespace="http://xmlns.oracle.com/apps/ta/adsdemo/events/schema"
location="xsd/ADSDemoEventSchema.xsd"/>
<event-definition name="ADSDemoEvent">
<content xmlns:ns0="http://xmlns.oracle.com/apps/ta/adsdemo/events/schema"
element="ns0:ADSDemoEventElement"/>
</event-definition>
</definitions>
Example 4414 Event Schema Definition
<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/apps/ta/adsdemo/events/schema"
targetNamespace="http://xmlns.oracle.com/apps/ta/adsdemo/events/schema"
attributeFormDefault="unqualified"
elementFormDefault="qualified">
<xsd:element name="ADSDemoEventElement" type="ADSDemoEventElementType"/>
<xsd:complexType name="ADSDemoEventElementType">
<xsd:sequence>
<xsd:element name="correlationId" type="xsd:long"/>
<xsd:element name="key" type="xsd:long"/>
<xsd:element name="eventType" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Note:
44-21
2.
Open the UI page and interact with the UI components that you designed to
trigger the event.
The event should immediately display in the EDN-DB-LOG page.
3.
</content>
</business-event>
4.
5.
6.
If your process has no errors and is expecting a response from the human
workflow notification, do the following:
a.
b.
c.
At this point, the BPEL process should complete and invoke the ADF Business
Components service to trigger the ADS push. The UI should promptly update. Check
the Oracle ADF UI runtime console and diagnostic logs for stack traces and log
messages.
44-23
What You May Need to Know About Initiating an Asynchronous Service with Dynamic UI Update
For the SOA functionality, use the Oracle Enterprise Manager console for diagnostics
and Oracle Fusion Applications Logger sensor variables for logging.
For the ADF Business Components service functionality, use BPEL fault handling and
logging via Oracle Fusion Applications Logger sensor variables as well as the console,
Oracle Fusion Applications Logger and server diagnostic logs for more detailed error
messages.
Oracle ADF UI
ADS
JMS
SOA Mediator
SOA BPEL
45
Managing Tasks Programmatically
45
This chapter describes what to do when you need to programmatically create, set an
outcome for, or query task information that resides in one or more SOA domains.
When to implement: When you need to programmatically create, set an outcome for,
or query task information that resides in one or more SOA domains.
Design Pattern Summary: The design pattern involves programmatic interaction with
human task client services by an application with the following requirements:
displaying task status information, providing UI facets to enable setting task outcomes
without navigating through the worklist, and submitting new tasks without initiating
a BPEL process.
In addition, the human task services support federated task queries across several
SOA domains so as to obtain an aggregated task list across several product families.
Involved components:
Potential Approaches
Oracle Fusion Middleware Extensions for Applications maintains the list of servers in
the taxonomy tables. An API enables building the JAXB object based on the list of SOA
domains in the Oracle Fusion Applications topology.
This pattern is recommended as it provides the following features:
45.3 Example
The Expenses team has an Expenses Manager role with administrator privileges to
approve or reject expenses that belong to other users. The Expenses team must provide
a workbench that collectively scans all SOA domains for open expense notifications
and provide a consolidated UI to set their outcome, potentially all at once. This UI
would comprise a table listing notifications matching certain filter criteria with buttons
to select and set the appropriate outcome of the expense. This is done through RMI
interaction with the appropriate SOA domain.
Create and deploy a human task definition using a SOA composite that contains
the human task.
Develop code to do the following:
Note:
Task Service: The task service programmatically sets a task outcome, such as
approve or reject for a single, particular task using a single, particular SOA
runtime.
Task Query Service: The task query service programmatically queries tasks for a
particular task type. Use the portlet to render a worklist and relevant tasks in your
dashboard. Alternatively, you may manually build the worklist instead.
Federated Task Query Service: The federated task query service programmatically
executes a federated query of tasks for a particular task type. Use the portlet to
render a worklist and relevant tasks in your dashboard. Alternatively, you may
manually build the worklist instead.
Use the following guidelines to determine the type of task or query service to use.
Single server task service API: Use this API to obtain a single task object using the
task number or task ID from a single, specific SOA runtime.
Single server task query service API: Use this API to query for tasks from a
single, specific SOA runtime.
Federated task query service API: Use this API to query tasks based on
namespace or task name from one or more SOA runtime domains.
Applications Core: Add this library to enable using Oracle Fusion Middleware
Extensions for Applications taxonomy APIs to obtain the necessary JAXB object
containing the RMI endpoint information for the desired server.
SOA Runtime: Add this library to enable using the human workflow task query
APIs.
Importing Code Packages to Enable Using the Single Server Task Service API
import java.util.ArrayList;
import java.util.List;
import java.util.logging.Logger;
import javax.jws.WebService;
import oracle.bpel.services.workflow.verification.IWorkflowContext;
import oracle.bpel.services.workflow.client.IWorkflowServiceClient;
import oracle.bpel.services.workflow.task.model.Task;
import
import
import
import
import
import
import
import
import
oracle.bpel.services.workflow.IWorkflowConstants;
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory;
oracle.bpel.services.workflow.query.ITaskQueryService;
oracle.bpel.services.workflow.repos.Ordering;
oracle.bpel.services.workflow.repos.Predicate;
oracle.bpel.services.workflow.repos.TableConstants;
oracle.bpel.services.workflow.task.IInitiateTaskResponse;
oracle.bpel.services.workflow.task.ITaskService;
oracle.bpel.services.workflow.task.model.ObjectFactory;
import oracle.apps.fnd.applcore.common.DeploymentsUtil;
import oracle.bpel.services.workflow.client.config.RemoteClientType;
import oracle.bpel.services.workflow.client.config.ServerType;
import oracle.bpel.services.workflow.client.config.WorkflowServicesClientConfigurationType;
// Get the workflow task service context for use in later calls for performance
// improvement
wfCtx = querySvc.getWorkflowContextForAuthenticatedUser();
Note:
45.4.2.5 Obtain the Single Task Object and Set Task Outcome
When interacting with the task service, you must first obtain the task number or ID for
the task to retrieve the task details. Use the task number or task ID to invoke the
getTaskDetailsById or getTaskDetailsByNumber methods of the task query service
object.
Note: This approach assumes that you have obtained the task
number or task ID (either through the task query service or
otherwise).
Task t = querySvc.getTaskDetailsById(wfCtxt,
"0a6d287a-9849-4e5e-914b-805706d6b9d9");
taskSvc.updateTaskOutcome(wfCtxt, t, "APPROVE");
// Another example, using the task number to reject a task.
Task t = querySvc.getTaskDetailsByNumber(wfCtxt, 200140 );
taskSvc.updateTaskOutcome(wfCtxt, t, "REJECT");
Example 455 shows how to use STDOUT calls to display the various task attributes
through the task API.
Example 455
45.4.3 How to Use the Single Server Task Query Service API
If your use case involves connecting to a single SOA domain and querying for all tasks
that match certain criteria, take the following steps. After you have queried for the
relevant tasks, you can display them in an ordered list in the UI or programmatically
set task outcome all at once.
45.4.4 How to Use the Federated Server Task Query Service API
Using the federated server task query service API involves the following main steps:
Declare task and query service references, and create the workflow client service
object.
import oracle.bpel.services.workflow.fws.client.IFederatedWorkflowContext;
Note:
Example 458 shows sample code in which a list of servers is created for a parallel
federated query.
Example 458
45.4.4.4 Declare Task and Query Service References and Create the Workflow
Client Service Object
After constructing the server list, obtain the query service object reference by invoking
the getFederatedTaskQueryService API of the WorkflowServiceClientFactory, as
shown in Example 459.
Example 459 Declaring Task and Query Service References and Creating the Workflow
Client Service Object
java.util.logging.Logger logger = Logger.getLogger("oracle.apps");
WorkflowServicesClientConfigurationType wscct =
getWorkflowClientConfigObject("FIN_SOA_RMI");
if ( wscct == null ) {
// Log Incident
return "FAILED!";
}// if
querySvc = WorkflowServiceClientFactory.getFederatedTaskQueryService(wscct,
requestedServers, logger);
45.4.5 How to Query and Traverse Federated and Non-federated Query Result Sets
Querying and traversing federated and non-federated query result sets involves the
following main steps:
Construct a list of OptionalInfo items for the results of the queryTasks() method.
ons.ExtFunc"
xmlns:task="http://xmlns.oracle.com/bpel/workflow/task"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/bpel/workflow/taskDefinition"
xmlns:evidence="http://xmlns.oracle.com/bpel/workflow/TaskEvidenceService"
xmlns:dvm="http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue"
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:ns0="http://xmlns.oracle.com/bpel/workflow/common"
xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath"
xmlns:tsc="http://xmlns.oracle.com/bpel/workflow/common/tsc"
xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.tip.xref.xpath.XRefXPa
thFunctions"
xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
xmlns:mhdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.mediator.service.c
ommon.functions.GetRequestHeaderExtnFunction">
<name>Humantask1</name>
...
This query results in the WFTASKMETADATA row, shown in Table 451 and Table 452.
Table 451
ID
URI
Name
Title
Component
Name
default/SOAComposite1!1.0 default/SOAComposite1!
1.0*2008-12-02_
*2008-12-02_08-32-41_
08-32-41_
642/Humantask1
642/Humantask1
Table 452
Humantask1
string('Task
TItle')
Humantask1
CompositeDN
Composite
Composite
Name
Version
Namespace
http://xmlns.oracle.com/WFClientPatternSOAApp/WF
ClientPatternTaskComposite/Humantask1 
You can then query the WFTASK table using the task ID shown in the first column of
Table 451, as shown in Example 4514.
Example 4514 Query the WFTASK table using the task ID
task:select * from wftask where taskdefinitionid =
'default/SOAComposite1!1.0*2008-12-02_08-32-41_642/Humantask1';
The results of the entire table are too large to print, but the selected columns shown in
Table 453 may be useful.
Table 453
Useful Columns
Column Name
Column Value
State
ASSIGNED
TaskID
0a6d287a-9849-4e5e-914b-805706d6b9d9
TaskNumber
200140
WorkflowDescriptorURI
default/SOAComposite1!1.0*2008-12-02_08-32-41_
642/Humantask1
TaskDefinitionID
default/SOAComposite1!1.0*2008-12-02_08-32-41_
642/Humantask1
TaskDefinitionName
Humantask1
CorrelationID
0a6d287a-9849-4e5e-914b-805706d6b9d9
This example focuses on tasks belonging to the current user identity, obtained
automatically from the session context and passed using a SAML token in the SOAP
header. These tasks that bear the ASSIGNED state and match the namespace
http://xmlns.oracle.com/WFClientPatternSOAApp/WFClientPatternTaskComposite
/Humantask1.
45-11
45.4.5.4 Construct the List of Display Columns for the queryTasks() Method
By default, the queryTasks() method returns only a list of tasks with their TASKID
value. If you require additional columns, such as TASKNUMBER, TITLE, PRIORITY, STATE,
ENDDATE, ASSIGNEE, COMPOSITEINSTANCEID, ROOTTASKID, and so on, construct an
ArrayList of String objects containing the names of the additional columns you want
returned in the result set. Example 4519 shows sample code that constructs a list of
display columns for queryTasks().
Example 4519 Constructing the List of Display Columns for queryTasks()
// List of display columns
// For those columns that are not specified here, the queried Task object will not
// hold any value.
// For example: If TITLE is not specified, task.getTitle() returns a value of
// null.
// For the list of most comonly used columns, check the table below
// Note: TASKID is fetched by default, such that it is unnecessary to explicitly
// specify it.
List queryColumns = new ArrayList();
queryColumns.add("TASKNUMBER");
queryColumns.add("TITLE");
queryColumns.add("PRIORITY");
queryColumns.add("STATE");
queryColumns.add("ENDDATE");
queryColumns.add("NUMBERATTRIBUTE1");
queryColumns.add("TEXTATTRIBUTE1");
The queryTasks() method returns a list of tasks that match the predicate and
ordering criterion.
Example 4522 shows how to invoke queryTasks() using the previously constructed
attribute lists.
Example 4522 Invoking queryTasks() with the Previously Constructed Attribute Lists
List tasksList = querySvc.queryTasks(wfCtxt,
queryColumns,
optionalInfo,
ITaskQueryService.ASSIGNMENT_FILTER_MY_AND_GROUP,
keyword,
predicate,
ordering,
0,0); // No Paging
More information on paging is available in the API documentation. (Look for the text
"How to use paging.")
45-13
Example 4524
Example 4525
Example 4526
Example 4527
Example 4528
Example 4529
Example 4525 Setting the Outcome of the Task Reference on the Single Server Task
Service
'APPROVE'.taskSvc.updateTaskOutcome(wfCtxt, t, "APPROVE");
Example 4526 Setting the Outcome of the Task Reference on the Single Server Task
Service
'REJECT'.taskSvc.updateTaskOutcome(wfCtxt, t, "REJECT");
Example 4527 Obtaining a Single Task Reference Using the Non-Federated Query
Service
getTaskDetailsById, then setting the outcome to 'APPROVE'.Task t =
querySvc.getTaskDetailsById(wfCtxt, "0a6d287a-9849-4e5e-914b-805706d6b9d9");
taskSvc.updateTaskOutcome(wfCtxt, t, "APPROVE");
Example 4528 Obtaining a Single Task Reference Using the Non-Federated Query
Service
getTaskDetailsByNumber, then setting the outcome to 'REJECT'.Task t =
querySvc.getTaskDetailsByNumber(wfCtxt, 200140 );
taskSvc.updateTaskOutcome(wfCtxt, t, "REJECT");
Example 4529 Updating a Single Task Outcome on the Federated Query Service
Map<String, IWorklowContext> ctxMap = fedWFCtx.getWorkflowContextMap()
String serverName = task.getServerName();
IWorklowContext taskWfCtx = ctxMap.get(serverName);
if (taskWfCtx !=null)
45-15
This ensures that the SOA composite has been deployed before creating a task
instance. For more information, see "Deploying and Managing SOA Composite
Applications" in the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite
and Oracle Business Process Management Suite.
45.9 What You May Need to Know About Implementing Email Notification
for an Oracle ADF Task Flow for a Human Task
This approach uses the RMI interface to the human workflow task services for
performance and identity propagation.
Endpoint information for the RMI URL is stored in the Oracle Fusion Middleware
Extensions for Applications taxonomy tables and available in JAXB object form by
the taxonomy APIs.
Use of paging (25 or 50) to limit result set size in task query or federated task
query calls is necessary for performance reasons.
46
Implementing an Oracle ADF Task Flow for a
Human Task
46
This chapter describes what to do if your SOA composite includes a human task, and
you need to define an Oracle ADF task flow for a human workflow for users to
interact with the task.
When to implement: If your SOA composite includes a human task, then you need to
define an Oracle ADF task flow for a human workflow for users to interact with the
task.
Design Pattern Summary: If your SOA composite includes a human task, then you
need a way for users to interact with the task. The integrated development
environment of Oracle SOA Suite includes Oracle Application Development
Framework (Oracle ADF) for this purpose. With Oracle ADF, you can design a task
display form that depicts the human task in the SOA composite.
Involved components:
46.3 Example
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
46.4 How to Implement an Oracle ADF Task Flow for a Human Task
This section describes the procedure used to invoke an Oracle ADF task flow for a
human task. The procedure includes tasks that are detailed in the following sections:
Implementing an Oracle ADF task flow for a human task involves the following tasks:
Define your human workflow task definition in SOA workspace. The TASK file
definition and schemas are referenced when creating the Oracle ADF task flow for
human tasks. The TASK file defines the data controls used in your task detail page.
Define the UI and uiModel project following the directory structure, package
structure and naming standards. Although the task detail page is associated with a
human task definition in your SOA composite, add to source control the UI project
containing the Oracle ADF task flow for human task definition with the Oracle
ADF workspace, not the SOA workspace.
If you plan to create other UI and uiModel projects unrelated to Oracle ADF task
flow for human tasks, you can create them in the same LBA directory as the UI
and uiModel projects associated with an Oracle ADF task flow for human tasks.
However, it is recommended to keep the other UI and uiModel projects in separate
projects, using the optional <Context> to differentiate them.
In the New Gallery window, select Web Tier > JSF > ADF Task Flow Based on
Human Task and click OK.
3.
In the SOA Resource Browser dialog, select the TASK file location and target TASK
file.
This creates the data control definition.
4.
Create a bounded task flow. From the Create Task Flow dialog, enter a name for
the task flow and click OK.
Note:
This creates the task flow containing a View component with the default name
taskDetails1_jspx, as shown in Figure 461. Rename the view activity to
something meaningful to you.
5.
Double-click the view activity in the task flow. From the Create JSF Page dialog
that displays, modify the file name or directory location as needed, and click OK.
6.
When placing a bounded task flow on a JSPX page, make sure to handle
exceptions in the bounded task flow. If the exception is propagated to the
unbounded task flow, the bounded task flow may exit, causing the JSPX page to
behave unpredictably.
Use the template with the ID ExceptionHandlerTaskFlowTemplate in the JSPX
page to avoid any unpredictable behavior. The template is located in the
UIComponents-View.jar, as follows:
/oracle/apps/fnd/applcore/patterns/uishell/templates/ExceptionHandlerTa
skFlowTemplate.xml.
Use the Property Inspector to add the template to the page, as
shown in Figure 462.
Note:
Drag and drop the task data control to your JSPX page and select Create >
Human Task > Complete Task with Payload, as shown in Figure 463.
4.
5.
In the Source view of the JSPX page, verify that <af:panelHeader> displays as the
top most component in the <af:form> component. Figure 465 shows the Source
view of a sample JSPX page.
6.
7.
Verify that the following distributed libraries are included in the JSP Tag LIbraries
for the project:
worklistComponents 1.0,
Instructions
Details
Recommended Actions
Related Links
History
Note:
Do not modify the code in the first column, which corresponds to the first
<trh:cellFormat> with id="cf1", as shown in Figure 466.
Do any or all of the following:
Example 462
Note:
Example 463
</af:showDetailHeader>
If your page does not display the Recommended Actions section, remove the
<af:showDetailHeader> component with text="#{resources.RECOMMENDED_
ACTIONS}" and continue to the next section.
If your page does display the Recommended Actions section, add the actions and
appropriate links to this section.
Translation and accessibility standards state that individual
words should not be implemented as links.
Note:
maximumLength="#{bindings.PayloadInput1.hints.precision}"
shortDesc="#{bindings.PayloadInput1.hints.tooltip}" id="it3">
<f:validator binding="#{bindings.PayloadInput1.validator}"/>
</af:inputText>
</af:panelFormLayout>
</af:panelGroupLayout>
</af:showDetailHeader>
If your page does not have an application-specific section, then remove the
<af:showDetailHeader> component with text="<PLACE APPLICATION SPECIFIC
CONTENT HERE>"and continue to the next section.
Modify the text attribute of the <af:showDetailHeader> component.
Modify the body of the <af:showDetailHeader> component to meet your
requirements.
The Complete Task with Payload drop handler adds an
<af:inputText> component for each of the task payload fields by
default. Remove these fields if they are not required.
Note:
Add links to the bottom of this section, as shown in the pattern. The link
implementation instructions are discussed in Section 46.4.3.5, "How to Implement
Links."
If additional product-specific sections are required, add them directly below the
<af:showDetailHeader> section. Ensure that the size of the additional
<af:showDetailHeader> components is set to 1.
UIShellContext.getURL(java.lang.String viewId,
java.lang.String webApp,
java.lang.String pageParametersList,
java.lang.String navTaskFlowId,
java.lang.String navTaskKeyList,
java.lang.String navTaskParametersList,
java.lang.String navTaskLabel,
FndMethodParameters methodParameters)
If your page requires both comments and attachments, then leave it as is and
continue to the next section.
If your page does not require any comments or attachments, as in the FYI pattern,
remove the <af:switcher> component with
facetName="#{pageFlowScope.bpmClientType}" and its facets and continue to
the next section.
If your page requires the comments section only, move the
<af:showDetailHeader> component with text=#{resources.COMMENTS} from the
switcher facet with name="notificationClient"so that it is a peer of the switcher
with facetName="#{pageFlowScope.bpmClientType}". Then delete the
<af:switcher> component with facetName="#{pageFlowScope.bpmClientType}"
and its facets. The resulting code is shown in Example 467.
Example 467
Example 468
<af:popup id="popupAddAttachmentDialog">
<af:dialog title="#{resources.ADD_ATTACHMENT}" okVisible="false"
cancelVisible="false" closeIconVisible="false" id="d2">
...
<af:panelGroupLayout id="pgl10">
<f:facet name="separator">
<af:spacer width="15" height="15" id="s2"/>
</f:facet>
<af:outputText value="#{resources.UPLOAD_FILE_CAVEAT}" id="ot10"/>
... Add additional instructions here ...
<af:panelFormLayout id="pfl2">
<af:selectOneRadio label="#{resources.ATTACH_TYPE}"
value="#{readAttachmentBean.selectedAttachmentType}"
valueChangeListener="#{readAttachmentBean.toggle}" autoSubmit="true"
id="editAttachmentType" layout="horizontal" immediate="true">
...
</af:afdialog>
</af:popup>
If your page does not display the Related Links section, then remove the
<af:showDetailHeader> component with text="#{resources.RELATED_LINKS}"
and continue to the next section.
If your page displays the Related Links section, add the appropriate links to this
section. The link implementation instructions are described in Section 46.4.3.5,
"How to Implement Links."
If the JSPX page that you defined for your online version contains only the
following supported components, then you can use your existing JSPX page for
both online and email versions.
af:column
af:commandLink
af:document
af:goLink
af:image
af:inputText
af:inputComboBoxListOfValues
af:inputDate
af:inputListOfValues
af:inputNumberSlider
af:inputNumberSpinbox
af:inputRangeSlider
af:outputText
af:panelHeader
af:panelLabelAndMessage
af:selectOneChoice
af:table
trh:tableLayout
trh:rowLayout
trh:cellFormat
af:panelFormLayout
af:panelGroupLayout
af:panelList
af:spacer
If the online version of your JSPX page includes many interactions to be made
available in the email notification, then you will need to build a second JSPX page
for your email notification.
Use an If component in the JSPX page to ensure that only supported components
are rendered in the email version. For more information, see Section 46.4.5.3,
"Using an If Component."
2.
a.
Add a new view to the task flow definition and rename it appropriately.
b.
Define a control flow from the newly introduced view to the existing task flow
return activity called taskReturn.
c.
Add a router.
a.
b.
c.
3.
d.
Define a control flow case from the newly introduced router to the view
associated with the online version. For the transition value, specify online.
e.
Define a control flow case from the newly introduced router to the view
associated with the email version. For the transition value, specify email.
Set the newly introduced router as the default activity, as shown in Figure 469.
Test your page to determine whether the width of <af:table> is acceptable. If the
table is not wide enough, set the <af:column> width attribute.
If you are displaying a task payload attribute in your JSPX page, you must override
the EL expression for the label attribute for each of the payload attributes. For
example, in the automatically generated Oracle ADF code shown in Example 4614,
replace the "#{bindings.PayloadInput1.hints.label}" so that it refers to translated
text in the Xliff resource bundle associated with your UI project.
Example 4614 Label attributes for the payload
<af:inputText value="#{bindings.PayloadInput1.inputValue}"
label="#{bindings.PayloadInput1.hints.label}"
required="#{bindings.PayloadInput1.hints.mandatory}"
columns="#{bindings.PayloadInput1.hints.displayWidth}"
maximumLength="#{bindings.PayloadInput1.hints.precision}"
shortDesc="#{bindings.PayloadInput1.hints.tooltip}"
id="it1">
<f:validator binding="#{bindings.PayloadInput1.validator}"/>
</af:inputText>
Note: Two strings in the Oracle ADF code template that store their
translations in the resource bundle associated with the TASK file (as
opposed to the UI project). Do not define the translations in the
resource bundle associated with your UI.
Title: Define the title in the task definition using the Translation setting. Ensure a
translation is provided in a Java resource bundle. Do not use the properties file to
store translated text.
Custom actions: Ensure a translation is provided in a Java resource bundle. Do not
use the properties file to store translated text.
For more information about translation resource bundles, see the section entitled
"How to set up Resource Bundles for Translation of Your Customizations" in
Chapter 63, "Creating Customizable Applications."
In Oracle JDeveloper, select Application Navigator > Data Controls > Task Flow
Name > getTaskDetails(String, String, String) > Return > Task > System
Attributes > Collection Target.
Regardless of whether aggregation is enabled, the collection target contains
information on the rows that are being approved or rejected by the approver.
Example 4615 Adding the Oracle ADF library to the SuperWeb project
<filter>
<filter-name>WorkflowFilter</filter-name>
<filter-class>
oracle.bpel.services.workflow.client.worklist.util.WorkflowFilter
</filter-class>
</filter>
<filter-mapping>
<filter-name>WorkflowFilter</filter-name>
<url-pattern>/faces/*</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>IntegrateTaskFlowWithTask</servlet-name>
<servlet-class>
oracle.bpel.services.workflow.client.worklist.servlet.
IntegrateTaskFlowWithTask
</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet>
<servlet-name>secureNotificationServlet</servlet-name>
<servlet-class>
oracle.bpel.services.workflow.client.worklist.servlet.SecureNotificationS
ervlet
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>IntegrateTaskFlowWithTask</servlet-name>
<url-pattern>/integratetaskflowwithtask</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>secureNotificationServlet</servlet-name>
<url-pattern>/notification/secure</url-pattern>
</servlet-mapping>
<context-param>
<param-name>oracle.adf.view.rich.security.FRAME_BUSTING</param-name>
<param-value>differentDomain</param-value>
</context-param>
3.
Under the default source location, create the hwtaskflow.xml file and merge all
the notification task flow details. For example, if you are adding a new ADF task
flow for a human task to a project defined in a workspace called
fusionapps/fin/components/Payables.jws, then you would take the following
steps.
a.
b.
</hwTaskFlows>
Secure actions
b.
c.
2.
d.
e.
b.
Navigate to Domain Structure > Services > Foreign JNDI Providers and click
New.
c.
d.
Click ForeignJNDIProvider-SOA.
e.
f.
Note:
3.
b.
Navigate to Domain Structure > Services > Foreign JNDI Providers and click
ForeignJNDIProvider-SOA.
c.
d.
e.
4.
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.JpsPermission</class>
<name>VerificationService.createInternalWorkflowContext</name>
</permission>
<permission>
<class>oracle.security.jps.service.credstore.
CredentialAccessPermission</class>
<name>context=SYSTEM,mapName=BPM-CRYPTO,keyName=BPM-CRYPTO</name>
<actions>read,write</actions>
</permission>
<permission>
<class>oracle.security.jps.JpsPermission</class>
<name>IdentityAssertion</name>
<actions>*</actions>
</permission>
</permissions>
</grant>
5.
6.
Deploy your application containing the human task detail UI to the remote
non-SOA Oracle WebLogic Server.
When accessing the task in the Oracle Business Process
Management Worklist, you may get the following message: "Details
not available for this task."
Tips:
If your SOA runtime and task detail UI are running on different domains during
development, set the value to never for testing purposes only.
3.
4.
5.
6.
3.
Repeat step 2 for the second <af:commandImageLink> with the action property
value #{popupBean.showCommentDialog}. Example 4620 shows a sample
illustrating <af:commandImageLink> after modifying the action property value.
47
Cross Family Business Event Subscription
Pattern
47
This chapter describes what to do when you require your SOA composite to subscribe
to a business event published on another Oracle SOA Suite cluster.
When to implement: When you require your SOA composite to subscribe to a
business event published on another Oracle SOA Suite cluster.
Design Pattern Summary: The Event Delivery Network (EDN) infrastructure supports
business event publishing and subscription within a single Oracle SOA Suite cluster.
To propagate a business event from one Oracle SOA Suite cluster to another, you must
build a mediator-to-mediator bridge. The bridge queues the event message in a global
aqueue from the Oracle SOA Suite cluster. The Oracle SOA Suite cluster publishes the
event and then dequeues the event message from the Oracle SOA Suite cluster that
subscribes to the event.
Involved components:
Oracle Mediator
A global EDN queue can be shared across all Oracle Fusion Applications families.
Although it supports cross-event subscription, the shared EDN feature is not
recommended due to the durability of subscriptions. If any of the Oracle SOA
Suite clusters sharing an event queue goes down, then the events will remain in
the queue until the cluster goes back up and dequeues the event. If the cluster is
offline for a long period, the queue could become quite large. In addition, a large
number of events may need to be dequeued by each of the Oracle SOA Suite
clusters even if there may no subscribers. This may affect performance.
Example
WARNING:
The composite with the event subscription can be deployed to the Oracle SOA
Suite cluster which publishes the event.
47.3 Example
CRM Subscribes to Event Published by HCM
HcmUsersSpmlComposite deployed in the HCM SOA cluster publishes a
post-processing event to report the success or failure of the process of creating a new
user or assigning roles to a user. In order for CRM to perform additional actions based
on the user request, the post-processing event must be propagated from HCM to CRM.
Table 471 lists the HCM composite components and values.
Table 471
Composite Components
Values
Publishing Product
Per
Subscribing Product
Hz
Owning Product
Hz
FoundationPartiesPerToHzXFamilyPubComposite
FoundationPartiesHzXFamilySubComposite
Recipient/Consumer
FoundationPartiesPerToHz
SOA workspace
CrmCommonSoa.jws
Composite Components
Values
Publishing Product
Hz
Subscribing Product
Per
Owning Product
Hz
Values
FoundationPartiesHzToPerXFamilyPubComposite
FoundationPartiesPerXFamilySubComposite
Recipient/Consumer
FoundationPartiesHzToPer
SOA workspace
CrmCommonSoa.jws
The sample code for this use case can be downloaded from Oracle SOA Suite samples.
Publishing product: The publisher product is the product that publishes the
event.
Subscribing product: The subscriber product is the product that subscribes to the
event.
Owning product: The owning product is the product that owns the XFamilyPub
and XFamilySub composites.
The product team requiring the cross-family subscription owns both the XFamilySub
and XFamilyPub composites. This pattern assumes the composites are defined at the
product level. It is also possible to define the XFamilySub and XFamilyPub at the family
level instead.
Determine whether an XFamilySub or XFamilyPub composite has been defined for your
product. If they have not been defined, then follow these guidelines for naming the
XFamilySub and XFamilyPub composites. The naming guidelines help make
cross-family event composites easily identifiable and self-descriptive.
These composites can reside in any LBA in your product.
Composite Naming Conventions
The composite names must adhere to the following guidelines:
1.
Start with the LBA short name. You can define the composite in any LBA.
2.
3.
4.
Add <Subscribing product> if not included in LBA short name. Use the
product short name as defined in Oracle Fusion Setup. Use B2B if the
subscriber is a composite deployed to the Setup SOA cluster for B2B.
Add <Publisher product>To<Subscriber product> so that the name is
self-descriptive. Use the product short name as defined in Oracle Fusion
Setup.
XFamilySub
A product can have more than one XFamilyPub composite.
Using the naming conventions specified in Composite Naming Conventions, the
sample composite name is as follows:
XFamilyPub
A product can have more than one XFamilyPub composite. There should only be one
XFamilyPub composite for each publisher product and subscriber product
combination.
In the owning team's SOA workspace, create an empty composite with the name
determined in Section 47.4.2.
2.
Drag and drop an Aqueue Adapter to the right swim lane of your composite and
define the adapter as follows.
a.
In the Service Name field, enter a service name for the Aqueue Adapter.
b.
Define a connection for your Oracle Fusion Middleware schema and enter
JNDI name eis/AQ/XFamilyEventAqueueInterface.
c.
d.
For the operation type, select the Enqueue radio button. In the Operation
Name field, enter Enqueue.
e.
For the queue name, enter FUSION as the database schema and ACR_
XFAMILY_EVENT_Q for the queue name.
f.
On the Queue Parameters page, enter the recipient as defined in Section 47.4.3.
g.
4.
For each event to which your family subscribes, define a routing rule in the
mediator. Click add button next to Event Subscriptions and select the business
event to which you want to subscribe on the remote Oracle SOA Suite cluster.
Reference the EDL file from MDS, and do not copy the file in your composite.
a.
Add a static routing rule and click the Service button. Select References >
EnqueueEventMessage > Enqueue.
b.
c.
In the column on the right, right-click msg_out:Namespace. Select Set Text >
Enter Text, and specify the event namespace.
d.
In the column on the right, right-click msg_out:LocalName. Select Set Text >
Enter Text, and specify the event local name.
e.
In the Component Palette, from XSL Constructs, drag and drop copy-of to
themsg_out:Payload element on the far right column of the XSL design tab.
In the Copy-of Type dialog, select Replace the children of the selected node
with the results of the copy-of. If an error message displays to the right of the
copy-of element, you can ignore it.
f.
In the far left column, select the element just below <sources>. Drag-and-drop
the element to the copy-of in the far right column in the XSL design tab. After
you complete this step, the error icon that displayed in the previous step
disappears.
<rootElement name="FusionXFamilyEvent"
namespace="http://xmlns.oracle.com/apps/common/acr/events"/>
</target>
</mapTargets>
<!-- GENERATED BY ORACLE XSL MAPPER 11.1.1.2.0(build 100216.1000.2230) AT [MON APR 26 14:00:00
PDT 2010]. -->
?>
<xsl:stylesheet version="1.0"
xmlns:xpath20="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.
services.functions.Xpath20"
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:mhdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.mediator.
service.common.functions.MediatorExtnFunction"
xmlns:oraext="http://www.oracle.com/XSL/Transform/java/oracle.tip.pc.
services.functions.ExtFunc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:dvm="http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue"
xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:med="http://schemas.oracle.com/mediator/xpath"
xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
xmlns:xdk="http://schemas.oracle.com/bpel/extension/xpath/function/xdk"
xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.
tip.xref.xpath.XRefXPathFunctions"
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:ns0="http://xmlns.oracle.com/apps/crm/hz/bulkImport/
FoundationBulkImportEventsComposite"
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:socket="http://www.oracle.com/XSL/Transform/java/oracle.
tip.adapter.socket.ProtocolTranslator"
xmlns:msg_out="http://xmlns.oracle.com/apps/common/acr/events"
xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/XFamilyEventPattern/
FinInfrHzToZxXFamilyPubComposite/EnqueueEventMessage"
xmlns:ldap="http://schemas.oracle.com/xpath/extension/ldap"
exclude-result-prefixes="xsi xsl xsd ns0 plt wsdl msg_out tns xpath20 bpws mhdr
oraext dvm hwf med ids xdk xref ora socket ldap">
<xsl:template match="/">
<msg_out:FusionXFamilyEvent>
<msg_out:Namespace>
<xsl:text disable-output-escaping="no">http://xmlns.oracle.com/apps/crm/hz/bulkImport/
FoundationBulkImportEventsComposite</xsl:text>
</msg_out:Namespace>
<msg_out:LocalName>
<xsl:text disable-output-escaping="no">ImportPartyData</xsl:text>
</msg_out:LocalName>
<msg_out:Payload>
<xsl:copy-of select="/ns0:batchInfo"/>
</msg_out:Payload>
</msg_out:FusionXFamilyEvent>
</xsl:template>
</xsl:stylesheet>
5.
In the routing rule, define an assign statement to copy the context from the
apps.context.header property into the ApplicationContext element in the
aqueue message. The Assign Value window is shown in Figure 471.
Use the Expression builder to generate an expression for the To region. Select
Variables > out > FusionXFamilyEvent > msg_out:FusionXFamilyEvent > msg_
out:ApplicationContext, click Insert into Expression and then click OK.
Figure 471 Define an Assign Statement
<assign>
<copy target="$out.FusionXFamilyEvent/msg_out:FusionXFamilyEvent/msg_out:ApplicationContext"
value="$in.property.apps.context.header"
xmlns:msg_out="http://xmlns.oracle.com/apps/common/acr/events"/>
</assign>
6.
Open the composite.xml file and search for the following line.
<binding.jca config="EnqueueEventMessage_aq.jca"/>
7.
Example 473
Replace the binding.jca element with the code shown in Example 473.
<binding.jca config="EnqueueEventMessage_aq.jca">
<property name="jca.subject.xpath">/msg_out:FusionXFamilyEvent/msg_out:Subject</property>
<property name="jca.subject.nslist">xmlns:msg_out=
"http://xmlns.oracle.com/apps/common/acr/events"</property>
</binding.jca>
8.
Example 474
Add standard fault policies to the composite just above the <component> elements
in the composite.xml file, as shown in Example 474.
<property name="oracle.composite.faultPolicyFile">
oramds:/apps/oracle/apps/fnd/applcore/soa/fault/fault-policies.xml</property>
47-8 Developer's Guide
<property name="oracle.composite.faultBindingFile">
oramds:/apps/oracle/apps/fnd/applcore/soa/fault/fault-bindings.xml</property>
Drag and drop an Aqueue Adapter onto the left swim lane of your composite and
provide the following values in the definition. When specifying the Messages
URL, you will be referencing oramds. Ensure you have a SOA-MDS defined which
points to fusionapps/soa_shared/soa-infra before proceeding.
a.
b.
In the Service Connection window, define a connection for the Oracle Fusion
Middleware schema. For the JNDI name, enter eis/AQ/XFamilyEventAqueue.
For the XA Data Source, accept the default value.
c.
In the Adapter Interface window, accept the default selection Define from
operation and schema (this is specified later).
d.
In the Operation window, select Dequeue for the operation type. In the
Operation Name text field, accept the default value of Dequeue.
e.
In the Queue Name window, select the database schema and enter a queue
name.
From the Database Schema dropdown list, select Fusion.
In the Queue Name field, enter ACR_XFAMILY_EVENT_Q.
f.
g.
In the Messages window, select the message schema URL and the relevant
schema element.
In the URL field, browse for the message schema URL.
From the Schema Element dropdown list, select FusionXFamilyEvent.
3.
Drag and drop a mediator component onto your composite using the Define
Interface Later template, and name it DequeueMediator.
Draw a wire between the aqueue adapter and mediator, as shown in Figure 472.
4.
For each cross family event to which your family subscribes, define a static routing
rule in the mediator.
a.
Add a routing rule to raise the event by clicking on the add icon and the Event
button. Use oramds to reference the EDL file rather than copying the EDL file
into your composite.
b.
Add a filter expression to the rule to select the aqueue messages with the
namespace and local name that match the event.
For example, if the namespace of the event is
http://xmlns.oracle.com/apps/crm/hz/bulkImport/FoundationBulkImport
EventsComposite and the local name is ImportPartyData, then the following
filter is defined, as shown in Example 475.
Example 475
(($in.FusionXFamilyEvent/msg_out:FusionXFamilyEvent/msg_out:Namespace =
"http://xmlns.oracle.com/apps/crm/hz/bulkImport/FoundationBulkImportEventsComposite")
and ($in.FusionXFamilyEvent/msg_out:FusionXFamilyEvent/msg_out:LocalName = "ImportPartyData"))
c.
Create a transformation XSL file. Click the transformation icon, select Create
New Mapper File, and click OK.
d.
In the Component Palette, expand the XSLT Constructs tab. Drag and drop the
copy-of construct onto the XSLT file column on the element directly under the
<target> element.
e.
In the Copy-of Type dialog, select Replace the selected node with the results
of the copy-of.
f.
From the source column, drag and drop the msg_out:Payload onto the copy-of
element in the XSLT file column.
g.
Example 476
XSL File
<?oracle-xsl-mapper
<!-- SPECIFICATION OF MAP SOURCES AND TARGETS, DO NOT MODIFY. -->
<mapSources>
<source type="WSDL">
<schema location="../DequeueEventMessage.wsdl"/>
<rootElement name="FusionXFamilyEvent"
namespace="http://xmlns.oracle.com/apps/common/acr/events"/>
</source>
</mapSources>
<mapTargets>
<target type="XSD">
<schema location="../xsd/bulkImportEvents.xsd"/>
<rootElement name="batchInfo"
namespace="http://xmlns.oracle.com/apps/crm/hz/bulkImport/
FoundationBulkImportEventsComposite"/>
</target>
</mapTargets>
<!-- GENERATED BY ORACLE XSL MAPPER 11.1.1.2.0(build 100216.1000.2230) AT [MON APR 26 15:28:04
PDT 2010]. -->
?>
<xsl:stylesheet version="1.0"
xmlns:xpath20="http://www.oracle.com/XSL/Transform/java/oracle.
tip.pc.services.functions.Xpath20"
xmlns:bpws="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
xmlns:mhdr="http://www.oracle.com/XSL/Transform/java/oracle.tip.mediator.
service.common.functions.MediatorExtnFunction"
xmlns:oraext="http://www.oracle.com/XSL/Transform/java/oracle.
tip.pc.services.functions.ExtFunc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:dvm="http://www.oracle.com/XSL/Transform/java/oracle.tip.dvm.LookupValue"
xmlns:hwf="http://xmlns.oracle.com/bpel/workflow/xpath"
xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/XFamilyEventPattern/
FinInfrZxXFamilySubComposite/DequeueEventMessage"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:med="http://schemas.oracle.com/mediator/xpath"
xmlns:ids="http://xmlns.oracle.com/bpel/services/IdentityService/xpath"
xmlns:xdk="http://schemas.oracle.com/bpel/extension/xpath/function/xdk"
xmlns:xref="http://www.oracle.com/XSL/Transform/java/oracle.
tip.xref.xpath.XRefXPathFunctions"
xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:ns0="http://xmlns.oracle.com/apps/crm/hz/bulkImport/
FoundationBulkImportEventsComposite"
xmlns:ora="http://schemas.oracle.com/xpath/extension"
xmlns:socket="http://www.oracle.com/XSL/Transform/java/oracle.tip.adapter.socket.
ProtocolTranslator"
xmlns:msg_out="http://xmlns.oracle.com/apps/common/acr/events"
xmlns:ldap="http://schemas.oracle.com/xpath/extension/ldap"
exclude-result-prefixes="xsi xsl tns plt xsd wsdl msg_out ns0 xpath20 bpws
mhdr oraext dvm hwf med ids xdk xref ora socket ldap">
<xsl:template match="/">
<xsl:copy-of select="/msg_out:FusionXFamilyEvent/msg_out:Payload/child::node()">
<?oracle-xsl-mapper-position ns0:batchInfo?>
</xsl:copy-of>
</xsl:template>
</xsl:stylesheet>
h.
In the routing rule, define an assign statement to copy the context from the
ApplicationContext element in the aqueue message into the
5.
Example 477
<binding.jca config="EnqueueEventMessage_aq.jca">
<property name="jca.subject.xpath">/msg_out:FusionXFamilyEvent/msg_out:Subject</property>
<property name="jca.subject.nslist">xmlns:msg_out=
"http://xmlns.oracle.com/apps/common/acr/events"</property>
</binding.jca>
6.
Example 478
<property name="oracle.composite.faultPolicyFile">
oramds:/apps/oracle/apps/fnd/applcore/soa/fault/fault-policies.xml</property>
<property name="oracle.composite.faultBindingFile">
oramds:/apps/oracle/apps/fnd/applcore/soa/fault/fault-bindings.xml</property>
Raise the cross family business event. Before integrating with Oracle ADF, you can
raise a business event by invoking the following PL/SQL code in the Oracle
Fusion Applications schema.
a.
b.
c.
Replace the business event content.begin with the relevant business event.
Example 479 shows sample PL/SQL code used to raise a business event.
Example 479
fnd_global.initialize_session('F58679122D280FD03AD1198A55EFC6BF', 'Abraham.Mason');
hcm_edn_publish_event('/oracle/apps/hcm/users/publicModel/entity/events/edl/LdapRequestEO',
'ActiveLdapRequestEvent',
'<business-event xmlns="http://oracle.com/fabric/businessEvent"
xmlns:ns="/oracle/apps/hcm/users/publicModel/entity/events/edl/LdapRequestEO">'||
'<name>ns:ActiveLdapRequestEvent</name>'||
'<content>'||
'<ActiveLdapRequestEventInfo xmlns="/oracle/apps/hcm/users/publicModel/
entity/events/schema/LdapRequestEO">'||
'<LdapRequestId>'||
'<newValue value="5"/>'||
'<oldValue value="5"/>'||
'</LdapRequestId>'||
'</ActiveLdapRequestEventInfo>'||
'</content>'||
'</business-event>');
commit;
end;
/
3.
Confirm the event was raised on the SOA cluster that raises the cross-family
business event by navigating to http://<SOA SERVER>:<SOA
PORT>/soa-infra/events/edn-db-log.
4.
Confirm the event name space, name, identity, payload and context matches the
event raised via the PL/SQL API.
a.
b.
3.
Confirm the event was raised on the SOA cluster that subscribes to the
cross-family business event by navigating to http://<SOA SERVER>:<SOA
PORT>/soa-infra/events/edn-db-log.
4.
Confirm the event namespace, name, identity, payload and context matches the
event raised via the PL/SQL API.
The statement should return the following results. Ensure SELECT, UPDATE, ENQUEUE,
and DEQUEUE privileges are returned, as shown in Example 4711.
Example 4711 Results Returned
GRANTEE
------FUSION_RUNTIME
FUSION_RUNTIME
47-14 Developer's Guide
OWNER
-----FUSION
FUSION
GRANTOR
-------FUSION
FUSION
PRIVILEGE
--------SELECT
UPDATE
GRANTABLE
--------NO
NO
TABLE_NAME
---------ACR_XFAMILY_EVENT_QT
ACR_XFAMILY_EVENT_QT
FUSION_RUNTIME
FUSION_RUNTIME
FUSION
FUSION
FUSION
FUSION
ENQUEUE
DEQUEUE
NO
NO
ACR_XFAMILY_EVENT_Q
ACR_XFAMILY_EVENT_Q
If any of these privileges are not defined in your environment, run the appropriate
command listed in Example 4712.
Example 4712 Granting Relevant Privileges
GRANT SELECT ON FUSION.ACR_XFAMILY_EVENT_QT TO FUSION_RUNTIME;
GRANT UPDATE ON FUSION.ACR_XFAMILY_EVENT_QT TO FUSION_RUNTIME;
execute DBMS_AQADM.GRANT_QUEUE_PRIVILEGE('ENQUEUE', 'ACR_XFAMILY_EVENT_Q',
'FUSION_RUNTIME', FALSE);
execute DBMS_AQADM.GRANT_QUEUE_PRIVILEGE('DEQUEUE', 'ACR_XFAMILY_EVENT_Q',
'FUSION_RUNTIME', FALSE);
This statement should return the results shown in Table 473. Confirm that the
ENQUEUE_ENABLED and DEQUEUE_ENABLED columns are set to YES for ACR_XFAMILY_
EVENT_Q.
Table 473 Results When Confirming ACR_XFAMILY_EVENT_Q Is Enabled for
Enqueuing and Dequeuing
OWNER
FUSION
FUSION
NAME
ACR_XFAMILY_EVENT_Q
AQ$_ACR_XFAMILY_
EVENT_QT_E
QUEUE_TABLE
ACR_XFAMILY_EVENT_QT ACR_XFAMILY_EVENT_QT
QID
3851358
3851357
QUEUE_TYPE
NORMAL_QUEUE
EXCEPTION_QUEUE
MAX_RETRIES
RETRY_DELAY
ENQUEUE_ENABLED
YES
NO
DEQUEUE_ENABLED
YES
NO
RETENTION
USER_COMMENT
exception queue
NETWORK_NAME
If the queue is not enabled for enqueue or dequeue, run the command shown in
Example 4714.
47.6.3 AQ_INVALID_QUEUE_TYPE
If you encounter the error message, shown in Example 4715, take the following steps.
Example 4715 AQ_INVALID_QUEUE_TYPE Error
{{Error during invoking 1-way operation "Enqueue" on target service
"EnqueueEventMessage"
Exception occured when binding was invoked. Exception occured during invocation of
JCA binding: "JCA Binding execute of Reference operation 'Enqueue' failed due to:
AQ_INVALID_QUEUE_TYPE. Unable to obtain the correct queue type. Queue does not
exist or not defined correctly. Drop and re-create queue. ". The invoked JCA
adapter raised a resource exception. Please examine the above error message
carefully to determine a resolution. }}
This error indicates that FUSION_RUNTIME does not have the appropriate privileges to
enqueue messages in the aqueue. Take the steps described in Section 47.6.1, "Privileges
to FUSION_RUNTIME."
Part VII
Part VII
Implementing Security
This part of the Developer's Guide provides information about Oracle Fusion
Applications security. It discusses how to implement Oracle Fusion Data Security and
user sessions, and how to secure specific use cases for Oracle ADF application
artifacts, Web services, and portlet applications.
Getting Started with Security introduces security concepts and features, namely
authentication and authorization. Authentication establishes the identity of the user.
Authorization ensures that users only have access to resources to which they have
been granted access.
Implementing Application User Sessions describes how to allow applications to store
security and application context on the user session, and to allow for an enhanced
security implementation. An application can easily reconnect to the same user session
for each request, maintaining the user context over the duration of the user's session
without the overhead of having to obtain and initiate a database connection each time.
The actual connection used is not guaranteed to be the same between requests. User
session roles can be enabled for a user, and dictate what privileges that user has to
access functions and data of the application.
Implementing Oracle Fusion Data Security describes how to enforce authorization for
access and modification of specific data records. The goal of Oracle Fusion Data
Security is to authorize a user to perform specified actions on selected data. Data
security can secure rows and attributes of a database object and addresses the question
"Who can do what on which set of data."
Implementing Function Security describes how to authorize end users to access securable
application artifacts created using Oracle ADF.
Securing Web Services Use Cases describes best practices for for securing Web services in
Oracle Fusion Applications and specifically explains the difference between global
policy attachment and local policy attachment and when to use each.
Securing End-to-End Portlet Applications describes how to authenticate and authorize
portlet services, as well as how to configure key stores and credential stores.
This part contains the following chapters:
48
Getting Started with Security
48
This chapter describes the components that developers use to secure Oracle Fusion
applications and web services by enforcing authentication and authorization.
This chapter includes the following sections:
48.1.1 Architecture
Oracle Fusion applications are built on top of a fixed set of internal and third-party
technologies. This set of technologies defines what may be used to develop, build,
package, and run all Oracle Fusion applications. Each technology and component may
have its own specific requirements for security implementation.
The following figure depicts the components in the Oracle Fusion Applications
security approach.
Application resources including ADF task flows, ADF components, and ADF
Business Components. For more information, see:
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Oracle Platform Security Services (OPSS) security. For more information, see:
Oracle Fusion Middleware Application Security Guide.
Oracle Web Services Manager (Oracle WSM). For more information, see:
Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
Oracle WSM policy interceptors. For more information, see Chapter 52, "Securing
Web Services Use Cases."
Identity providers including the LDAP-based provider and the file-based provider
(jazn-data.xml file). For more information, see:
Oracle Fusion Middleware Application Security Guide.
Oracle Fusion application user sessions. For more information, see Chapter 49,
"Implementing Application User Sessions."
Oracle Fusion Data Security policies for data security. For more information, see
Chapter 50, "Implementing Oracle Fusion Data Security."
Oracle Fusion Applications security policies for function security. For more
information, see Chapter 51, "Implementing Function Security."
Some of the technologies have an additional layer of security on top of the main
security technologies.
The previous figure depicts the various security components as layers. The uppermost
layer includes the Oracle WebLogic Server and the Java applications running on the
server; under it, is the layer consisting of APIs for Authentication, Authorization,
Credential Store Framework, User and Role, and identity virtualization; the bottom
layer includes the Security Service Provider Interface (SSPI) layer and the service
providers. The bottom layer interacts with security data repositories, such as LDAP
and database servers.
In addition to the list of providers shown in Figure 482, other providers include the
role mapping and audit providers.
For more information about OPSS, see the "Understanding Security Concepts" part in
the Oracle Fusion Middleware Application Security Guide.
The Security Service Provider Interface (SSPI) layer is accessed through OPSS APIs
and provides Java EE container security in permission-based (JACC) mode and in
resource-based (non-JACC) mode. It also provides resource-based authorization for
the environment, thus allowing customers to choose their security model.
For more information about Oracle WSM, see Oracle Fusion Middleware Security and
Administrator's Guide for Web Services.
How Policies are Executed
When a request is made from a service consumer (also known as a client) to a service
provider (also known as a Web service), the request is intercepted by one or more
policy interceptors. These interceptors execute policies that are attached to the client
and to the Web service. There are five types of interceptors (reliable messaging,
management, WS-Addressing, security, and MTOM) that together form a policy
interceptor chain. Each interceptor executes policies of the same type. The security
interceptor intercepts and executes security policies, the MTOM interceptor intercepts
and executes MTOM policies, and so on.
Policies attached to a client or Web service are executed in a specific order via the
Policy Interceptor Pipeline, as shown in the following figure.
Figure 483 Policy Interceptors Acting on Messages Between a Client and Web Service
to a particular pillar. That is, everything running on that same pillar should see the
same context.
For details about application user sessions, see Chapter 49, "Implementing Application
User Sessions."
Declaratively enforce security on the view object level through view criteria,
The data security implementation relies on the security context defined in the
application user session. Even if OPSS authenticates the user and the security subject is
established, the user cannot access any data unless the application user session is
established.
For details about Oracle Fusion Data Security, see Chapter 50, "Implementing Oracle
Fusion Data Security."
48.1.2 Authentication
Oracle Fusion applications reside in containers that automatically handle
authentication. The container intercepts all requests entering the system, and ensures
that users are properly authenticated and the security context propagated.
Invoking the ADF Security wizard when developing an application configures the
application to enforce security at runtime.
When a request is received with no subject defined, Oracle Platform Security Services
creates a subject containing the anonymous user principal and the anonymous role
principal. Oracle Platform Security Services is configured by the JPSFilter. With this
security subject, unauthenticated users can access public resources. When accessing
secure resources, the adfAuthentication servlet forces users to authenticate. The
security configuration determines the login module to be used for authentication.
By default, Oracle WebLogic Server is the authenticator used when developing
applications with Oracle ADF. Different configurations can also be used, such as an
Oracle Single Sign-On solution.
For more information, see the "Enabling ADF Security in a Fusion Web Application"
chapter in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
Audit Identity
When switching to the application identity, you must propagate the identity to be
audited to preserve the submitting identity for auditing purposes.
Auditing is based on who columns, which are populated with session data. When the
session is established, it is initialized using the current identity. The session APIs
expose a method to manipulate the identity to be used for auditing. This method
allows teams to control which identity is stored as the audit identity. Example 481
illustrates the syntax of this method.
Example 481
ApplSession.setHistoryOverrideUserName()
The session is not propagated, rather only the identity is propagated. As the session is
initialized using the identity, any application specific values are lost. To prevent this,
you must pass the audit identity and override the audit identity on the session.
It is recommended for the service provider to add an extra parameter to the service so
as to store the original user ID (historyOverrideUserName, of type String). In order to
invoke the service, the service method consumer must fill in the original user ID as
part of the payload. Within the service, the value passed is populated on the session as
shown in Example 482.
Example 482
48.1.3 Authorization
Authorization ensures that users only have access to the resources to which they have
been granted access. Authorization decisions are based on policies stored in a policy
store. There are two main types of policy stores: OPSS application security repository
and Oracle Fusion Data Security repository. The OPSS repository contains the security
definitions that control access to applications. The Oracle Fusion Data Security
repository contains the security definitions controlling data access.
At runtime, the page context determines whether the current user has view
permissions for the page being accessed. If the page includes an activity of a bounded
task flow, the task flow controller determines the permissions. If the page is a top-level
page with an associated page definition file, the Oracle ADF model determines the
permissions for the page.
The OPSS service provider interface checks whether the subject includes the roles with
the relevant permissions required to access the page. If the user is authorized to access
the page, then the task flow is initiated. If the user is not authorized, ADF Controller
throws an exception and passes control to an exception handler specified by the task
flow configuration.
It is also possible to include an API that checks whether the current user has access to a
resource.
Developer created additions to the policy store must be migrated to LDAP by a
security administrator.
48.2.1 APIs
You can implement authentication by using user and role APIs. For more information,
see the "Developing with the User and Role API" chapter of the Oracle Fusion
Middleware Application Security Guide.
48-11
securityContext.userName
securityContext.authenticated
securityContext.userInRole
securityContext.userInAllRoles
securityContext.userGrantedPermission
securityContext.userGrantedResource
securityContext.taskflowViewable
securityContext.regionViewable
Note that decisions about user's access rights should not rely on the user's role
information since role definitions may be changed. Instead access should be based on
available permissions.
For more information, see the "Enabling ADF Security in a Fusion Web Application"
chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
2.
3.
4.
Grant the entitlement to a custom duty role that was added to the Oracle Fusion
application policy store.
5.
Enable ADF Security for the application by running the Configure ADF Security
wizard.
After running the ADF Security wizard, any web page associated with a bounded
ADF task flow will be protected. Therefore before running the application and testing
security, developers must first create security policies that grant end users access.
For more information, see Chapter 51, "Implementing Function Security."
securityContext.taskflowViewable
securityContext.regionViewable
securityContext.userGrantedPermission
For more information, see the "Enabling ADF Security in a Fusion Web Application"
chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
48-13
1.
2.
Refer to these security definitions from the code artifacts. This step varies
depending on the technology used, as well as the functional requirements of the
application.
For more information about implementing Oracle Fusion Data Security, see
Chapter 50, "Implementing Oracle Fusion Data Security."
For more information about using Oracle Authorization Policy Manager, see the
"Using Oracle Authorization Policy Manager" chapter of the Oracle Fusion Applications
Administrator's Guide.
The security requirements for the PII attribute determine the technologies to be used.
49
Implementing Application User Sessions
49
This chapter describes how to implement application user sessions in an Oracle Fusion
application to allow applications to store security and application context on the user
session.
This chapter includes the following sections:
number of attributes exists, developers may want to create their own namespaces to
group the attributes together more cleanly.
Oracle Fusion Middleware Extensions for Applications provides covers on top of the
routines for getting attributes. To access the attributes of the application context, APIs
exist in both PL/SQL and Java, as described in Section 49.3, "Accessing Properties of
the Applications Context."
If you have any web services projects, you must configure them to maintain the
application user session across the web service request. For more information, see
Section 52.7, "Maintaining Application Session Context Across Web Service
Requests."
If you have any portlet projects, you must configure them to maintain the
application user session across the web service request. For more information, see
Section 53.5, "Maintaining Application Session Context Across Web Service
Requests."
1.
2.
In your Application Navigator, select the web.xml file in the WEB-INF folder of
your user interface project. Double-click to open the file. In the Categories tree,
select Filters to create a new filter. Enter the following information:
Filter Name: Enter ApplSessionFilter
Filter Class: Enter oracle.apps.fnd.applcore.common.ApplSessionFilter
3.
Select the Source view to manually modify the web.xml source to add the
ApplSessionFilter mapping definition into the same section where other filters
are definedimmediately after the JpsFilter mapping definition and before any
other definitions.
The following example shows the ApplSessionFilter mapping definition to add.
Example 491
...
<filter-mapping>
<filter-name>ApplSessionFilter</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
...
It is important that you add this filter mapping immediately after the JpsFilter
mapping definition and before any other definitions. This is to ensure that the
ApplSessionFilter servlet filter executes immediately after the JpsFilter servlet
handles authentication. Normally, this does not make a difference, however there
are cases, such as customization code, where this is required.
You can create the above through the Filter Mappings tab (with Mapping Type
set to Servlet, and Mapping set to Faces Servlet, and Dispatcher Type set to
Forward, Request) but to change the ordering of the filter mapping, you must
modify the web.xml file directly.
4.
You should also stop and restart any server processes that you have running to make
sure JDeveloper notices this new change. At this point you can run your page with
application user sessions enabled, but you will always be running as the anonymous
user. If you wish to require that users to authenticate, you will need to enable
authentication and define some users and roles, as described in Section 51.3, "Adding
Function Security to the Application."
different log levels, define message time frames, and search on message text. For more
information about these JDeveloper log tools, see the "Testing and Debugging ADF
Components" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
After the application is deployed to standalone Oracle WebLogic Server, a system
administrator uses Oracle Enterprise Manager Fusion Applications Control to adjust
the log level and to view the logger's recorded messages. The system administrator
may increase the ApplSession log level to gather detailed information for a particular
managed server. For more information about adjusting log levels for the ApplSession
logger, using Fusion Applications Control, see "Adjusting ApplSession Log Levels for
Troubleshooting" section in the "Troubleshooting Oracle Fusion Applications Using
Incidents, Logs, QuickTrace, and Diagnostic Tests" chapter of the Oracle Fusion
Applications Administrator's Troubleshooting Guide.
For information about Oracle Fusion Middleware logging functionality, see the
"Managing Log Files and Diagnostic Data" chapter of the Oracle Fusion Middleware
Administrator's Guide.
49.2.4 What Happens at Runtime: How the Application User Session is Used
When you run your page, an authentication dialog displays. Login as OPERATIONS /
welcome1. An application user session for the OPERATIONS user is created and
associated with your application user session. Your page can access this application
user session through the ApplSessionUtil class, as described in Section 49.3,
"Accessing Properties of the Applications Context."
For details about enforcing security and granting access to application resources while
testing the applications, see Section 51.3, "Adding Function Security to the
Application."
The list of context attributes includes information such as current user name and the
current language. The core attributes that are now supported were derived from the
following:
The following is the list of context attributes that are automatically captured and
maintained in the ApplSession context. The values listed are the exact names of the
attributes as they are defined in the session context. Note that developers can add their
own custom attributes as well.
Security and Customization attributes:
USER_GUID - The unique GUID that identifies the currently logged in user.
Language attributes:
LANGUAGE - The language tag representing the current language.
NLS_LANG - The two-letter database language code. Derived from the language.
NLS_SORT - String sorting logic in database. This is from linguistic sorting support
project.
TIME_FORMAT - Format mask pattern for time parsing and formatting. This includes
time zone formatting.
TIME_ZONE - User's preferred time zone in Oracle E-Business Suite (EBS) R12.
Miscellaneous attributes:
ACTION - Stores the current action, such as page, being taken for tracing.
The stored name-value pairs are partitioned into separate namespaces. Oracle Fusion
Applications creates namespaces to store the context attributes.
The actual names of these namespaces and which attributes
are used in which namespace is an implementation detail that you do
not need to be aware of.
Note:
Developers can access the attribute-storage namespaces through the standard APIs
that are detailed below.
Developers may also choose to define their own namespaces, especially if they have
several attributes they wish to store on the session. Developer may currently choose
among the following APIs for initializing namespaces:
The Java and PL/SQL initializeNamespace routines are identical, just invoked from
different layersthese will dynamically create a new namespace associated with the
currently attached session, which you can then access and retrieve session attributes
from for the duration of that session.
@BeforeClass
public static void setUpBeforeClass()
throws exception
{
//
// Create a session for the OPERATIONS user
//
Using the example, guid1 and guid2 should both return the same value. The
ApplSessionUtil API is a convenience method that essentially calls the same code as
the first two lines. One difference is that ApplSessionUtil.getUserGuid() raises an
exception if the session is not available. This is true for all the ApplSessionUtil get
methods, except for getSession(), which just returns null if there is no session.
All of the centrally maintained attributes listed above have corresponding get APIs
available. The following example shows a mechanism for getting generic attributes.
Example 494
The following example shows the API you use to fetch attributes from a particular
namespace.
Example 495
The following is a more complex example of how you might use this:
You have a view object (TestVO) where you want to always display the current user
name as one of the fields.
To always display the current user name as one of the fields:
1. Add a non-column based UserName attribute to the TestVO object.
2.
3.
Example 498
Whenever the TestVO view object is displayed, by default it will include the
current user name field.
The following example uses the SysadminInfo field that was added to the TestVO view
object to display a value when running the FND product.
Example 499
TestVO Example
assuming you have initialized the connection to use sessions properly. For detailed
information about the FND_GLOBAL package, see the javadoc.
50
Implementing Oracle Fusion Data Security
50
This chapter describes how to use Oracle Fusion Data Security to enforce security
authorization for access and modification of specific data records in an Oracle Fusion
application.
This chapter includes the following sections:
Note:
The goal of Oracle Fusion Data Security is to authorize a user to perform specified
actions on selected data. It can secure rows and attributes of a database object and
relies on OPSS to provide the authentication services for OPSS principals (users,
Implementing Oracle Fusion Data Security 50-1
groups, or roles). It answers the question "Who can do what on which set of data".
Who refers to the OPSS user or group (or role), what is the action, and which is the
subset of data that can be accessed.
You can use Oracle Fusion Data Security to either restrict the rows that are returned by
a given query based on the intended business operation or restrict the actions that are
available for a given row.
Oracle Fusion Data Security assumes that the connection or
session provided to it has been initialized properly with the
appropriate user session user context, as described in Chapter 49,
"Implementing Application User Sessions." In this chapter, the user
session is specifically an application user session (ApplCore). The
application user session is the session that Oracle Fusion Data Security
expects to see.
Note:
The purpose of data security is to model and enforce security authorization for a
specific data record or a set of records. Data security provides access control within
Oracle Fusion applications on the data a user can access and the actions a user can
perform on that data. Oracle Fusion application rely on data security to restrict access
to individual data that is displayed on a page that may display after the user has
selected a menu or menu option.
For additional information about Oracle Fusion Data Security, see the product-specific
security guides.
The following are some use cases where Oracle Fusion Data Security can be utilized:
Grant read action on expense reports to managers of the current employee when
the manager is granted Expenses Administrator role.
Administer the list of documents available to an end user in a Document
Management System (DMS) based on Document Categories.
Show the list of Sales Opportunities available to a Sales Head of an organization
based on region.
Allow a Human resources (HR) Benefits Administrator to only administer the
employees whose last name begins with A-F.
Allow a HR Administrator to only administer the employees in a given region.
In Oracle Fusion Data Security, data that must be secured is identified as resources.
These resources are database tables or views. Policies that control which data that a
user has access and can perform actions, can be made on a row instance or condition.
The following figure illustrates the logical data model implemented by Oracle Fusion
Data Security.
An instance is a row of data and is identified by the primary key value of the row in the
resource's storage table. A condition is a group of row instances whose membership is
determined by a rule in the form of a SQL predicate, which must be applicable to the
WHERE clause of a single-table query against the resource's storage table.
For example, each row in the Purchase Order table is an instance of the Purchase
Order resource. The purchase order number is the primary key that identifies a
particular purchase order instance. You can create an condition with the predicate "PO_
NUMBER=100", which contains just one row of data. Purchase orders from the West
region can be put into a condition that is defined by the predicate "REGION='WEST'". A
condition that contains all the rows of data in the resource's storage table can be
defined by the predicate "1=1".
Memberships of a condition are dynamic in many ways, such as:
Condition membership rules may contain any valid SQL attributes, such as
columns of a table. Adding new instances or updating existing instances may
affect the membership of a condition. Using the above Purchase Order example, if
the predicate is "REGION='WEST'", new purchase orders in the region of West will
automatically become a member of the condition.
When an action is granted to an OPSS application role (also called a duty role by
Oracle Fusion Applications) on a condition it can be parameterized. Using the
Purchase Order example, the condition may be defined by the predicate
"REGION=&PARAM" where the parameter PARAM is associated with different regions.
When an action is granted on a condition, it may be done for a particular value of
the parameter, such as a sales manager in the West region may have an action
granted on a Region condition with the parameter value West.
The condition rules may not reveal any membership at all. It can just be a WHERE
clause to filter rows based on runtime user session variables.
To grant data security actions to a user, you must first identify the resources that you
want to secure, define conditions on those resources, and then grant specific actions on
these conditions to the application role to which the user belongs.
50.1.1 Terminology
Resource: A resource on which data security is enforced, such as a purchase order.
Resources are stored in the Oracle Fusion Applications FND_OBJECTS table. Note that
Oracle Fusion Applications database tables are sometimes called FND tables, where
FND refers to resources in the "foundation" tables.
Note:
Any action granted on a row instance implies that the Oracle Fusion Data Security
runtime system always has the ability to query the instances. This can be used by a
standard Virtual Private Database (VPD) policy function to provide default query
filtering. However, this does not mean that you have the ability to view or query
because the ability to view a row of the resource is secured by an action.
In the context of a specific row instance, the policies specify the set of actions that
can be performed on a data record.
Resource access can be tested using the Oracle Fusion Data Security authorization
checking API. Policies are stored in FND_GRANTS table.
VPD - Virtual Private Database: Provides the ability to dynamically attach a predicate
at runtime to all queries issued against a database object (table or view). This feature is
available in Oracle RDBMS. For more information about implementing VPD, see
Section 50.1.5, "Integrating Oracle Fusion Data Security with Virtual Private Database
(VPD)".
Security Policy: A PL/SQL function developed to return a predicate added by VPD to
a query. This function is bound to a table or view for some or all of DML statement
types: SELECT, INSERT, UPDATE, DELETE.
50.1.2 Integrating Oracle Fusion Data Security with Oracle Platform Security Services
(OPSS)
When integrating Oracle Fusion Data Security with Oracle Platform Security Services
(OPSS) to support making policies to OPSS principals, it is important to understand
that OPSS principals may be defined in third-party systems and this data does not
exist in the database. At runtime when a user session is created, the user information
for that session and the flattened list of roles (to include role hierarchies) for the user of
that session is propagated to the database. The roles available in a user session may be
different from all the roles that a user may potentially have based on the
authentication mechanism used, such as password vs. biometrics, authentication level
of DMZ vs. non-DMZ, and so on.
50.1.3 Integrating Data Security Task Flows into Oracle Fusion Functional Setup
Manager
Every Oracle Fusion application registers ADF task flows for setup activities with a
product called Oracle Fusion Functional Setup Manager. These task flows are available
from the Fusion Applications Setup and Maintenance work area and enable customers
and implementers to set up and configure business processes and products. For more
information about data security tasks, see the product-specific security guides.
If data security task flows are used in a web application, that web application must be
configured to use ADF Security to enable authentication and authorization so that the
correct data security predicates are generated.
Additionally, ADF Security controls access to a specific task flow, and users who do
not have the required privilege cannot view the task flow. For more information about
how to implement function security privileges and roles, see Chapter 51,
"Implementing Function Security."
The following table lists the task flows and their parameters.
Table 501
Task Flow
Name
Parameters
Passed
Manage
Database
Resources
/WEB-INF/oracle/apps/fnd/
applcore/dataSecurity/ui/
taskflow/DBResourceTF.xml
Manage
Database
Resource
/WEB-INF/oracle/apps/fnd/
mode = edit
applcore/dataSecurity/ui/
dbResourceId
taskflow/CreateDBResourceTF.xml
Goes to the
None.
Edit page for a
database
resource.
Manage
Database
Resource
Conditions
/WEB-INF/oracle/apps/fnd/
mode = edit
applcore/dataSecurity/ui/
dbResourceId
taskflow/CreateDBResourceTF.xml
panelTab =
conditions
Goes to the
Conditions tab
of the database
resource Edit
page.
Manage
Database
Resource
Actions
/WEB-INF/oracle/apps/fnd/
mode = edit
applcore/dataSecurity/ui/
dbResourceId
taskflow/CreateDBResourceTF.xml
panelTab =
actions
Goes to the
Actions tab of
the database
resource edit
page.
Manage
Policy
/WEB-INF/oracle/apps/fnd/
applcore/dataSecurity/ui/
taskflow/PolicyTF.xml
This is the
Create/Edit
Policy page
module_id
(optional)
grantGuid
(optional)
dbResourceId
(optional)
Behavior
Comments
Goes to the
Search page
for database
resources.
None.
appId (optional)
roleName
(optional)
50.1.5 Integrating Oracle Fusion Data Security with Virtual Private Database (VPD)
Note that integrating with VPD is optional.
The database has a feature called Virtual Private Database (VPD). VPD allows an
arbitrary WHERE clause to be appended to a table, view, or synonym. By doing so, the
WHERE clause restricts the rows available. A PL/SQL function is written that returns the
WHERE clause and a policy is enabled on a particular view or synonym that references
50-6 Developer's Guide
Managing Data Security Artifacts in the Oracle Fusion Data Security Policy Tables
3.
Add a policy.
Add a policy in the database that will associate the policy function with the view.
At runtime, in LOVs or UIs, wherever you want to display the rows that the user has
select access to, they simply select off that view.
50.2 Managing Data Security Artifacts in the Oracle Fusion Data Security
Policy Tables
Oracle Fusion Data Security artifacts include resources, row instances, conditions,
actions, aggregate actions, and so on. Data security artifacts are stored in the Oracle
Fusion Data Security repository and are customized using Oracle Authorization Policy
Manager, which can be accessed by the developer through Oracle Fusion Functional
Setup Manager, from the Manage Data Security task available in the Setup and
Maintenance work area of any Oracle Fusion Setup application.
After the developer selects the Manage Data Security task in
Oracle Fusion Functional Setup Manager, the environment redirects to
the data security customization user interface provided by Oracle
Authorization Policy Manager. In this document, although the data
security customization tool is identified as Oracle Authorization
Policy Manager, be aware that the tool must be accessed through
Oracle Fusion Functional Setup Manager.
Note:
Managing Data Security Artifacts in the Oracle Fusion Data Security Policy Tables
2.
inherit the appropriate duty role for your product family from the duty roles listed
in Table 502.
3.
Use cases:
CRM Administrator logs in. He must be able to manage the CRM database
resources. He must NOT be able to access the HCM resources.
Super Administrator (Application Developer) logs in. He must be able to manage
conditions for all Oracle Fusion resources.
Oracle Fusion Applications delivers the duty roles and policies as specified.
2.
Oracle Authorization Policy Manager (APM) authors enterprise roles and maps
the duty roles listed in Table 502. A security manager uses APM to define the
relationship between a duty role and enterprise roles.
APM can create three enterprise roles, one per pillar. (Multiple product
families can be included into one pillar).
APM can include the product family level duties into the above enterprise
roles, as appropriate.
APM must ensure that they have the correct role GUIDs for the duty roles.
(See the jazn-data.xml file.)
3.
A security manager can create their own enterprise roles if required. They can
determine which objects can be managed by specific data security administrators
by including the duty roles into their custom enterprise roles. Security managers
are expected to use the APM console to perform enterprise role to duty role
mapping.
4.
Reasoning:
Data security policies are made to duty roles as the default approach. This makes it
possible for the security manager to quickly assemble the duties to an enterprise role
and use the Oracle Fusion reference implementation quickly. Granting them to an
enterprise role means that the security manager must duplicate the policies to any new
enterprise roles they create. Enterprise roles are highly guarded and should be created
and used only if absolutely needed.
50.2.2 What You May Need to Know About Administering Oracle Fusion Data Security
Policy Tables
The data security administration UI is secured so that only administrators are
permitted to create and manage security policies.
You cannot view the database resources or manage policies
from the Functional Setup Manager if you have not granted the
appropriate data security manage privileges to your administrators.
Note:
The following table lists the duty roles that have been predefined by the Oracle Fusion
security reference implementation to allow access to users to manage data security.
These roles are administered at the product family level to manage resources and
policies for that specific product family. The security reference implementation
50-8 Developer's Guide
Family
Duty Role
CRM
HCM
FSCM
APM - CRM
APM - HCM
APM - FSCM
Making the Oracle Fusion Data Security Provider the Data Security
dataSecurityProviderClass=
"oracle.apps.fnd.applcore.dataSecurity.util.FndDataSecurityProvider"
Example 502
<sec:JaasSecurityContext intialContextFactoryClass=
"oracle.adf.share.security.JAASIntialContextFactory"
jaasProviderClass="oracle.adf.share.security.providers.jps.JpsSecurity.Context"
dataSecurityProviderClass=
"oracle.apps.fnd.applcore.dataSecurity.utl.FndDataSecurityProvider"
authorizationEnforce="true"
authenticationRequire="true"/>
In Oracle JDeveloper, the design time tools for ADF Business Components are shaped
so that the Oracle Fusion Data Security Provider will be automatically registered as the
default when you launch JDeveloper with the Oracle Fusion Applications Developer
role selected. This occurs when the developer runs the Configure ADF Security wizard
for the ADF data model project.
At runtime, the ADF Business Components invocation of Oracle Fusion Data Security
Provider happens automatically only for standard operations. For custom operations
that are available on the entity object, you must invoke the Oracle Fusion Data
Security authorization checking API manually, as described in Section 50.3.4, "How to
Perform Authorization Checks for Custom Operations."
There may be other reasons to invoke Oracle Fusion Data Security APIs manually to
determine the SQL predicate for a given action or to do an authorization check. For
example, you might query VPD policies written based on fnd_data_
security.getSecurityPredicate() to enforce data security rules.
Oracle Fusion Data Security Provider only implements row-level authorization check.
It does not implement a column-level authorization checking API. Even though Oracle
Fusion Data Security can be used to perform column-level security using custom
actions, it is not integrated with ADF Business Components directly using the data
security provider interface. Wherever column-level security is needed, you must use a
custom action.
The default Oracle Fusion Data Security provider
implementation assumes that the object name in FND_OBJECTS for the
entity being secured is the database table/view name backing this
entity. If the entity is a translatable entity (MLS entity), then the
backing database table/view name is identified by Oracle Fusion
Middleware Extensions for Applications custom property fnd:OA_
BASE_TABLE. If the default behavior is not sufficient, one can set a
custom property on the entity object to identify the name of the object
from the Oracle Fusion Data Security repository that will be used to
secure this entity. The custom property OA_DS_BASE_TABLE should be
set to accomplish this.
Note:
At runtime, for the read operation, ADF Business Components automatically invokes
the Oracle Fusion Data Security Provider (which is registered with ADF Business
Components in the adf-config.xml file when you secure the read operation on the
entity object), to identify the WHERE clause (if any) that must be added to the SQL
statement for the entity object. This is done before executing the query.
After the query has been executed, ADF Business Components invokes the Oracle
Fusion Data Security Provider again to perform the authorization check for standard
operations, (update and removeCurrentRow), to see if the user has update and delete
access to that row.
In the case of custom privilege that you define, you must create a view criteria and
apply it to the view instance that you want the application module data model to filter.
In either case, the user must have sufficient privileges to view the filtered rows. The
action name that you define in Oracle Fusion Data Security must match the custom
action specified on the entity object.
To secure the rows displayed to a user for read privilege:
1. In the Application Navigator, double-click the entity object.
2.
In the overview editor for the entity object, click the General navigation tab and
expand the Security section.
3.
In the overview editor, click the Query navigation tab and expand the View
Criteria section, then click Add New View Criteria to add a dummy view criteria.
The following figure shows a dummy view criteria that has been added in the
overview editor for the view object.
3.
In the Edit View Criteria dialog, create a dummy view criteria with no view
criteria items and name the view criteria using the following format:
FNDDS__privilegeName__objectName__objectAlias
where:
privilegeName is the privilege name that is used to filter the data.
objectName is the name of the secured database resource in the FND_OBJECTS table.
objectAlias is optional and is the alias for the resource.
Note:
4.
Select Both for the Query Execution Mode, as shown in the following figure.
The query execution mode for the dummy view criteria must be set to Both. If you
leave the default setting Database selected, then the ADF Business Components
association consistency feature will not work properly.
5.
In the application module overview editor, select the Data Model navigation tab
and select the view instance to filter, then click Edit to apply the view criteria, as
shown in the following figure.
Alternatively, you can apply the view criteria at runtime in your code by calling
the view object's applyViewCriteria(viewCriteriaName) API.
Figure 505 Application Module Overview Editor Edit View Instance Dialog
50.3.3 What Happens at Runtime: How Oracle Fusion Data Security Filters View
Instance Rows
The implementation for securing data by applying a view criteria on the view object
instance is handled in the Oracle Fusion Middleware Extensions for Applications
layer. It requires the use of Oracle Fusion Middleware Extensions for Applications
base classes to achieve this behavior. The OAViewCriteriaAdapter class is the default
view criteria adapter class set as the ADF Business Components application module in
the OAApplicationModuleImpl class. This functionality is provided in the
OAViewCriteriaAdapter.getCriteriaClause() method to fetch the security predicate.
In this implementation, the method uses the metadata on the view criteria to invoke
Oracle Fusion Data Security APIs that fetch the security predicate.
In the case of a custom operation secured by a custom action, multiple data security
view criteria can be applied to the view object. When multiple view criteria are
applied, the WHERE clause corresponding to each view criteria is AND'ed. This is
standard behavior for ADF Business Components. However, when a single data
security view criteria for a given privilege is applied, the instance sets corresponding
to that privilege are OR'ed. When multiple privilege checks are applied, the instance
sets of a privilege are AND'ed with the instance sets of another privilege. For example,
for an object, for privilege priv1, the user has instance sets IS1, IS2. For the same object
for privilege priv2, the user has instance sets IS3, IS4. If both priv1 and priv2 checks
are applied simultaneously (using view criteria), the WHERE clause would be (IS1 OR
IS2) AND (IS3 OR IS4).
that are available on the entity object, you must invoke the authorization check API
manually as shown in the following example.
Example 503
if(row.getSecurityHints().allowsOperation("ApprovePO").hasPermission())
// code for PO approval
else
// display error message
There may be other reasons to invoke Oracle Fusion Data Security APIs manually to
determine either the SQL predicate for a given action or to do an authorization check.
For example, VPD policies written based on fnd_data_
security.getSecurityPredicate() to enforce data security rules.
50.3.5 How to Test Privileges Using Expression Language Expressions in the User
Interface
You can test data security actions for standard (read, update, delete) or custom actions
on an entity row using Expression Language or Groovy expression exposed on the
entity row.
The Expression Language and Groovy expressions described below work by default
when the view object is an updateable view object based on an entity object. If the
view object is a read-only view object (based on an entity object) or an expert mode
view object, then Expression Language or Groovy expression will not work unless you
create a transient attribute with a custom Groovy expression that invokes Data
Security to check action. The transient attribute can be used to control the rendering of
some other attribute in the read-only view object on the page.
The following example shows the Expression Language expression to use on ADF
bindings for view object attributes.
Example 504
#{bindings.<attrName>.hints.allows.<privilegeName>}
For example, your UI might have a button to control the grant for the
UpdateEmployeeSalary privilege; the Expression Language expression on the
button may be defined as shown in the following example.
Example 505
#{bindings.PersonId.hints.allows.UpdateEmployeeSalary}
When this expression is invoked, Oracle Fusion Data Security Provider checks to
see if the user identified by the PersonId attribute has access to the current row for
UpdateEmployeeSalary privilege. Note that even though the attribute name is
included in the Expression Language expression, it is really doing a row-level
security check.
Do not use the expression shown in the following example as Oracle Fusion Data
Security Provider does not implement a column-level security check interface. If
you want to perform a column-level security, use the expression shown in the
previous example with a custom action.
Example 506
#{bindings.<attrName>.hints.<attrName>.allows.<privilegeName>}
The following example shows the expression to use for table iterators:
Example 507
#{row.hints.allows.<privilegeName>}
Do not use the expression shown in the following example as Oracle Fusion Data
Security Provider does not implement column-level security check interface. If you
want to do column-level security, use the expression shown in the previous
example with a custom action.
Example 508
#{row.hints.<attrName>.allows.<privilegeName>}
When using Expression Language, be careful if you decide to set the expression on
the rendered attribute. When PPR is enabled, ADF Faces does not handle the
rendered attribute on a UI component well.
Tip:
If you want to use Data Security expressions on the rendered attribute, you must
manually identify the partial trigger UI components on the page and then set the
partialTriggers attribute on the parent UI component of the UI component that
has the data security Expression Language expression. Do not use visible
attribute on the UI component as this could potentially be a security hole when the
UI component and its data is rendered by the server and sent to the client. The
visible attribute is a client-side attribute to show or hide the UI component on
the browser.
When using Groovy expressions, use the expression shown in the following
example if the view object is an updateable view object based on an entity object.
Example 509
object.getSecurityHints().allowsOperation("updateCategory").hasPermission()
When using Groovy expressions, use the expression shown in the following
example if the view object is a read-only view object based on an entity object or
an expert mode view object. Create a transient attribute on the view object of type
Boolean and Value Type Expression. The transient attribute can be used to control
the rendering of some other attribute in the read-only view object on the page.
For example, you have a read-only view object with the attributes PersonId, Name,
Gender, and Age and you want to control the rendering of the Gender attribute on
the UI. First, you should create a transient attribute by name
TransientGenderAttr and set the Groovy expression as mentioned above. The
following example shows an EL expression to conditionally render the UI
component for the Gender attribute:
You must make sure that the parent UI component of this UI component has the
partialTriggers set to the appropriate UI component IDs. Also, in this scenario,
make sure to have the binding available for the transient attribute in the view
object, and to set the rendered="false" on the UI component for the transient
attribute, or comment out the UI component in the JSF page.
1.
2.
Register your database view or table that you want to secure with Fusion
Oracle Data Security.
b.
Identify the conditions that you want to make available on the registered business
resource:
Tip: Conditions may be static or parameterized. For details about
parameterizing conditions, see Section 50.4.2, "How to Use
Parameterized Conditions When Securing a Business Object."
3.
Identify the actions that you want to secure this business resource:
4.
b.
Register the various actions that are part of the aggregate action.
c.
Note:
However, this step is still required as runtime queries are fired against
the fnd_compiled_menu_functions table instead of the fnd_menu_
entries table.
d.
5.
Identify the Oracle Platform Security Services (OPSS) principals (OPSS users and
roles) for which you want to make policies.
OPSS principals do not exist in the database and are managed by OPSS Policy
Store, which may be a third-party system.
6.
Make appropriate aggregate action policies on the business resource to OPSS users
and roles.
Policies can be made on a row instance, on the resource globally, or for a condition,
which may be parameterized.
50.4.1 How to Use Oracle Fusion Data Security to Secure a Business Object
This example shows how to secure a document categories business resource. The
document categories business data is stored in the FND_DEMO_DOC_CATEGORIES table.
The following table lists the document category definitions for the table.
Table 503
Name
Value
CATEGORY_ID
APPLICATION_ID
NUMBER
CREATION_DATE
CREATED_BY
LAST_UPDATE_DATE
LAST_UPDATED_BY
LAST_UPDATE_LOGIN
NUMBER
NAME
START_DATE_ACTIVE
DATE
END_DATE_ACTIVE
DATE
ATTRIBUTE_CATEGORY
VARCHAR2(30)
VARCHAR2(150)
DEFAULT_DATATYPE_ID
NUMBER
3.
4.
Identify the actions securing this entity object for read, update, and delete operations
as read, update, delete. Additionally, custom actions with the names FND_DEMO_
ATTACHMENT_VIEW, FND_DEMO_ATTACHMENT_UPD, and FND_DEMO_ATTACHMENT_DEL may
be created for testing.
5.
Identify aggregate actions for which policies are made for this entity:
6.
7.
8.
Make policies to OPSS principals admin and regularUserRole for the FND_DEMO_
DOC_CATEGORIES business resource.
An administrator can reuse the first condition for several different policies granted to
different locations and the second condition can be reused for policies granted to
different titles. For example, one policy might use OIS1 to grant to 'WEST' by putting
'WEST' in FND_GRANTS.PARAMETER1, while another policy would reuse the same OIS1 to
grant to 'EAST'. At runtime, the FND_DATA_SECURITY package substitutes the
PARAMETER values from the FND_GRANTS table to the OISs granted.
When the data security system runs the predicates that have been defined in the
conditions, it does a simple replace-style parsing of the predicate. For example, &TABLE_
ALIAS is replaced by the table alias of the resource table, if it was passed to the get_
security_predicate() call, and &GRANT_ALIAS is replaced by the policy table alias.
Caution: The &TABLE_ALIAS and &GRANT_ALIAS column qualifiers
must be included in the predicates of all conditions to keep possible
duplicate column names from causing collisions.
float- NUMBER that can have a decimal point. For example, 123.456.
This should be stored in the canonical format, using FND_NUMBER.NUMBER_TO_
CANONICAL(). (The canonical format is based on the FND_NUMBER package
'FM999999999999999999999.99999999999999999999'.)
You should use canonical format because the string must be stored in a format that
doesn't need to be converted if the data is passed between systems that use
different decimal characters or other number formatting.
date- DATE calendar date, optional time. For example, 2009/04/30 11:32:32.
This should be stored in canonical format, using FND_DATE.DATE_TO_CANONICAL().
(The canonical format is based on the FND_DATE package, 'YYYY/MM/DD
HH24:MI:SS'.
You should use canonical format because the string must be stored in a format that
doesn't need to be converted if the data is passed between systems that use
different date formats.
The following example shows Integer equality formats that you should NOT use.
Example 5014 Incorrect Integer Equality Formats
&TABLE_ALIAS.ITEM_ID = to_number(&GRANT_ALIAS.PARAMETER1)
&TABLE_ALIAS.ITEM_ID = fnd_data_security.to_int(&GRANT_ALIAS.PARAMETER1)
You must use to_char() as it is built-in and performs much faster than fnd_data_
security.to_init().
When used with data security parameters, to_number() causes Invalid Number
exceptions. This in turn, will make SQL statements abort if the to_number() gets run
on policy parameters, which store non-numeric data such as DATE or VARCHAR2 data.
The policies table will almost certainly contain some non-numeric data in a policy.
It may be decided to run a to_number(&GRANT_ALIAS.PARAMETER1) in a big statement
on more policy rows than intended, and filter the rest of the rows later in the
execution. This will definitely cause your SQL statement to fail so therefore, you must
not have to_number() around any of the policy parameters in your predicate.
Tip: The routine fnd_data_security.to_init() was written to
avoid this problem; it is basically a wrapper over to_number(), which
traps the Invalid Number exception. Therefore, if the execution plan
involves operating against policies that don't apply, they won't cause
the whole statement to fail. However, because of performance issues,
to_char() is the preferred solution.
Integer Range:
The following example shows the correct Integer range format to use.
Example 5015 Integer Range Format
&TABLE_ALIAS.LEVEL >= fnd_data_security.to_init(&GRANT_ALIAS.PARAMETER1)
The following example shows Integer range formats that you should NOT use.
Example 5016 Incorrect Integer Range Formats
&TABLE_ALIAS.LEVEL >= to_number(&GRANT_ALIAS.PARAMETER1)
to_char(&TABLE_ALIAS.LEVEL) >= &GRANT_ALIAS.PARAMETER1
The following example shows Float equality formats that you should NOT use.
Example 5018 Incorrect Float Equality Formats
to_char(&TABLE_ALIAS.TEMP) = &GRANT_ALIAS.PARAMETER1
&TABLE_ALIAS.TEMP = to_number(&GRANT_ALIAS.PARAMETER1)
&TABLE_ALIAS.TEMP = fnd_data_security.to_decimal(&GRANT_ALIAS.PARAMETER1)
Using to_number() without a format could fail if the environment is set up to use
comma as the decimal character and the parameter is stored with a period as the
decimal character. Using to_char() without an explicit format could convert to a
comma-format number, which would not match the period-format number. Because of
these potential problems, you must explicitly provide the canonical format.
Float Range:
The following example shows the correct Float range format to use.
Example 5019 Float Range Format
&TABLE_ALIAS.TEMP > fnd_data_security.to_decimal(&GRANT_ALIAS.PARAMETER1)
The following example shows Float range formats that you should NOT use.
Example 5020 Incorrect Float Range Formats
to_char(&TABLE_ALIAS.TEMP,'FM999999999999999999999.99999999999999999999') >
&GRANT_ALIAS.PARAMETER1
to_char(&TABLE_ALIAS.TEMP) > &GRANT_ALIAS.PARAMETER1
&TABLE_ALIAS.TEMP > to_number(&GRANT_ALIAS.PARAMETER1)
&TABLE_ALIAS.TEMP > fnd_data_security.to_init(&GRANT_ALIAS.PARAMETER1)
You should not use to_char() because it does not order correctly.
You should use fnd_data_security.to_decimal() instead of fnd_data_security.to_
init() because the data may contain decimals, which to_init() cannot handle.
Date Equality:
The following example shows the correct Date equality format to use.
Example 5021 Date Equality Format
to_char(&TABLE_ALIAS.ACTION_DATE,'YYYY/MM/DD HH24:MI:SS') = (&GRANT_
ALIAS.PARAMETER1)
The following example shows Date equality formats that you should NOT use.
Example 5022 Incorrect Date Equality Formats
to_char(&TABLE_ALIAS.ACTION_DATE) = (&GRANT_ALIAS.PARAMETER1)
&TABLE_ALIAS.ACTION_DATE = fnd_data_security.to_date(&GRANT_ALIAS.PARAMETER1)
&TABLE_ALIAS.ACTION_DATE = to_date(&GRANT_ALIAS.PARAMETER1)
The following example shows Date range formats that you should NOT use.
Example 5024 Incorrect Date Range Formats
&TABLE_ALIAS.HIRE_DATE > fnd_data_security.to_date(&GRANT_ALIAS.PARAMETER1)
to_char(&TABLE_ALIAS.HIRE_DATE) > (&GRANT_ALIAS.PARAMETER1)
&TABLE_ALIAS.HIRE_DATE > to_date(&GRANT_ALIAS.PARAMETER1)
In this case, you can use to_char() with a format mask because the canonical format
maintains proper ordering of the character domain.
50.4.4 What You May Need to Know About Creating Application Roles
Before testing the application in the staging environment, any custom application roles
that you created will need to be created in the LDAP application policy store. These
new application roles will receive new GUIDs and any data security policies defined
for application roles of the same name must have their GUIDs reconciled. For details
about reconciling GUIDs in the data security repository, see the "Reconciling GUIDs"
section in the Oracle Fusion Applications Administrator's Guide.
50.5.1 How to Use the DataSecurityAM API to Get Session Context Information
The DataSecurityAMImpl class is in the
oracle.apps.fnd.applcore.dataSecurity.dataSecurityService.applicationModul
e package. It is the container for all data security resources provided by Oracle Fusion
Middleware Extensions for Applications. This class contains core methods to:
Check action for the current user, as shown in the following example.
Where DataContext is a container class that represents the resource and optionally
the primary keys of that resource for which data security check must be done. It
has the following attributes: ObjectName, PK1, PK2, PK3, PK4, PK5.
Privilege and DataContext classes are in the
oracle.apps.fnd.applcore.dataSecurity.util package.
Note:
If the action is granted to an Oracle Platform Security Services (OPSS) role in FND_
GRANTS table, then the system retrieves all the OPSS roles that the user has access
to, and checks if one of them matches with the OPSS role to which the action has
been granted.
Get the security predicate associated with a given action on a given resource for
the current user, as shown in the following example.
Get all the actions available on a given row instance for the current user, as shown
in the following example.
Get all the aggregate actions available on a given row instance for the current user,
as shown in the following example.
As shown in the following example, static APIs are also provided in the
DataSecurityAMImpl class for the above core methods that take in a DBTransaction
object.
Example 5030 Static API Examples
public static boolean testPrivilege(Privilege privilege, DataContext context,
DBTransaction dbTxn)
public static String getSecurityPredicate(Privilege privilege,
DataContext dataContext, String grantInstanceType, String statementType,
String tableAlias, DBTransaction dbTxn)
public static String[] getAggregatePrivileges(DataContext dataContext,
DBTransaction dbTxn)
public static String[] getPrivileges(DataContext dataContext, DBTransaction dbTxn)
50.5.2 How to Use the PL/SQL Data Security API to Check User Privileges
Oracle Fusion Middleware Extensions for Applications provides the FND_DATA_
SECURITY PL/SQL package for the data security system.
FUNCTION check_privilege determines whether the user is granted a particular action
for a particular row instance, as shown in the following example. The user is
determined from the user session context.
Example 5031 FUNCTION check_privilege API
FUNCTION check_privilege
(
p_api_version
IN NUMBER,
/* API Version of this procedure - currently 1.0 (Required) */
p_privilege
IN VARCHAR2,
/* Name of the action (Required) */
p_object_name
IN VARCHAR2,
/* Resource on which the policy should be checked from FND_Objects table
(Required) */
p_instance_pk1_value
IN NUMBER DEFAULT NULL,
/* p_instance_pk(1...5)_value (Required)
Primary key values for the row instance, with order corresponding
to the order of the PKs in the FND_Objects table. Most resources have
only a few primary key columns so let the higher, unused columns
default to NULL.
NOTE: The caller must pass an actual primary key and it must be the
primary key of an actual instance (row). */
p_instance_pk2_value
IN NUMBER DEFAULT NULL,
p_instance_pk3_value
IN NUMBER DEFAULT NULL,
p_instance_pk4_value
IN NUMBER DEFAULT NULL,
p_instance_pk5_value
IN NUMBER DEFAULT NULL
)RETURN VARCHAR2;
p_statement)_type
IN VARCHAR2 DEFAULT 'OTHER',
/* (Optionsl) statement type: 'OTHER', 'VPD', 'EXISTS' = to check existence. */
x_predicate
OUT NOCOPY VATRCHAR2,
x_return_status
OUT NOCOPY VARCHAR2,
p_table_alias
IN VARCHAR2 DEFAULT NULL
/* (Optional) */
);
Data security should only be used when the combined predicates (Applications Code
+ Data Security Predicates) are efficient, and return only relevant rows. Most queries
should only return either one row or just a few rows. The maximum number of rows
that data security should consider operating on is 100 rows. If you are seeing
performance problems with queries that apply data security to more than 100 rows,
the query must be made more selective. Blind queries against tables secured with data
security are not allowed.
Note: Data security is not designed as a means to limit the number of
rows returned; there must always be another selective WHERE clause
before the data security predicate.
Note:
Note:
Important Note
Before invoking a WLST script you must run the following wlst.sh script on Oracle
WebLogic Server to ensure that the required JARs are added to the class path.
>sh $ORACLE_HOME/common/bin/wlst.sh
After you invoke the wlst.sh script, you can connect to Oracle WebLogic Server in
offline mode, that is, the data security script does not require a connection to a running
server to operate.
Output file's directory path where you want the script's output file to be saved.
Application name for which you want to run the script. The application name is
the deployment name in Oracle WebLogic Server. For example, SalesApp#V3.0.
Note that the version part of the application name is specified with a # symbol: for
example, #V3.0 in SalesApp#V3.0.
Application source path of the deployed application. For example,
/scratch/myself/view_storage/myself_main_gene_
testing/system11.1.1.4.37.56.69/DefaultDomain/servers/DefaultServer/upl
oad/DemoSecurity/V2.0/app/DemoSecurity.ear. The source path can be obtained
from Oracle WebLogic Server Administration Console, under the Deployments
section for the application.
Session cookie value created for the logged-in user for whom you want to validate
data security roles and privileges. Optional (you can press Enter to skip). To obtain
the session cookie, you must log into the application as the user whose roles and
privileges you want to examine. After logging into the application, from the
browser, open the cookies window (for example, in Internet Explorer, you can
display cookies from the Temporary Internet Files and History Settings dialog).
Under the site oracle.com, locate the cookie named <DATABASE_SID>_FND_SESSION
and copy the value, which is the required session cookie. If you do not find this
named session cookie, it means that the applications context is not created for your
application.
Tip: You can run the application context diagnostic script by
pressing Enter when the data security script prompt you to enter the
value for session cookie for your application. This will invoke the
applications context script and validate the applications context
configuration. For details about the applications context script, see
Section 50.7.2, "How to Validate Applications Context."
Validates the session filters and filter mapping definitions in the web.xml file,
which is archived in the application EAR file. The scripts checks for the presence
of the <filter-name>ApplSessionFilter</filter-name> element and verifies
that the ApplSessionFilter mapping definition appears immediately after the
JpsFilter mapping definition, and then outputs the result to the output file
ApplsessionDiagResults.out.
Connects to the database and gets the Oracle Fusion Applications FND table
metadata for the application context. The script checks the value of the Name,
Datatype, Precision, and isNullable attributes for each column in the tables,
Implementing Oracle Fusion Data Security 50-31
validates the database schema for each table, and then outputs the result to the
output file ApplsessionDiagResults.out.
Output file's directory path where you want the script's output file to be saved.
Application name for which you want to run the script. The application name is
the deployment name in Oracle WebLogic Server. For example, SalesApp#V3.0.
Note that the version part of the application name is specified with a # symbol: for
example, #V3.0 in SalesApp#V3.0.
Application source path of the deployed application. For example,
/scratch/myself/view_storage/myself_main_gene_
testing/system11.1.1.4.37.56.69/DefaultDomain/servers/DefaultServer/upl
oad/DemoSecurity/V2.0/app/DemoSecurity.ear. The source path can be obtained
from Oracle WebLogic Server Administration Console, under the Deployments
section for the application.
Session cookie value created for the logged-in user for whom you want to validate
data security roles and privileges. Optional (press Enter to skip). To obtain the
session cookie, you must log into the application as the user whose roles and
privileges you want to examine. After logging into the application, from the
browser, open the cookies window (for example, in Internet Explorer, you can
display cookies from the Temporary Internet Files and History Settings dialog).
Under the site oracle.com, locate the cookie named <DATABASE_SID>_FND_SESSION
and copy the value, which is the required session cookie. If you do not find this
named session cookie, it means that the applications context is not created for your
application.
Object-centric task flow lets the end user display and secure a single business
object. The flow displays the end user's business object selection and then displays
all the application roles that may be granted access to that object. This task flow
simplifies the task of securing a business object across the organization.
Role-centric task flow (also called the Profile task flow) lets the end user select an
application role profile and secure multiple business objects pertaining to that
profile. The flow displays the end user's application role profile selection and
displays all the securable business objects that the profile may access. This task
flow is also called the profile task flow since every end user is assigned to a profile
that corresponds to an enterprise role mapped to a hierarchy of application roles.
Note that the role-centric task flow and the object-centric task flow present the end
user with different views of the same security functionality. Both enable data
security and functionality security policies for permissions that the end user
selects across business objects.
Instance-level task flow lets the end user select an instance of a securable business
object (one row) for which they have access and then confer access rights to
another user or group of users. This task flow provides a way for end users to
share access rights with other members of their organization. The scope of this
task flow is different from the role-centric and object-centric task flows in that
security is limited to the business object instance. The business object itself must
already have grants made to the end user who wishes to share access.
Role management task flow lets the end user create and edit application roles. This
task flow is particularly useful when the user creates custom business objects and
wishes to grant permission to that object for a custom application role.
50.8.1 About Integrating the Data Security Task Flows into Your Application
The process of integrating the data security task flows into an Oracle Fusion
application involves understanding the input parameters of the task flow. Your
application will use a managed bean to initialize the task flow's parameters before the
application displays the task flow to the end user. The way your application references
the values of the input parameters on the bean depends on how you want to display
the task flow. Your application can display the data security task flow one of two ways:
You can display the task flow in the application's primary browser window.
You can display the task flow in the application's secondary browser window that
displays a new web page and allows the user to view the primary window while
working in the task flow.
For example, the object instance task flow user interface is well-suited to run in a
dialog. When you run this task flow in a dialog, the user can select an object in the
primary browser window, make grants on the selection in the secondary window, and
repeat for other objects without needing to reopen the primary window. The other task
flows, including the object-centric task flow, profile (role-centric) task flow, and role
management task flow, are large enough that you may want to display them in the
primary window.
The steps to integrate the data security task flows into your application will depend on
the method you choose to display the task flow. However, review the following
general steps for an overview of the process.
Before you begin:
Add the data security task flows to your project.
To integrate the data security task flows, follow these general steps.
1.
Decide whether you want your application to display the task flow in the primary
window or in a popup dialog.
2.
Create a task flow reference in your application to bind the data security task flow
to the ADF Model layer.
In JDeveloper, the reference will be generated for you when you drag and drop the
data security task flow. The way you drag and drop the data security task flow
depends on the way your application displays the task flow.
3.
Define the data security task flow's input parameters so they have page flow
scope.
Page flow scope will allow the values to be passed into the task flow from a
managed bean. The ADF Model layer component that you use to define the
parameters depends on the way your application displays the task flow.
4.
Create a managed bean and define an initialization method to populate the input
parameters for the data security task flows, as shown in Table 504.
The method you define will initialize the values before your application displays
the task flow. When displaying the page inside your application's primary
window, the initialization method must also return the value of the flow control
outcome you configure in your application's task flow to invoke the data security
task flow. The outcome return value is not needed when displaying a dialog, since
the dialog is not invoked the same way.
5.
Create a navigation button that invokes the initialization method in your method
bean.
The ADF Faces component you use to create the button depends on how you want
the data security task flow to display.
6.
Enable function security grants to be made by the data security task flows.
7.
Grant view permission to an application role that allows the end user to access the
task flow.
8.
The following table describes the input parameters that your managed bean must
initialize for each task flow.
Table 504
Parameters Passed
Behavior
Object-centric task
flow (also referred
to as
(ObjectLevelTF)
/WEB-INF/oracle/apps/fnd/
applcore/dataSecurity/ui/
taskflow/ObjectLevelFT.xml
Create and
manage grants to
multiple
application roles
for a single
business object.
objectName
Specify the list of role categories from
which the available application roles will
be fetched:
roleCategories
Specify the list of securable actions to be
displayed in the UI for the object:
actions
Specify true/false to determine
whether the View All column (supports
global grants) should appear in the task
flow UI:
disableViewAll
Specify true/false to determine
whether the Update All column
(supports global grants) should appear in
the task flow UI:
disableUpdateAll
Role-centric task
flow (also referred
to as ProfileTF)
/WEB-INF/oracle/apps/fnd/
applcore/dataSecurity/ui/
taskflow/ProfileTF.xml
Create and
manage grants to
a single
application role
profile for
multiple
business objects.
actions
Specify true/false to determine
whether the View All column (supports
global grants) should appear in the task
flow UI:
disableViewAll
Specify true/false to determine
whether the Update All column
(supports global grants) should appear in
the task flow UI:
disableUpdateAll
Table 504 (Cont.) Data Security Task Flows and Their Input Parameters
Task Flow Name
Parameters Passed
Behavior
Instance-level task
flow (also referred
to as
ObjectInstTF)
/WEB-INF/oracle/apps/fnd/
applcore/dataSecurity/ui/
taskflow/ObjectInstTF.xml
Confer existing
grants for a
single instance of
a business object
to another user
(or user group).
objectName
Specify the primary key of the object
instance for which grants will be shared:
instancePk1
instancePk2
instancePk3
instancePk4
instancePk5
Specify the list of securable actions to be
displayed in the UI for the object:
actions
Specify the ID of the customized task
flow:
taskflowId
Specify the holder of the customized task
flow parameters:
parameterMap
Role management
task flow (also
referred to as
RoleManagementTF)
/WEB-INF/oracle/apps/fnd/
applcore/dataSecurity/ui/
taskflow/RoleManagementTF.
xml
roleCategories
Specify the title of the task flow UI:
title
50.8.2 How to Configure Data Security Task Flows to Display in the Primary Window
When you integrate the task flow as a primary window, your application's task flow
invokes the data security task flow using a task flow call activity. A control flow case
defines the transition (identified with a particular outcome value) between your
application's view activity (for the calling web page) and the call activity. A navigation
button in the calling web page invokes a method on the managed bean that initializes
the task flow's input parameters and returns the expected value of the control flow
case outcome. Your application's task flow invokes the data security task flow through
the call activity reference that matches the returned outcome.
To integrate a data security task flow with your application so it appears in the
primary browser window of the application:
1.
In your application's task flow, create a call activity and specify a control flow case
from the calling web page's view activity.
The calling web page is the page in your application where you want the end user
to launch the data security UI. This is the page that will be replaced in the browser
window when the data security UI is displayed.
2.
Drop the desired data security task flow onto the task flow call activity.
3.
Edit your application's task flow configuration file to specify the data security task
flow's input parameter values on the call activity.
4.
Create a managed bean that initializes the data security task flow's input
parameters and returns the value of the outcome for the control flow case you
specified.
5.
Register the managed bean in your application's task flow configuration file.
6.
In the web page associated with the view activity, drop an ADF command button
and configure the button to invoke the managed bean's initialization method.
50.8.2.1 Creating a Task Flow Call Activity in Your Application's Task Flow
You can use a task flow call activity to call any one of the data security task flows from
your application's unbounded or bounded task flow. The task flow call activity allows
you to call the data security task flows located within the same or a different
application.
To pass parameters into the data security task flow, you specify input parameter
values on the task flow call activity. These values must correspond to the input
parameter definitions on the called data security task flow.
The following example shows the task flow call activity definition with a reference to
the object-centric data security task flow. The task flow call activity also defines the
input parameter values required by the object-centric task flow.
Example 5033 ObjectLevelTF Reference in Calling Task Flow Configuration File
<task-flow-call id="ObjectLevelTF">
<task-flow-reference>
<document>/WEB-INF/oracle/apps/fnd/applcore/dataSecurity/ui/taskflow/
ObjectLevelTF.xml</document>
<id>ObjectLevelTF</id>
</task-flow-reference>
<input-parameter>
<name>objectName</name>
<value>#{pageFlowScope.objectName}</value>
</input-parameter>
<input-parameter>
<name>roleCategories</name>
<value>#{pageFlowScope.roleCategories}</value>
</input-parameter>
<input-parameter>
<name>actions</name>
<value>#{pageFlowScope.actions}</value>
</input-parameter>
<input-parameter>
<name>disableViewAll</name>
<value>#{pageFlowScope.disableViewAll}</value>
</input-parameter>
<input-parameter>
<name>disableUpdateAll</name>
<value>#{pageFlowScope.disableUpdateAll}</value>
</input-parameter>
</task-flow-call>
The following example shows the task flow call activity definition with a reference to
the role-centric data security task flow. The task flow call activity also defines the input
parameter values required by the role-centric task flow.
Example 5034 ProfileTF Reference in Calling Task Flow Configuration File
<task-flow-call id="ProfileTF">
<task-flow-reference>
<document>/WEB-INF/oracle/apps/fnd/applcore/dataSecurity/ui/
taskflow/ProfileTF.xml</document>
<id>ProfileTF</id>
</task-flow-reference>
<input-parameter>
<name>roleCategories</name>
<value>#{pageFlowScope.roleCategories}</value>
</input-parameter>
<input-parameter>
<name>actions</name>
<value>#{pageFlowScope.actions}</value>
</input-parameter>
<input-parameter>
<name>disableViewAll</name>
<value>#{pageFlowScope.disableViewAll}</value>
</input-parameter>
<input-parameter>
<name>disableUpdateAll</name>
<value>#{pageFlowScope.disableUpdateAll}</value>
</input-parameter>
</task-flow-call>
The following example shows task flow call activity definition with a reference to the
role management data security task flow. The task flow call activity also defines the
input parameter values required by the role management task flow.
Example 5035 RoleManagementTF Reference in Calling Task Flow Configuration File
<task-flow-call id="RoleManagementTF">
<task-flow-reference>
<document>/WEB-INF/oracle/apps/fnd/applcore/dataSecurity/ui/
taskflow/RoleManagementTF.xml</document>
<id>RoleManagementTF</id>
</task-flow-reference>
<input-parameter>
<name>roleCategories</name>
<value>#{pageFlowScope.roleCategories}</value>
</input-parameter>
<input-parameter>
<name>title</name>
<value>#{pageFlowScope.title}</value>
</input-parameter>
</task-flow-call>
In the ADF Task Flow page of the Component Palette, drag a Task Flow Call
activity and drop it on the calling task flow.
3.
In the ADF Task Flow page of the Component Palette, select Control Flow Case
and create the control flow case between the source activity (in your calling task
flow) and the call activity.
4.
In the task flow diagram, enter the outcome value for the control flow case.
The value of the outcome must match the return value of the task flow
initialization method you create in the managed bean. For details about the
managed bean, see Section 50.8.2.2, "Initializing the Data Security Task Flow Using
a Managed Bean."
5.
In the Application Navigator, drag the desired data security task flow and drop it
on top of the task flow call activity that is located on the calling task flow.
This action references the data security task flow as the called task flow in the
<task-flow-call> definition. JDeveloper adds the task flow reference to the
calling task flow's configuration file.
6.
In the editor for the calling task flow, click the Source tab to view the new task
flow reference.
7.
In the source for the calling task flow, locate the <task-flow-call> element and
create the input parameter definitions by copying and pasting from the sample
code:
If you dropped the object-centric task flow (the activity references task flow
<id>ObjectLevelTF</id>), add the input parameter values from
Example 5033.
If you dropped the role-centric task flow (the activity references task flow
<id>ProfileTF</id>), add the input parameter values from Example 5034.
If you dropped the role management task flow (the activity references task
flow <id>RoleManagementTF</id>), add the input parameter values from
Example 5035.
Instead of copying and pasting the input parameter values from the samples, you
can also use the Property Inspector to define each input parameter value.
However, it is important that the input parameter values you create match the
parameter names specified by the called task flow. Copying from the samples
ensures the names match exactly.
50.8.2.2 Initializing the Data Security Task Flow Using a Managed Bean
Managed beans are Java classes that you register with the application in your calling
task flow's configuration file. You will create a method on a managed bean to:
Return a value that matches the outcome of the calling task flow.
When your application runs, and the end user clicks the button in the calling web
page, the method is invoked and the properties are declared, allowing the called data
security task flow input parameters to be populated with the declared values.
The following example shows the additional source code that your managed bean
must include to initialize the object-centric (ObjectLevelTF) task flow.
Example 5036 Source for Populating the ObjectLevelTF Input Parameters
//Source for managed bean method to populate and pass ObjectLevelTF parameters
String objectName = "TEST_DS_EMP";
List actions = new ArrayList<ActionMap>();
//for action1
List<String> instanceSets1 = new ArrayList<String>();
instanceSets1.add("TEST_EMP_IS1");
instanceSets1.add("TEST_EMP_IS2");
instanceSets1.add("TEST_EMP_IS3");
ActionMap action1 = ActionMap.getActionMapForObjectUI("View", "VIEW_M",
"ViewPermSet", false, instanceSets1);
actions.add(action1);
//for action 2
List<String> instanceSets2 = new ArrayList<String>();
instanceSets2.add("TEST_EMP_IS2");
instanceSets2.add("TEST_EMP_IS3");
instanceSets2.add("TEST_EMP_IS4");
ActionMap action2 = ActionMap.getActionMapForObjectUI("Update", "UPDATE_M",
"UpdatePermSet", false, instanceSets2);
actions.add(action2);
//populate role categories
List roleCategories = new ArrayList<String>();
roleCategories.add("Category1");
roleCategories.add("Category2");
roleCategories.add("Category3");
//set the paramters in pageflow scope
AdfFacesContext context = AdfFacesContext.getCurrentInstance();
Map pageFlowScope = context.getPageFlowScope();
pageFlowScope.put("objectName", objectName);
pageFlowScope.put("roleCategories",roleCategories);
pageFlowScope.put("actions", actions);
pageFlowScope.put("disableViewAll", false);
pageFlowScope.put("disableUpdateAll", false);
The following example shows the additional source code that your managed bean
must include to initialize the role-centric (ProfileTF) task flow.
Example 5037 Source for Populating the ProfileTF Input Parameters
//Source for managed bean method to populate and pass ProfileTF parameters
List roleCategories = new ArrayList<String>();
roleCategories.add("Category1");
roleCategories.add("Category2");
List actions = new ArrayList<ActionMap>();
//for action1
List<ProfileActionObject> profileObjects1 = new ArrayList<ProfileActionObject>();
profileObjects1.add(ProfileActionObject.getProfileActionObject("View",
"TEST_DS_EMP", "VIEW_EMP_M","ViewEmpPermSet"));
profileObjects1.add(ProfileActionObject.getProfileActionObject("View",
"TEST_DS_EMP1", "VIEW_EMP1_M","ViewEmp1PermSet"));
profileObjects1.add(ProfileActionObject.getProfileActionObject("View",
"TEST_DS_EMP2", "VIEW_EMP2_M","ViewEmp2PermSet"));
ActionMap action1 = ActionMap.getActionMapForProfileUI("View", profileObjects1);
actions.add(action1);
//for action 2
List<ProfileActionObject> profileObjects2 = new ArrayList<ProfileActionObject>();
profileObjects2.add(ProfileActionObject.getProfileActionObject("Update",
"TEST_DS_EMP1", "UPDATE_EMP1_M","UpdateEmp1PermSet"));
profileObjects2.add(ProfileActionObject.getProfileActionObject("Update",
"TEST_DS_EMP2", "UPDATE_EMP2_M","UpdateEmp2PermSet"));
ActionMap action2 = ActionMap.getActionMapForProfileUI("Update",profileObjects2);
actions.add(action2);
The following example shows the additional source code that your managed bean
must include to initialize the role management (RoleManagementTF) task flow.
Example 5038 Source for Populating the RoleManagementTF Input Parameters
//Source for managed bean method to populate & pass RoleManagementTF parameters
AdfFacesContext context = AdfFacesContext.getCurrentInstance();
Map pageFlowScope = context.getPageFlowScope();
pageFlowScope.clear();
List roleCategories = new ArrayList<String>();
roleCategories.add("Category1");
roleCategories.add("Category2");
roleCategories.add("Category3");
pageFlowScope.put("roleCategories", roleCategories);
pageFlowScope.put("title", "Role Management");
In the class editor, create a method that you want to use to initialize the task flow
input parameters.
For example, you might create a method for the RoleManagementTF task flow,
initializeRoleManagement().
3.
If you want to initialize the object-centric task flow, add the input parameter
property declarations from Example 5036.
If you want to initialize the role-centric task flow (also called the Profile task
flow), add the input parameter property declarations from Example 5037.
If you want to initialize the role management task flow, add the input
parameter property declarations from Example 5038.
Copying from the samples ensures the input parameters names match those
defined by the data security task flow.
4.
In the source you pasted, edit the input parameter property definitions to specify
the default values for your application.
5.
Enter a return value for the initialization method that matches the outcome of the
control flow case you specified in your calling task flow.
For example, for the outcome value "start", your method should show:
return "start";
For details about creating the control flow case in your application's task flow, see
Section 50.8.2.1, "Creating a Task Flow Call Activity in Your Application's Task
Flow."
50.8.2.3 Registering the Managed Bean with Your Application's Task Flow
To declare the manage bean in the calling task flow's configuration file, you must enter
a bean identifier name, the class path for the bean, and you must specify backing bean
scope. The following example uses the bean identifier roleManageBean to match the
Action attribute definition specified on the button component shown in
Example 5039.
Example 5040 Managed Bean Declaration in Calling Task Flow Configuration File
<adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2">
<task-flow-definition id="MyCallingTaskFlow">
<default-activity id="__1">CallRoleManageTF</default-activity>
<managed-bean id="__4">
<managed-bean-name id="__5">roleManageBean</managed-bean-name>
<managed-bean-class id="__2">
oracle.apps.fnd.applcore.dataSecurity.view.RoleManage</managed-bean-class>
<managed-bean-scope id="__3">backingBean</managed-bean-scope>
</managed-bean>
</task-flow-definition>
...
</adfc-config>
In the editor for the task flow, click the Source tab.
3.
In the source for the calling task flow, declare the managed bean by creating the
<managed-bean> element similar to the sample shown in the previous example.
50.8.3 How to Configure the Object Instance Task Flow to Display in a Dialog
When you integrate a data security task flow as a dialog, your application's task flow
invokes the task flow using an executable in the ADF Model layer. This executable is
50-42 Developer's Guide
defined by JDeveloper when you drop the data security task flow as region onto a
dialog component that you add to your application's calling web page. The web page
the defines the region is associated with a view activity in your application task flow;
no task flow control flow case is needed to invoke the data security task flow.
A popup button in the calling web page defines a listener that invokes a method on
the managed bean to initialize the task flow's input parameters. The button then
displays the dialog with a region that invokes the task flow using the executable
defined on the calling page's definition. When the user clicks the dialog close button, a
listener (for the dialog's close button) saves the end user's sections from data security
UI.
To integrate the object instance task flow (ObjectInstTF) with your application so it
appears in a dialog (as a secondary browser window):
1.
In your application's task flow, double-click the view activity associated with the
web page that end users will use to open the dialog.
2.
3.
Drop an ADF popup component onto the button and configure a popup fetch
listener to invoke an initialization method on a managed bean.
4.
Drop an ADF dialog inside the popup component and configure a dialog listener
to invoke a method to save grants made by the user.
5.
Drop the object instance task flow as a region onto the dialog component.
6.
Edit the page definition file for the calling page to specify the data security task
flow's input parameter values on the task flow executable.
7.
Create a managed bean and define a method to initialize the task flow parameters
before the dialog displays.
8.
Define another method on the managed bean to trigger the task flow save action
and save the grants into the database.
9.
Register the managed bean in your application's task flow configuration file.
50.8.3.1 Creating the Task Flow Executable in the Region Page Definition FIle
When you drop a data security task flow onto a web page to create an ADF region,
JDeveloper adds an af:region tag to the page. The af:region tag references an object
that implements RegionModel, as shown in Example 5042.
JDeveloper also adds a task flow binding to the <executables> element of the page
definition file for the page that defines the ADF region. The task flow binding provides
a bridge between the ADF region and the data security task flow. It binds a specific
instance of an ADF region to the data security task flow and maintains all information
specific to the task flow. The taskFlowId attribute specifies the directory path and the
name of the source file for the bounded task flow.
To pass parameters into the data security task flow, you must specify input parameter
values on the task flow binding. These values must correspond to the input parameter
definitions on the called data security task flow.
The following example shows task flow binding in the page definition file with a
reference to the object-instance data security task flow. The task flow binding also
defines the input parameter values required by the object-instance task flow.
Example 5041 ObjectInstTF Call Entry in Page Definition File
<taskFlow id="ObjectInstTF1"
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/dataSecurity/ui/
taskflow/ObjectInstTF.xml#ObjectInstTF"
Refresh="ifNeeded"
xmlns="http://xmlns.oracle.com/adf/controller/binding">
<parameters>
<parameter id="objectName" value="#{pageFlowScope.objectName}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="actions" value="#{pageFlowScope.actions}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="instancePK1" value="#{pageFlowScope.instancePK1}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="instancePK2" value="#{pageFlowScope.instancePK2}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="instancePK3" value="#{pageFlowScope.instancePK3}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="instancePK4" value="#{pageFlowScope.instancePK4}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="instancePK5" value="#{pageFlowScope.instancePK5}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="taskflowId" value="#{pageFlowScope.taskflowId}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
<parameter id="parameterMap" value="#{pageFlowScope.parameterMap}"
xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
</parameters>
</taskFlow>
childCreation="deferred">
<af:dialog id="polDiag" modal="true" title="Object Instance UI"
affirmativeTextAndAccessKey="Save and Close" resize="on"
contentWidth="600" contentHeight="330"
stretchChildren="first"
dialogListener="#{backingBeanScope.objectInstanceBean.okCreatePolicy}">
<af:region value="#{bindings.ObjectInstTF1.regionModel}" id="r1"/>
</af:dialog>
</af:popup>
</af:panelGroupLayout>
</af:panelHeader>
In the ADF Task Flow page of the Component Palette, drag a View activity and
drop it on the calling task flow.
3.
In the ADF Task Flow page of the Component Palette, select Control Flow Case
and create the control flow case between the source activity (in your calling task
flow) and the view activity.
4.
5.
In the Application Navigator, drag the object instance task flow and drop it on top
of the task flow call activity that is located on the calling task flow.
This action defines the data security task flow as the called task flow using a
<task-flow-call> definition. The task flow call definition appears in the calling
task flow configuration file.
6.
In the editor for the task flow, click the Source tab to view the new task flow
reference.
7.
In the source for the calling task flow, locate the <task-flow-call> element and
create the input parameter definitions by copying and pasting from the sample
code:
If you dropped the object-centric task flow (activity will show task flow
reference <id>ObjectLevelTF</id>), add the input parameter values from
Example 5033.
If you dropped the role-centric task flow (activity will show task flow
reference <id>ProfileTK</id>), add the input parameter values from
Example 5034.
If you dropped the role management task flow (activity will show task flow
reference <id>RoleManagementTF</id>), add the input parameter values from
Example 5035.
Instead of copying and pasting the input parameter definitions from the samples,
you could also use the Property Inspector to define each input parameter.
However, it is important that the input parameter definitions you create match the
parameter names specified by the called task flow. Copying from the samples
ensures the names match exactly.
A popup fetch listener method to add properties to the managed bean that will
initialize the input parameters of the data security task flows.
A dialog listener method to save the grants made by the end user to the database
when the user closes the dialog.
When your application runs, and the end user clicks the button in the calling web
page, the popup fetch listener method is invoked and the properties are declared,
allowing the called data security task flow input parameters to be populated with the
declared values.
The following example shows additional source code that your managed bean must
include to initialize the object-instance (ObjectInstlTF) task flow.
Example 5043 Source for Populating the ObjectInstTF Input Parameters
//Source for manaaged bean to populate and pass ObjectInstTF parameters
public void launchPolicy(PopupFetchEvent popupFetchEvent)
{
List actions = new ArrayList<ActionMap>();
ActionMap action1 = ActionMap.getActionMapForInstanceUI("View", "VIEW_EMP_M");
actions.add(action1);
ActionMap action2 = ActionMap.getActionMapForInstanceUI("Update",
"UPDATE_EMP_M");
actions.add(action2);
ActionMap action3 = ActionMap.getActionMapForInstanceUI("Create",
"CREATE_EMP_M");
actions.add(action3);
ActionMap action4 =
ActionMap.getActionMapForInstanceUI("Delete", "DELETE_EMP_M");
actions.add(action4);
ActionMap action5 =
ActionMap.getActionMapForInstanceUI("CustomFSOnlyAction",
"CUSTOMFSONLYACTION_EMP_M");
actions.add(action5);
AdfFacesContext context = AdfFacesContext.getCurrentInstance();
Map pageFlowScope = context.getPageFlowScope();
pageFlowScope.clear();
pageFlowScope.put("actions", actions);
pageFlowScope.put("objectName", "TEST_DS_EMP");
pageFlowScope.put("instancePK1",
pageFlowScope.put("instancePK2",
pageFlowScope.put("instancePK3",
pageFlowScope.put("instancePK4",
pageFlowScope.put("instancePK5",
"2");
null);
null);
null);
null);
// If you want to use a customized task flow instead of people picker to select
// users, you need specify values for the taskflowId and parameterMap.
// Map<String, Object> paraMap = new HashMap<String, Object>();
// paraMap.put("pageTitle", "Custom User Selection");
// pageFlowScope.put("parameterMap", paraMap);
//Taskflow name
// pageFlowScope.put("taskflowId", "/WEB-INF/CustomDSUserTF.xml#CustomDSUserTF");
}
The following example shows the source code you must add for the method your
dialog listener invokes. In this case, the method is named okCreatePolicy() to match
the method invoked by the dialog listener in Example 5042.
Example 5044 Source for Saving the ObjectInstTF Grants
//Source for managed bean to save end user grant
public void okCreatePolicy(DialogEvent dialogEvent)
{
DataSecurityUIUtils.saveInstanceGrants(dialogEvent);
//Add your custom code if needed
}
In the class editor, create a method that you want the popup listener to invoke to
initialize the task flow input parameters.
For example, you might create a method launchPolicy() named for the method
invoked by the popup listener (shown in Example 5042).
3.
4.
In the source you pasted, edit the input parameter property definitions to specify
the default values for your application.
5.
In the class editor, create a method that you want the dialog listener to invoke to
save the grants after the user closes the dialog.
For example, you might create a method okCreatePolicies() named for the
method invoked by the dialog listener (shown in Example 5042).
6.
In the method definition, create the save operation by copying and pasting from
Example 5044 into the new save grants method definition.
Copying from the sample ensures the method saveInstanceGrants() is called
exactly as shown.
50.8.3.3 Registering the Managed Bean with Your Application's Task Flow
To declare the manage bean in the calling task flow's configuration file, you must enter
a bean identifier name, the class path for the bean, and you must specify backing bean
scope. The following example uses the bean identifier objectInstanceBean to match
the bean references specified in the listener properties shown in Example 5042.
Example 5045 Managed Bean Definition in Calling Task Flow Configuration File
<adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2">
<task-flow-definition id="MyCallingTaskFlow">
<default-activity id="__1">CallObjectInstTF</default-activity>
<managed-bean id="__4">
<managed-bean-name id="__5">objectInstanceBean</managed-bean-name>
<managed-bean-class id="__2">
oracle.apps.fnd.applcore.dataSecurity.view.DSObjectInstance</managed-bean-class>
<managed-bean-scope id="__3">backingBean</managed-bean-scope>
</managed-bean>
</task-flow-definition>
...
</adfc-config>
In the editor for the task flow, click the Source tab.
3.
In the source for the calling task flow, declare the managed bean by creating the
<managed-bean> element similar to the sample shown in the previous example.
50.8.4 How to Grant the End User Access to the Data Security Task Flows
The data security task flows, when integrated into your application, behave like other
web application resources secured by ADF Security. By default, ADF Security locks
down application resources and therefore requires that you grant access rights to the
members of the application roles for the task flows.
To grant view access to the task flows, you define a OPSS permission grant defined by
the oracle.adf.controller.security.TaskFlowPermission class. The following
example shows the permission definition that grants the users (identified by
<grantee> in your application) view access rights to the task flows.
Note that the resources in the permission grant are identified by regular expression
metacharacters .* (dot followed by an asterisk). This expression denote any number of
arbitrary characters and effectively grants view rights on all task flows in the Oracle
Fusion Applications data security path
/WEB-INF/oracle/apps/fnd/applcore/dataSecurity/ui/taskflow/.
Example 5046 Grant to View Data Security Task Flows
<grant>
<grantee>
...
</grantee>
<permissions>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/WEB-INF/oracle/apps/fnd/applcore/dataSecurity/ui/taskflow/.*</name>
<actions>view</actions>
</permission>
</permissions>
</grant>
The grantee of the permission are the application roles that your application specifies.
If you are using custom application roles not defined by Oracle Fusion Applications, a
security manager will need to configure these application roles using Authorization
Policy Manager. For example, an application role requires a role category definition.
In the source for the jazn-data.xml file, add the permission definition shown in
the previous example to the policy store and define the grantee.
Grantee are typically application roles that your application defines. A grant is
always made to a single grantee. When you need to grant view permission to more
than one grantee, create duplicate grants and name the grantee in each.
3.
50.8.5 How to Grant the Application Access to the Application Policy Store
A grant must be added to the jazn-data.xml policy store to allow your application to
provision the LDAP policy store. The LDAP policy store is secured so that only
authorized applications can make API calls needed to create and update grants in the
store. For this purpose, a code source grant must be made to authorize the
implementation code of the data security task flows to make credential store and
policy store API calls. The following example shows the code source grant where
<application-name> is the application name specified in the jazn-data.xml policy
store.
Example 5047 Grant to Enable Policy Store Provisioning by Data Security Task Flow Source Code
<grant>
<grantee>
<codesource>
<url>file:${domain.home}/servers/${weblogic.Name}/tmp/_WL_user/<application-name>/-</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.security.jps.service.policystore.PolicyStoreAccessPermission</class>
<name>context=APPLICATION,name=<application-name></name>
<actions>getApplicationPolicy,grant,revoke,alterAppRole,createAppRole,
alterAppRoleCategory</actions>
</permission>
</permissions>
</grant>
To enable the application to access and update the domain policy store:
1. In JDeveloper, open the jazn-data.xml file in the overview editor.
2.
In the source for the jazn-data.xml file, add the code source grant shown in the
previous example to the policy store and enter the name of your application in the
<url> and <name> definitions.
The application name you enter must match the application name identified in the
policy store definition.
3.
In the source for the web.xml file, add the web application initialization parameter
shown in the previous example beneath the JPS filter.
The application name you enter must match the application name identified in the
policy store definition.
3.
51
Implementing Function Security
51
Access the web pages of a custom ADF task flow that supports the duty
Note:
Function security controls access to securable application artifacts including ADF task
flows and top-level web pages backed by ADF page definition files. Users who do not
have the required privilege cannot view the task flow. For example, in a sales
organization, duties such as Manage_Accounts and Manage_Invoices exist for roles,
such as Sales_Manager or Sales_Associate. A function security policy might give end
users who belong to the Sales_Manager role the ability to view and edit customer
invoices. Whereas, end users who do not belong to the Sales_Manager role, may not
enter the task flow.
As an security implementation guideline, you should only use Oracle JDeveloper tools
to work on the exported file-based policy store, and you should not edit the security
definitions directly. JDeveloper supports iterative development of security so you can
easily create, test, and edit security policies that you create for Oracle ADF application
artifacts.
After you customize security, you use JDeveloper to add end user identities to the
identity store of the exported file before running and testing the application in
JDeveloper's Integrated WebLogic Server. You provision a few test end user identities
by defining user groups and then assign those groups to application roles to simulate
how the actual end users of the enterprise will access the secured application artifacts.
When you deploy the application in your development environment, JDeveloper
migrates the identity store you created to the embedded LDAP of Integrated WebLogic
Server. The application policy store is migrated to a system-jazn-data.xml file that
aggregates the security policies definitions of all applications in your workspace.
After testing in JDeveloper, you must consult with the security administrator to merge
the LDAP-based application policy store in the staging environment with the security
policies that you added to the exported jazn-data.xml file. The staging environment
is an LDAP-based Oracle WebLogic Server configured to use Oracle Internet Directory
(OID) for the enterprise's application policy store and identity store (note that the
stores of the staging server are LDAP-based and not file-based). Initially, the staging
environment allows further testing using that server's identity store before deploying
to the production environment. Thus, end user identities created in JDeveloper are not
migrated to standalone Oracle WebLogic Server and are used only in Integrated
WebLogic Server to test the extended application.
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework
Describes ADF Security, through which ADF components interact with OPSS.
The following table summarizes the function security scenarios that Oracle Fusion
security supports. The "Application Developer Tasks" column of the table provides a
brief description of the security artifacts involved in each scenario.
Table 511
Security Goal
File Name
Location
Security Purpose
jazn-data.xml
<JDevAppHome>/src/META-INF
adf-config.xml
<JDevAppHome>/.adf/META-INF
weblogic-application.xml <JDevAppHome>/src/META-INF
jps-config.xml
<JDevAppHome>/src/META-INF
Location
Security Purpose
web.xml
<JDevAppHome>/UserInterface/
public-html/WEB-INF
weblogic.xml
<JDevAppHome>/UserInterface/
public-html/WEB-INF
cwallet.sso
<JDevAppHome>/src/META-INF
Decide the names of custom application roles that your application will specify as
the grantee of security privileges.
Optionally, ask the security administrator to create custom application roles with
the names you supply.
If a security manager creates the application roles you identify, then those custom
application roles will already appear in the policy store section of the exported
jazn-data.xml file. For details about how the security administrator creates
application roles using Oracle Authorization Policy Manager, see the
product-specific security guides.
If you do not ask the security manager to create custom application roles, then you
must create them in JDeveloper before you define security policies.
3.
4.
5.
Determine which ADF artifacts should be secured and grant entitlement privileges
to custom application roles to specify the access rights of end users.
Although ADF Security permits you to define function security policies for ADF
artifacts using only resource privilege grants, an Oracle Fusion security best
practice is to define access policies using entitlement grants except for publicly
accessible application artifacts.
For details about securing application functions, see Section 51.3.1, "How to Create
Entitlement Grants for Custom Application Roles."
6.
Determine which ADF artifacts should be public and grant resource privileges to
an appropriate OPSS built-in application role.
For details about making application functions public, see Section 51.3.3, "How to
Define Resource Grants for OPSS Built-In Roles."
7.
Opt into the previously defined function security policies by running the
Configure ADF Security wizard to enforce OPSS authorization checking.
For details about enabling security on the user interface project, see Section 51.3.5,
"How to Enforce Authorization for Securable ADF Artifacts."
8.
Determine which user interface components you want to associate with user
entitlements, and enter EL utility methods on the component to make it logically
consistent with its target.
ADF does not enforce security on user interface components, such as buttons or
links that navigate to securable artifacts (pages and task flows). For details about
using EL utility methods, see the "Enabling ADF Security in a Fusion Web
Application" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
9.
Define test user identities and run the application in JDeveloper to simulate the
privileges of the enterprise users who will eventually interact with the application.
For details about adding test user in JDeveloper, see Section 51.3.6, "How to Enable
Authentication and Test the Application in JDeveloper."
10. After testing is complete, remove the test users from the jazn-data.xml file and
provide the updated jazn-data.xml file to the security administrator to merge the
file-based policy store with the application policy store in the staging
environment.
JDeveloper must not be used as an identity store provisioning tool, and you must
be careful not to deploy the application with user identities that you create for
testing purposes. Deploying user identities with the application introduces the risk
that malicious users may gain unintended access.
For information about how the security administrator merges the policies using
Oracle Authorization Policy Manager, see the "Upgrading Fusion Application
Policies" section in the Oracle Fusion Applications Administrator's Guide.
11. The security administrator provisions enterprise users by mapping enterprise
roles defined in the staging environment identity store to the custom application
roles.
For information about how the security administrator provisions enterprise users
using Oracle Authorization Policy Manager, see the product-specific security
guides.
12. Before running the application in the staging environment, the security
administrator must reconcile the application roles GUIDs of any data security
policies that were created based on new custom application roles.
When the file-based policy store is merged, the GUIDs of application roles are not
preserved. For information about how the security administrator reconciles GUIDs
using a WLST command, see the "Reconciling GUIDs" section in the Oracle Fusion
Applications Administrator's Guide.
13. Continue testing the application in the staging environment before deploying the
Best Practice:
To simplify the task of securing the functions of your application, ADF provides the
ADF Security framework. ADF Security defines a containment hierarchy that lets you
define a single security policy for the ADF bounded task flow and its contains web
pages. In other words, the security policy defined at the level of the bounded task flow,
secures the flow's entry point and then all pages within that flow are secured by the
same policy. For example, a series of web pages may guide new end users through a
registration process and the bounded task flow controls page navigation for the
process.
Specifically, the ADF artifacts that you may secure are:
ADF bounded task flow protects the entry point to the task flow, which in turn
controls the end user's access to the pages contained by the flow
The ADF unbounded task flow is not a securable application artifact and thus
does not participate in OPSS authorization checks. When you need to secure the
constituent pages of an unbounded task flow, you define policies for the page
definition files associated with the pages instead.
ADF page definition files associated with top-level web pages and regions
For example, a page may display a summary of products with data coordinated by
the ADF bindings of the page's associated ADF page definition file.
Do not create entitlement grants for the individual
web pages of an ADF bounded task flow. When the end user accesses
the bounded task flow, security for all pages will be managed by the
entitlements you create for the task flow. This supports a well-defined
security model for task flows that enforces a single entry point for all
end users. For additional best practice information about ADF and
function security, see Section 51.3.9, "What You May Need to Know
About Security Best Practices."
Best Practice:
Determine which ADF artifacts should be secured and grant entitlement privileges
to custom application roles to define the duties of end users.
2.
Determine which ADF artifacts should be public and grant resource privileges to
an appropriate OPSS built-in application role.
3.
Opt into the previously defined function security policies by running the
Configure ADF Security wizard to enforce OPSS authorization checking.
4.
Determine which user interface components you want to associate with user
entitlements, and enter EL utility methods on the component to make it logically
consistent with its target.
ADF does not enforce security on user interface components, such as buttons or
links that navigate to securable artifacts (pages and task flows). For details about
using EL utility methods, see the "Enabling ADF Security in a Fusion Web
Application" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
Implementing Function Security 51-9
5.
Define test user identities and run the application in JDeveloper to simulate the
privileges of the enterprise users who will eventually interact with the application.
Resource Type
ADF Region
ADF Entity
Permission
ADF Method
Resource
Webservice
Resource
Defines invoke actions on Fusion Web services. For more details about
securing Web services, see Section 52.5, "Authorizing the Web Service
with Entitlement Grants."
To define an entitlement grant for a securable ADF artifact, use the Entitlement Grants
page of the overview editor for the jazn-data.xml file. This editor is also called the
security policy overview editor.
Before you begin:
It may be helpful to have an understanding of ADF Security. For more information, see
the "Understanding Users and Roles" chapter of the Oracle Fusion Middleware
Application Security Guide.
It may also be helpful to understand the details of the ADF Security containment
model. For more information, see Section 51.3.9, "What You May Need to Know About
Security Best Practices."
You will need to complete these tasks:
Consult the security administrator for the enterprise to obtain the jazn-data.xml
file that contains the predefined function security policies for your application.
You must add the file to your application workspace, as explained in Section 51.2,
"Function Security Implementation Process Overview."
Create application roles as described in the "Enabling ADF Security in a Fusion
Web Application" chapter of the Oracle Fusion Middleware Fusion Developer's Guide
for Oracle Application Development Framework.
1.
2.
In the Entitlement Grants page of security policy overview editor, click the Add
Entitlements icon in the Entitlements list.
The overview editor displays all the resources that your application defines.
3.
In the Resources section, click the Add Member Resource icon to add a member
resource to the entitlement.
4.
In the Select Resources dialog, select the resource from the Resource Type
dropdown and then select the desired project in the Source Projects list.
The dialog displays all the projects in your application workspace.
5.
In the Available Resources list, select the resource from and click the Add icon.
The dialog displays all the resources define by your selected project.
6.
In the Actions lists, select the desired action for the selected resource.
The following figure shows the overview editor with the View action selected for
the task flow and added to MyEntitlement.
51-11
7.
8.
In the Grants section of the security policy overview editor, click the Add Role
Grants icon to grant the entitlement to an application role.
9.
In the Select Application Roles dialog, select one or more custom application roles.
The dialog displays all the application roles from the jazn-data.xml file. You must
not add a grant to a predefined application role (also called duty roles in the
terminology of Oracle Fusion Applications). Only select custom application roles
that either you created in JDeveloper or that were created by a security
administrator for this purpose.
resources to the same entitlement for the same custom application role.
51-13
</permission-set-refs>
</grant>
</jazn-policy>
</application>
</applications>
</policy-store>
</jazn-data>
Consult the security administrator for the enterprise to obtain the jazn-data.xml
file that contains the predefined function security policies for your application.
You must add the file to your application workspace, as explained in Section 51.2,
"Function Security Implementation Process Overview."
In the Resource Grants page of security policy overview editor, select the resource
from the Resource Type dropdown and then select the desired project in the
Source Projects list.
The overview editor displays all the projects in your application workspace.
3.
In the Resources column, select the ADF artifact for which you want to grant
access rights.
Tip: Click the lock icon to show only those resources that do not yet have grants.
4.
In the Granted to column, click the Add Grantee icon and choose Add
Application Role.
5.
In the Select Application Roles dialog, select one of these built-in application roles:
6.
7.
In the Resource Grants page of the overview editor, in the Actions column, select
the desired action.
The following figure shows the overview editor with the View action selected for
the task flow and granted to authenticated-role.
51-15
Example 512
<policy-store>
...
<jazn-policy>
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.internal.core.
principals.JpsAuthenticatedRoleImpl</class>
<name>authenticated-role</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/WEB-INF/customer-registration-task-flow.xml#
customer-registration-task-flow</name>
<actions>view</actions>
</permission>
...
</permissions>
...
</grant>
...
</jazn-policy>
</policy-store>
When you run the wizard, you are effectively enforcing authorization checking for all
securable ADF artifacts. The wizard also enables the ADF authentication servlet to
require the end user to log in the first time a page in the application is accessed.
This configuration requires a valid user to access the pages of your application. This
assumes that you will define custom application roles and assign explicit grants to
those roles to manage access to securable ADF artifacts, as described in Section 51.3.1,
"How to Create Entitlement Grants for Custom Application Roles." Alternatively,
when you want to make a page pubic and accessible by unauthenticated user, you
must explicitly grant to a built-in OPSS role, as described in Section 51.3.3, "How to
Define Resource Grants for OPSS Built-In Roles."
Before you begin:
It may be helpful to have an understanding of the configuration changes made by the
Configure ADF Security wizard. For more information, see the "Enabling ADF
Security in a Fusion Web Application" chapter of the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
To enforce authorization:
1. In the main menu, choose Application and then Secure > Configure ADF
Security.
2.
51-17
For details about creating test users, see the "Enabling ADF Security in a Fusion Web
Application" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
Note that if you enabled the option to grant to a test role when you run the Configure
ADF Security wizard, your grants may be of the following two types:
For the task flows that you create before running the Configure ADF Security
wizard, the wizard automatically assigns them to the test-all role. You will need
to remove these grants and create valid grants to your custom application roles.
For each entitlement granted to a specific role, the equivalent grant to the
test-all role must be removed.
The new task flows you create after running the Configure ADF Security wizard
are not granted to the test-all role automatically. You need to manually grant the
entitlements for the new task flows to your custom application roles.
51.3.7 What You May Need to Know About Actions That Developers Must Not Perform
Security definitions that are predefined in the Oracle Fusion security reference
implementation must not be changed by developers. When modifying the file-based
policy store, always create custom application roles and define new entitlement grants.
Specifically, developers must not make the following changes to the predefined
security definitions of the Oracle Fusion security reference implementation.
For more information about the Oracle Fusion security reference implementation, see
the product-specific security guides.
3.
If you want the policies to persist on the staging server after the application is
undeployed, then set the jps.policystore.removal flag in the
weblogic-application.xml file.
4.
Note that the jps-config.xml file in the application does not need to be modified.
When the application is deployed, the staging server will have its own instance of
the jps-config.xml file which is configured through a WLST command (the
reassociateSecurityStore command). Therefore, the application
jps-config.xml file can remain unchanged.
51-19
As a security best practice, you should not migrate users and groups that you create in
JDeveloper. If the Users and Groups checkbox is selected, test users and groups in
jazn-data.xml will be merged into the target server with different GUIDs than those
used to grant data security privileges.
JDeveloper must not be used as an identity store provisioning
tool, and you must be careful not to deploy the application with user
identities that you create for testing purposes. Deploying user
identities with the application introduces the risk that malicious users
may gain unintended access. Instead, rely on the system administrator
to configure user identities through the tools provided by the
domain-level identity management system.
Note:
Before testing the application in the staging environment, any custom application roles
that you created will need to be created in the LDAP application policy store. These
new application roles will receive new GUIDs and any data security policies defined
for application roles of the same name must have their GUIDs reconciled. For details
about reconciling GUIDs in the data security repository, see the "Reconciling GUIDs"
section in the Oracle Fusion Applications Administrator's Guide.
51.3.9 What You May Need to Know About Security Best Practices
ADF implements a particular security model. Follow these rules to address problems
you encounter when adding security to the application:
Bounded task flows are secured by default. Secured by default means OPSS will
check authorization on all bounded task flows when ADF Security has been
enabled.
Pages and page fragments backed by an ADF page definition file are also secured
by default when not embedded in a bounded task flow. Keep in mind that OPSS
will not check authorization for pages or page fragments that do not have a
corresponding ADF page definition file.
Pages and page fragments embedded in bounded task flows will not be checked
by OPSS for authorization. Instead, they are granted or denied as a unit depending
on the entitlement granted to the bounded task flow. That means those pages and
page fragments do not need to be explicitly granted in the policy store.
Bounded task flows embedded in bounded task flows will by checked by OPSS for
authorization.
ADF does not enforce security on user interface components, such as buttons or
links) that navigate to securable artifacts (pages and task flows). An explicit EL
expression must be attached to the component to make it logically consistent with
its target.
The test-all role is just a means of not breaking the application when ADF
Security is enabled. Therefore, it should never be deployed, since it grants access
to the application for non-authenticated users.
51-21
52
Securing Web Services Use Cases
52
This chapter describes the best practices for securing Web services in an Oracle Fusion
application using an Oracle Web Services Manager (Oracle WSM) feature called global
policy attachments (GPA).
This chapter contains the following sections:
3.
4.
5.
The BPEL process interacts with ADF Business Components Web services so as to
execute the business logic of the use case.
While event generation typically begins with ADF Business Components, it is also
possible to generate events from another SOA composite, Java PL/SQL code, or Java
code and either directly or indirectly invoke the ADF Business Components Web
service. However, when the event is triggered from the user interface and ADF
Business Components, the ADF Business Components Web service can be invoked
synchronously using the ServiceFactory interface (using either RMI or SOAP).
The following figure illustrates the possible event generation use cases for Oracle
Fusion applications. The main use case flowADF Business Components-generated
eventsis illustrated in the center, along with numbers (enclosed in circles)
illustrating the corresponding steps of the above use case. Possible alternative flows
are represented by dashed lines and numbers (enclosed in boxes, again corresponding
to the steps of the above use case).
Figure 521 Sample Web Service Use Case
Oracle Fusion applications typically use SOAP services. Use Oracle Web Services
Manager (Oracle WSM) to secure these services. Following are the main
recommendations when using Oracle WSM with Oracle Fusion Applications.
Attach Oracle WSM authentication service policies to Web services and BPEL
process Web service bindings.
Attach Oracle WSM client policies to Web services references in BPEL Partner
links, proxies and ADF Web services data controls.
It is a requirement to enforce authentication on all ADF Business Components Web
services and exposed BPEL processes.
It is a requirement to enforce authorization on all ADF Business Components Web
services.
No authorization is required for SOA components, although it is possible to
implement authorization checks for users and enterprise roles. You can enable
authorization checks in ADF Business Components Web services.
All request and response messages must be protected for integrity and
confidentiality using an XML signature and encryption. Oracle WSM
transparently handles this.
Oracle WSM policies do not apply to events.
Note:
Public Web services (those that do not need any user authentication) should use
LPA to locally attach a "no authentication" policy on both the client side and the
service side.
When a Web service client needs to connect to a service using a particular user
name and password, you need to specify the user name and password using a
configuration override.
But GPA policies do not allow configuration overrides, which means you must use
LPA to attach a username password policy on the client side. Note that even
though configuration overrides require that you implement LPA on the client side,
you still can allow the system administrator to define GPA on the server side for
username password policies. Unlike the client side, the server side need not
specify a particular username and password, instead it will accept any username
and password.
When a Web service requires additional security hardening, because, for example,
they want to use a key that is different from the domain key generated for Oracle
Fusion Applications, then you must use LPA and specify this key using a
configuration override.
The Oracle Fusion Applications provisioning script generates a single keypair
(public key and self signed certificate) with the alias orakey and stores the keypair
in all Oracle Fusion Applications domains. All GPA policies will use this key by
default unless you use LPA and specify a different key.
When a Web service exists that must be invoked outside of an Oracle Fusion
application that external service will be secured with message protection. The
default GPA for Oracle Fusion Applications is no message protection, which is not
sufficient for external services that can be invoked outside Oracle Fusion
applications. For external web services, you must use LPA to use a message
protection policy, for example to secure the external service to make it more secure
or less secure.
When a Fusion Web service can be invoked by an application outside of Oracle
Fusion applications (because an Oracle Fusion application is integrated with the
calling application) that service will most likely need to use policies to provide
additional hardening. In this case, these clients should use LPA.
Fusion Web service clients that need to connect to external non Fusion Web
services will most likely need to use policies that are different from the globally
attached policies. In this case, these clients should also use LPA.
You should use LPA whenever you want to override the globally attached policy. The
user name and specifying an alternate key are common examples of overriding a
globally attached policy.
In summary, use LPA when the Web service is a public service, when the service
requires elevated privileges to connect using a particular user name and password, or
when the service requires additional security hardening.
Before enabling GPA, make sure that you have attached the no_authentication_
service_policy policy to those services that do not need authentication.
4.
5.
Verify that your client and Web services are using GPA.
A system administrator does this using either Oracle Enterprise Manager Fusion
Middleware Control or using WLST.
For details about creating global policy sets, see the "Creating and Managing
Policy Sets" chapter of the Oracle Fusion Middleware Security and Administrator's
Guide for Web Services.
When a Web service should be public (those that do not require user
authentication)
When a Web service client requires elevated privileges to connect using a
particular user name and password
When a Web service requires additional security hardening
When Fusion Web service clients (for example, a JRF client or a SOA client) need
to connect to external non Fusion Web services
The following table shows the recommended Oracle WSM policies and the
components to which they apply.
Table 521
Profile
Recommended Oracle Web Services Manager Policies for Oracle Fusion Applications
Service Side Policy
Authentication wss_saml_or_username_
(AuthN)
token_service_policy
Features
Username:
Performance: High
wss10_saml_token_
client_policy
Security: Low
SAML:
wss10_saml_token_
client_policy
SSL Profile
wss_saml_or_username_
token_over_ssl_
service_policy
Username:
Performance: Medium
wss10_saml_token_
client_policy
Security: Medium
SAML:
wss10_saml_token_
client_policy
- Authentication: passwords
encrypted because of 1-way-SSL,
SAML token is signed by virtue of
2-way-SSL.
- Wire level security: Transport level,
using 1-way-SSL for username, and
2-way-SSL for SAML.
- Hardening: Medium. Each
application server can have its own
separate key.
Configuration: Hard. The same Oracle
HTTP Server URI must be set up for
both 1-way and 2-way-SSL and the
client certificate must be set to
propagate from Oracle HTTP Server to
Oracle WebLogic Server. For details, see
the "Setting Up Your Environment for
Policies" chapter of the Oracle Fusion
Middleware Security and Administrator's
Guide for Web Services.
Interoperatiblity:
- Username: High
- SAML: Medium
Table 521 (Cont.) Recommended Oracle Web Services Manager Policies for Oracle Fusion Applications
Profile
Features
Message
Security
wss11_saml_or_
username_token_with_
message_protection_
service_policy
Username:
Performance: Medium
wss10_saml_token_
client_policy
Security: High
SAML:
wss10_saml_token_
client_policy
No Behavior
oracle/no_
authentication_
service_policy
oracle/no_
authentication_
client_policy
@SecurityPolicy( { "oracle/no_authentication_service_policy"})
@CallbackSecurityPolicy("oracle/no_authentication_service_policy")
For more information about ADF Business Components Web services, see the
"Integrating Service-Enabled Application Modules" chapter of the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
For details about locally attaching the no behavior policy on Oracle WebLogic Server
using Fusion Middleware Control and the WebLogic Scripting Tool (WLST), see the
"Attaching Policies to Web Services" chapter of the Oracle Fusion Middleware Security
and Administrator's Guide for Web Services.
Note:
Oracle Fusion Applications can use either RMI or SOAP to invoke the service. An RMI
invocation of the service does not require security configuration. A SOAP invocation
of the service can support identity propagation or identity switch.
To support identity propagation by the client, use the SAML token policy. To support
identity switch, use the user name policy.
In the case of an ADF Business Components Web service, you can enter service
annotations in the Web service implementation class to specify the locally attached
policy, as shown in the following example.
Example 522
@SecurityPolicy( { "oracle/wss11_saml_or_username_token_with_message_protection_
service_policy"})
@CallbackSecurityPolicy("oracle/wss11_saml_token_with_message_protection_client_
policy")
Note that Fusion Web services should have asynchronous method calls enabled.
52.4.3 How to Provide Additional Security Hardening for Web Service Clients
Typically, Fusion Web services use a common domain wide key, which is necessary
both for encryption and signing. Since this key is global it works very well with GPA.
However, if certain Web services requires additional security hardening, because, for
example, they want to use a key that is different from the domain key, then those
services would need to use LPA and specify this key using a configuration override.
Another use case that would require LPA to provide additional security hardening
exists when a non-Oracle Fusion application invokes an Oracle Fusion application
Web service. In this case, because Fusion Web services do not use message protection
by default, additional protection will be required to comply with the invoking
application security policies.
For details about locally attaching Web service client policy and configuring override
properties on Oracle WebLogic Server, see the "Attaching Policies to Web Services"
chapter of the Oracle Fusion Middleware Security and Administrator's Guide for Web
Services.
2.
In the exported jazn-data.xml file, grant access to the Web service using the
JDeveloper security policy editor.
2.
Enforce ADF Security authorization for the Web service in the Web service
implementation class.
2.
Grant access to the Web service by defining an entitlement grant with a custom
duty role that was added to the Oracle Fusion application policy store as the
grantee.
The entitlement grant to the role specifies that the end user must be a member of
the role to access the resources specified by the entitlement. You should use
custom duty roles and you should not grant entitlements to predefined duty roles.
For details about creating entitlement-based security policies using JDeveloper tools,
see Section 51.3.1, "How to Create Entitlement Grants for Custom Application Roles."
The following example shows a complete set of required grants enabling Web service
authorization.
Example 523
<type-name-ref>WebserviceResourceType</type-name-ref>
</resource>
</resources>
<!-- entitlement definition -->
<permission-sets>
<permission-set>
<name>MyWebServiceEntitlement</name>
<display-name>MyEntitlement display name</display-name>
<description>MyEntitlement description</description>
<member-resources>
<member-resource>
<type-name-ref>WebserviceResourceType</type-name-ref>
<resource-name>xmlns.oracle.com/apps/financials/subledgerAccounting
/accountingMethodSetup/accountRulesService/AccountRulesService#*
</resource-name>
<actions>invoke</actions>
</member-resource>
<member-resource>
<type-name-ref>WebserviceResourceType</type-name-ref>
<resource-name>http://xmlns.oracle.com/apps/contracts/
termsAuthoring/deliverables/service/
DeliverableService#findDeliverableByDeliverableId
</resource-name>
<actions>invoke</actions>
</member-resource>
</member-resources>
</permission-set>
</permission-sets>
<!-- Oracle function security policies -->
<jazn-policy>
<!-- function security policy is a grantee and permission set -->
<grant>
<!-- application role is the recipient of the privileges -->
<grantee>
<principals>
<principal>
<class>
oracle.security.jps.service.policystore.ApplicationRole
</class>
<name>AppRole</name>
<guid>F5494E409CFB11DEBFEBC11296284F58</guid>
</principal>
</principals>
</grantee>
<!-- entitlement granted to an application role -->
<permission-set-refs>
<permission-set-ref>
<name>MyWebServiceEntitlement</name>
</permission-set-ref>
</permission-set-refs>
</grant>
</jazn-policy>
</application>
</applications>
</policy-store>
</jazn-data>
For details about the ADF Security, see the "Enabling ADF Security in a Fusion Web
Application" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
On this component...
Use ServicePermissionCheckInterceptor to
implement authorization.
The ADF Business Components policy interceptor works for both RMI and SOAP
cases and supports the EJB implementation of ADF Business Components Web
services. Therefore, if ServicePermissionCheckInterceptor is specified in the ADF
Business Components Web service implementation class, an Oracle WSM
authorization policy is not required for Fusion Web services.
In the case of an ADF Business Components Web service, you enter the @Interceptors
annotation and import statements in the Web service implementation class to specify
the policy interceptor, as shown in the following example.
Example 524
import oracle.jbo.server.svc.ServicePermissionCheckInterceptor;
import oracle.jbo.server.svc.ServiceContextInterceptor;
@Interceptors({ServiceContextInterceptor.class, ServicePermissionCheckInterceptor.class})
public class xxxServiceImpl ...
In order for this interceptor to work, you need to configure the policy interceptor in
your ejb-jar.xml file. In the Application Navigator, expand the META-INF node of
the Web service project and double-click the ejb-jar.xml node. In the source editor, add
the JpsInterceptor definition required by the EJB for authorization checking, as
shown in the following example.
Example 525
<enterprise-beans>
...
</enterprise-beans>
<interceptors>
<interceptor>
<interceptor-class>
oracle.security.jps.ee.ejb.JpsInterceptor
</interceptor-class>
<env-entry>
<env-entry-name>application.name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>ApplicationName</env-entry-value>
<injection-target>
<injection-target-class>
oracle.security.jps.ee.ejb.JpsInterceptor
</injection-target-class>
<injection-target-name>
application_name
</injection-target-name>
</injection-target>
</env-entry>
</interceptor>
...
<interceptors>
<assembly-descriptor>
<interceptor-binding>
<ejb-name>*</ejb-name>
<interceptor-class>
oracle.security.jps.ee.ejb.JpsInterceptor
</interceptor-class>
</interceptor-binding>
</assembly-descriptor>
</ejb-jar>
For details about the ADF Business Components ServiceFactory class, see the
"Integrating Service-Enabled Application Modules" chapter of the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
For more information about Oracle Web Services Manager policies, see the
"Understanding Oracle WSM Policy Framework" chapter of the Oracle Fusion
Middleware Security and Administrator's Guide for Web Services.
user's HTTP session. This includes information that defines a context for the
application, such as its language preferences, date, and number formatting.
In order for application session context propagation to occur, you need to register the
ApplSessionContext class with the context interceptor infrastructure. Then when a
SOAP request is generated by the invoked web service, the request calls out to the
infrastructure and adds the application session context onto the SOAP payload.
To register the ApplSessionContext class, you must add the oracle.applcore.config
library to the weblogic-application.xml file for projects on both ends of the web
service request. In order for propagation to work, both the client sending the request
and the server receiving the request must have this library.
Before you begin:
It may be helpful to have an understanding of application user sessions. For more
information, see Chapter 49, "Implementing Application User Sessions."
You will need to complete this task:
Configure your project to use application user sessions. For more information, see
Section 49.2, "Configuring Your Project to Use Application User Sessions."
To add the Oracle Applications Core (Config) JDev library to the classpath:
1. In the Application Resources panel of the Application Navigator, double-click the
weblogic-application.xml file of the project that defines the incoming side of the
web service request.
2.
In the source editor for the file, add the following lines alongside the other
<library-ref> tags:
<library-ref>
<library-name>
oracle.applcore.config
</library-name>
</library-ref>
The order of the <library-ref> tags is not important; however, all <library-ref>
tags must be grouped together.
3.
Repeat this change in the project that defines the outgoing side of the web service
request.
In order for propagation to work, both the client sending the request and the
server receiving the request must have the oracle.applcore.config library.
53
Securing End-to-End Portlet Applications
53
This chapter describes how to authenticate and authorize portlet services, as well as
configure key and credential stores. The process of securing portlet services is similar
to that of securing web services.
Section 53.4, "Registering the Key Store and Writing to the Credential Store"
WSRP_v2_Markup_Service
WSRP_v2_PortletManagement_Service
WSRP_v2_Registration_Service
WSRP_v2_ServiceDescription_Service
The requirements for the client counterparts for each of these ports is the same. Clients
of the WSRP_v2_Markup_Service port inherit GPA, and clients of the three non-markup
ports propagate an anonymous token defined by the oracle/no_authentication_
client_policy policy.
The following table summarizes the policies attached to the portlet service and the
client.
Table 531
Portlets
Port
WSRP_v2_Markup_Service
WSRP_v2_
PortletManagement_
Service
oracle/no_authentication_
service_policy
oracle/no_authentication_
client_policy
WSRP_v2_Registration_
Service
oracle/no_authentication_
service_policy
oracle/no_authentication_
client_policy
WSRP_v2_
ServiceDescription_
Service
oracle/no_authentication_
service_policy
oracle/no_authentication_
client_policy
To override GPA and secure end-to-end portlet applications with a locally attached
policy:
When a policy is attached locally, Oracle ADF must authenticate the portlet service
against an Oracle Web Services Manager policy, such as wss10_saml_token_with_
credential store. You only need to perform this task when a policy has a message
protection or a SSL profile.
The key store contains the signing and encryption keys used to encrypt and decrypt
messages. The key store itself and all the keys are password protected. The keys are
also referred to using aliases, which are stored, along with their corresponding
passwords, in the credential store. When accessing the key store, query the credential
store first for the necessary aliases and passwords.
You can verify the creation of the key store and credential store as follows.
To verify the creation of the key store and credential store:
1. Open $DOMAIN_HOME/config/fmwconfig/jps-config.xml.
2.
Example 532
Verify the existence of the entry shown in the following example. This code should
be configured out of the box.
Example 533
Make sure the default context references the key store and credential store service
instances as shown in the following example.
<jpsContext name="default">
<serviceInstanceRef
<serviceInstanceRef
<serviceInstanceRef
<serviceInstanceRef
<serviceInstanceRef
</jpsContext>
ref="credstore"/>
ref="policystore.xml"/>
ref="audit"/>
ref="idstore.ldap"/>
ref="keystore"/>
Note:
After you create an entitlement grant for the desired task flow in jazn-data.xml, you
must create a resource grant for the portlet bridge component to the authenticated
role, as shown in the following example.
Example 534
<jazn-policy>
<grant>
<grantee>
<principals>
<principal>
<class>oracle.security.jps.internal.core.principals.
JpsAuthenticatedRoleImpl</class>
<name>authenticated-role</name>
</principal>
</principals>
</grantee>
<permissions>
<permission>
<class>oracle.adf.controller.security.TaskFlowPermission</class>
<name>/WEB-INF/adfp-portlet-bridge-container.xml
#adfp-portlet-bridge-container</name>
<actions>view</actions>
</permission>
</permissions>
</grant>
...
</jazn-policy>
The following examples shows an entitlement grant enabling access to the task flow.
Example 535
</resource-type>
</resource-types>
<resources>
<resource>
<name>/WEB-INF/my-task-flow.xml#my-task-flow</name>
<display-name>my-task-flow</display-name>
<description>/WEB-INF/my-task-flow</description>
<type-name-ref>TaskFlowResourceType</type-name-ref>
</resource>
</resources>
<!-- entitlement definition -->
<permission-sets>
<permission-set>
<name>MyPortletEntitlement</name>
<member-resources>
<member-resource>
<resource-name>/WEB-INF/my-task-flow.xml#
my-task-flow</type-name-ref>
<type-name-ref>TaskFlowResourceType</type-name-ref>
<display-name>my-task-flow</resource-name>
<actions>view</actions>
</member-resource>
</member-resources>
</permission-set>
</permission-sets>
<!-- Oracle function security policies -->
<jazn-policy>
<!-- function security policy is a grantee and permission set -->
<grant>
<!-- application role is the recipient of the privileges -->
<grantee>
<principals>
<principal>
<class>
oracle.security.jps.service.policystore.ApplicationRole
</class>
<name>AppRole</name>
</principal>
</principals>
</grantee>
<!-- entitlement granted to an application role -->
<permission-set-refs>
<permission-set-ref>
<name>MyPortletEntitlement</name>
</permission-set-ref>
</permission-set-refs>
</grant>
</jazn-policy>
</application>
</applications>
</policy-store>
</jazn-data>
Note when the Oracle Fusion application needs to provide anonymous access to a
portlet, the bridge wrapper task flow needs a grant to the anonymous-role, and the
markup port needs a no_authentication policy, or it can use GPA, but needs to
53-6 Developer's Guide
specify a Default User in the producer registration, using a valid guest user account, as
described in Section 53.3, "Securing the Portlet Client."
Token Profile: Select a policy that overrides GPA. For example, you might select
No Authentication Client Policy when locally attaching a policy for any of the
three non-markup ports.
Configuration: Select Default.
Default User: Leave empty or enter a valid guest user account ID to propagate to
the portlet.
Note that Default User is only used when the consumer identity is in fact
anonymous. In this case, the Default User field lets you specify some valid
identity that is necessary to propagate to the portlet, when the consumer is
anonymous, and the producer needs to receive a valid identity.
Within the portlet consumer domain, make sure the key store and credential store are
the same ones used by the portlet producer or service. The key store and credential
store are located at $DOMAIN_HOME/config/fmwconfig. For more information, see the
section about verifying the creation of the key store and credential store under
Section 53.2.2, "How to Configure the Key Store and Credential Store."
53.4 Registering the Key Store and Writing to the Credential Store
By default, globally attached policy profile specifies (authentication [AuthN]) and
there is no need to use Oracle Enterprise Manager to register a key store or create a
credential store. You only need to perform this task when a policy profile offers
message protection or SSL.
However, if you need to configure another key store for your domain, use Oracle
Enterprise Manager to register the key store and write to the credential store.
53.4.1 How to Register the Key Store and Write to the Credential Store
To register the key store and write to the credential store:
1. In Oracle Enterprise Manager, expand your domain. Select WebLogic Domain >
WebLogic Domain Name.
2.
In the right-hand pane, click the WebLogic Domain menu at the top of the page
and select Security > Credentials.
3.
If there is no map called oracle.wsm.security, create one. If the map exists, skip
this step. The following figure displays the Create Map window.
4.
In the right-hand pane, click the WebLogic Domain menu at the top of the page
and select Security > Security Provider Configuration.
5.
In the Service Provider Configuration page, under the Key Store section, click the
Configure button. The Service Provider Configuration page is shown in the
following figure.
6.
Keystore Path: Enter the path of the keystore, in this case ./producer.jks.
Password/Confirm Password: Enter the required password, then confirm the
password.
Signature Key
Encryption Key
7.
53.4.2 What Happens When You Register the Key Store and Write to the Credential
Store
Entering this information enables the creation of keystore-csf-key, sign-csf-key
and enc-csf-key in the credential store of the domain. You can verify that the keys
have been created by viewing the credential store page of the domain in Oracle
Enterprise Manager.
SOAP request is generated by the invoked web service, the request calls out to the
infrastructure and adds the application session context onto the SOAP payload.
To register the ApplSessionContext class, you must add the oracle.applcore.config
library to the weblogic-application.xml file for projects on both ends of the web
service request. In order for propagation to work, both the portlet consumer and the
portlet producer must have this library.
Before you begin:
It may be helpful to have an understanding of application user sessions. For more
information, see Chapter 49, "Implementing Application User Sessions."
You will need to complete this task:
Configure your project to use application user sessions. For more information, see
Section 49.2, "Configuring Your Project to Use Application User Sessions."
To add the Oracle Applications Core (Config) JDev library to the classpath:
In the Application Resources panel of the Application Navigator, double-click the
weblogic-application.xml file of the project that defines the portlet producer.
1.
2.
In the source editor for the file, add the following lines alongside the other
<library-ref> tags:
<library-ref>
<library-name>
oracle.applcore.config
</library-name>
</library-ref>
The order of the <library-ref> tags is not important; however, all <library-ref>
tags must be grouped together.
3.
Repeat this change in the project that defines the portlet consumer.
In order for propagation to work, both the portlet consumer and the portlet
producer must have the oracle.applcore.config library.
53-11
Part VIII
Part VIII
Advanced Topics
This part of the Developer's Guide provides information about some of the advanced
features that are part of Oracle Fusion. These advanced features include the Oracle
WebLogic Server, repositories used in Oracle Fusion, profiles, Oracle Fusion
application seed data, and the Oracle Fusion Database Schema Deployment
Framework. Also included in this part, are procedures for debugging Oracle
Application Development Framework (Oracle ADF) and service-oriented architecture
(SOA) applications.
Oracle WebLogic Server: Deployment is the process of packaging application files as an
archive file and transferring it to a target application server. You can use JDeveloper to
deploy your ADF applications directly to the WebLogic Server or indirectly to an
archive file as the deployment target. You can then install this archive file to the target
server. You can also run applications in JDeveloper using the Integrated WebLogic
Server.
The Creating Repository Connections chapter provides information about the repositories
that are used in Oracle Fusion and describes how to connect to each of these
repositories using JDeveloper. The repositories include the Oracle Data Integrator
(ODI), and Oracle Business Activity Monitoring (Oracle BAM).
A profile is a set of changeable options that affect the way your application looks and
behaves. Profiles control how applications operate for users by the values that are set.
Profiles can be set at different levels depending on how the profiles are defined.
Initializing Oracle Fusion Application Data Using the Seed Data Loader describes using the
essential data to enable Oracle Fusion Middleware applications. Some examples
include static lists of values, functional or error messages, and lookup values. The Seed
Data Utility, which runs under JDeveloper, provides data extraction from the
development instances of Oracle Fusion Applications. It also loads the extracted data
to the customer database instances of Oracle Fusion Applications by integrating with
Oracle ADF TaskManager. This part discusses how to set up your seed data
environment, and how to extract and upload seed data.
The Using the Oracle Fusion Database Schema Deployment Framework (applxdf) includes
JDeveloper plugins that handle applications-specific metadata, datamodeling
standards for applications database modeling, and deployment of database schema
objects to a target application database. The database schema deployment component
can be invoked standalone outside of JDeveloper, such as from the command line,
Build scripts, or a Patching Tool like Task Director. The Database Schema Deployment
Framework is packaged and delivered to Oracle Fusion Applications and technology
teams.
The Improving Performance chapter contains performance, scalability, and reliability
(PSR) best practices documented based on performance analysis of several
prototypical Oracle Fusion Applications as well as various tests conducted by the
Oracle Fusion middleware performance team. The outcome of this analysis is captured
in this chapter. It includes best practices for coding and tuning ADF Business
Components-based applications with performance, scalability, and reliability in mind.
The Debugging Oracle ADF and Oracle SOA Suite chapter describes the process of
debugging your Oracle Application Development Framework (Oracle ADF) and
Oracle SOA Suite applications. It describes how to diagnose and correct errors and
how to use the debugging tools.
Designing and Securing View Objects for Oracle Business Intelligence Applications provides
guidelines and best practices for designing and securing view objects and other
supporting ADF Business Components objects for use by Oracle Fusion Business
Intelligence (BI) Applications.
Implementing ADF Desktop Integration describes how Oracle Application Development
Framework Desktop Integration makes it possible to combine third party desktop
productivity applications with Oracle Fusion web applications, so you can use a
program like Microsoft Excel as an interface to access Oracle Fusion web application
data. Currently, ADF Desktop Integration supports using an Excel workbook to access
descriptive and key flexfield data in your application.
The Oracle Metadata Services (MDS) framework allows you to create customizable
applications. The Creating Customizable Applications chapter describes how to configure
your application at design time so that it can be customized. It also provides
information about how to customize your applications using JDeveloper and
WebCenter Composer.
Working with Extensions to Oracle Enterprise Scheduler explains how to use extensions to
Oracle Enterprise Scheduler to manage job request submissions in the context of
Oracle Fusion Applications.
Oracle Enterprise Scheduler Security explains how Oracle Enterprise Scheduler Security
features provide access control for Oracle Enterprise Scheduler resources and
application identity propagation for job execution.
Implementing Oracle Social Network Integration documents how developers can
implement Oracle Social Network in an application by defining each role a user can
have during Oracle Social Network interaction.
This part contains the following chapters:
Chapter 57, "Initializing Oracle Fusion Application Data Using the Seed Data
Loader"
Chapter 61, "Designing and Securing View Objects for Oracle Business Intelligence
Applications"
54
Running and Deploying Applications on
Oracle WebLogic Server
54
This chapter provides a basic overview of the Oracle WebLogic Server environment
and information about how to run your applications on Integrated WebLogic Server. It
also provides information about how to deploy your applications to the
Administration Server instance of WebLogic Server to perform end-to end testing of
new applications. If you are deploying customizations or extensions, see the Oracle
Fusion Applications Extensibility Guide for Developers.
This chapter includes the following sections:
The scope of this chapter is limited to what is unique in the Oracle Fusion Applications
environment. For general details about Oracle WebLogic Server, references are made to
the generic Oracle Fusion Middleware guides.
Deployment Technique
Environment
When to Use
Test or
Development
Test or
Development
All WebLogic Server instances within the same domain must be at the same major and
minor version. Servers within a domain can be at different maintenance pack levels if
the Administration Server instance of Weblogic Server is at the same maintenance
pack level or higher than WebLogic Server instances called Managed Servers. For more
information about the tasks that are required, see Section 54.3, "Preparing to Deploy
Oracle ADF Applications to an Administration Server Instance of WebLogic Server."
After you have performed the tasks required for standalone deployment, you can use
JDeveloper to deploy directly to a WebLogic Server instance or to create an Enterprise
Archive (EAR) file and deploy the EAR file using WebLogic Server Administration
Console, Enterprise Manager, or WebLogic Scripting Tool (WLST) commands.
For more information on how to deploy an application directly using JDeveloper, see
Section 54.4, "Deploying Your Oracle ADF Applications to an Administration Server
Instance of WebLogic Server."
For more information about deploying the application using WebLogic Server
Administration Console, or WLST, see the Oracle Fusion Middleware Administrator's
Guide and the Oracle Fusion Middleware Administrator's Guide for Oracle Application
Development Framework.
Note:
You must run the Configure Fusion Domain Wizard to set up the Integrated
WebLogic Server domain or create a property file to be used to set up the
standalone WebLogic Server domain. For instructions, see Chapter 2, "Setting Up
Your Development Environment."
2.
If you want more debugging output, set the environment variable using one of the
shell commands as shown in Example 541, before starting the Administration
Server instance of WebLogic Server or before starting JDeveloper if you are going
to run Integrated WebLogic Server.
Example 541
Enable you to start and stop the servers from a central location.
There is only one Administration Server instance of WebLogic Server in a domain, and
an Administration Server instance of WebLogic Server controls only one domain.
A Managed Server WebLogic Server instance is a running instance that hosts the
applications and the resources that are needed by those applications. Each Managed
Server WebLogic Server instance is independent of all other Managed Server
WebLogic Server instances in the domain, unless they are in a cluster. You can have as
many Managed Server WebLogic Server instances as you need in a domain.
The Administration Server instance of WebLogic Server stores the master copy of the
domain configuration, including the configuration for all Managed Server WebLogic
Server instances in the domain. Each Managed Server WebLogic Server instance stores
a local copy of its configuration. When a Managed Server WebLogic Server instance
starts, it connects to the Administration Server instance of WebLogic Server to
synchronize the configuration.
In most cases, a single server environment is used for development purposes. This is
where a single server acts as the Administration Server instance of WebLogic Server
and as the host for applications, as illustrated in Figure 543.
However, there are some teams that use a Managed Server for either Oracle Enterprise
Scheduler (ESS) runtime or Service-Oriented Architecture (SOA). When you are setting
up your standalone WebLogic server, you can choose one of the following options:
Non-SOA
SOA
Not all components are available in both. For example, WebCenter libraries are not
available in SOA and SOA libraries are not available in non-SOA. Oracle ADF
54-6 Developer's Guide
Note:
Integrated WebLogic Server has already been configured with the Oracle Fusion
Middleware Extensions for Applications (ApplCore) domain extension templates so
all of the Oracle Fusion applications will run on Integrated WebLogic Server as they
would in an Administration Server instance of WebLogic Server.
JDeveloper has a default connection to Integrated WebLogic Server and does not
require any deployment profiles or descriptors.
When you run your application in JDeveloper using the run or debug commands,
Integrated WebLogic Server starts automatically and your application runs in the
target browser.
When you use JDeveloper to run an application for the first time, it automatically
creates the Integrated WebLogic Server instance.
You can also start the server directly from within JDeveloper. To do this, go to the main
menu and select Run > Start Server Instance.
Tip: The first time Integrated WebLogic Server starts, it tries to use
the first available port in the 7101 - 7105 range. The following message
appears as the first line in the Default server log in JDeveloper. You
should use the alternate port for all access:
HTTP port conflict detected. The HTTP port will be reassigned to port 7102.
The server and the application are considered separate entities, so even if you stop the
application, it does not stop the server. To terminate the application, select the
application name from the terminate button dropdown menu in the Server Instance
Log page, as shown in Figure 545.
To terminate the server, select the server name, as shown in Figure 546.
Figure 546 Terminating the Integrated WebLogic Server Instance
1.
2.
In the Application Properties dialog, expand Run and choose MDS. See
Figure 547.
Preparing to Deploy Oracle ADF Applications to an Administration Server Instance of WebLogic Server
3.
Select the MAR profile from the MAR Profile dropdown list.
b.
c.
Select the Directory Content option. You can choose to preserve the
customizations across application runs or delete customizations before each
run.
Create and configure the WebLogic Server domains using the Configure Fusion
Domain wizard as described in Chapter 2, "Setting Up Your Development
Environment."
If the application is using ADF Security, you may need to:
Configure for Oracle Single Sign-on using Oracle Access Manager (OAM). For
more information, see the "Applications That Will Run Using Oracle Single
Sign-On (SSO)" section in the Oracle Fusion Middleware Fusion Developer's Guide
for Oracle Application Development Framework.
Preparing to Deploy Oracle ADF Applications to an Administration Server Instance of WebLogic Server
Server" section in the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
Set up JDBC URL for WebLogic Server. For more information, see the
"Applications with JDBC URL for WebLogic" section in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Set up JDBC datasource for WebLogic Server. For more information, see the
"Applications with JDBC Data Source for WebLogic" section in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
b.
c.
d.
3.
54.3.2 How to Create Deployment Profiles for Standalone WebLogic Server Deployment
The deployment profiles determine how the application is bundled and deployed to
Standalone WebLogic Server. When running an application within JDeveloper using
Integrated WebLogic Server, these deployment profiles are not used.
Deploying Your Oracle ADF Applications to an Administration Server Instance of WebLogic Server
To deploy the application, you must create deployment profiles applicable to the
project or projects. The deployment profiles you need depend on your application
requirements. For example, an application may include Business Components Service
Interface, Web Application Archive (WAR), and MAR profiles. When you have defined
these, create an EAR deployment profile for the application.
You can only deploy the application as an EAR file at the application level. Creating
EAR files from the project level are incomplete and this option is disabled. The project
level deployment profiles should be included in the EAR deployment profile.
Depending on the type of projects in your application, you may need to create the
following deployment profiles:
Business Components Service deployment profile. For instructions, see the "How
to Deploy Web Services to Oracle WebLogic Server" section of the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
EJB JAR deployment profile. For instructions, see the "Creating an EJB JAR
Deployment Profile" section of the Oracle Fusion Middleware Java EE Developer's
Guide for Oracle Application Development Framework.
WAR deployment profile. For instructions, see the "Creating a WAR Deployment
Profile" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework
MAR deployment profile. For instructions, see the "Creating a MAR Deployment
Profile" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework
EAR deployment profile. For instructions, see the "Creating an Application-Level
EAR Deployment Profile" section of the Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework
54-11
Deploying Your Oracle ADF Applications to an Administration Server Instance of WebLogic Server
Note:
3.
4.
b.
c.
Username and Password: Enter a user name and password for the
administrative user authorized to access the application server.
d.
e.
Port: Enter a port number for the Oracle WebLogic Server instance on which
your application (.jar,.war,.ear) will be deployed.
f.
In the SSL Port field, enter an SSL port number for the Oracle WebLogic
Server instance on which your application (.jar,.war,.ear) will be deployed.
g.
Select Always Use SSL to connect to the Oracle WebLogic Server instance
using the SSL port.
h.
i.
j.
Click Finish to close the wizard and create your application server connection.
Deploying Your Oracle ADF Applications to an Administration Server Instance of WebLogic Server
b.
c.
In the Select Server page, select the application server connection, and click
Next.
d.
The WebLogic Options page appears. Select a deploy option and click Next.
If the adf-config.xml file in the EAR file requires MDS repository
configuration, the Deployment Configuration dialog appears for you to
choose the target metadata repository or shared metadata repositories, as
shown in Figure 548.
The Repository Name dropdown list allows you to choose a target metadata
repository from a list of metadata repositories registered with the
Administration Server instance of WebLogic Server. The Partition Name
dropdown list allows you to choose the metadata repository partition to which
the application's metadata will be imported during deployment. For more
54-13
information about managing the MDS repository, see the Oracle Fusion
Middleware Administrator's Guide.
If you are deploying an Oracle ADF application, do not use the
Deploy to all instances in the domain option.
Note:
e.
2.
Click Finish.
Deploy the Project. For instructions to deploy a SOA project, see the "Deploying
the Profile " section of the Oracle Fusion Middleware Developer's Guide for Oracle
SOA Suite
3.
54-15
55
Creating Repository Connections
55
This chapter provides information about Oracle WebCenter Content Server (Content
Server), Oracle Data Integrator (ODI), and Oracle Business Activity Monitoring
(Oracle BAM) Server repositories, which are used in Oracle Fusion applications, and
describes how to connect to each of these repositories using Oracle JDeveloper.
This chapter includes these sections:
For information about using the WLST command-line scripting interface, see Oracle
Fusion Middleware Oracle WebLogic Scripting Tool.
Before you begin:
Verify that Content Server has been deployed and you have a working server that
works with the Oracle Fusion applications.
Ensure that the code grant entry for the Attachments-Model.jar file exists in the
application's jazn-data.xml file, as described in Section 19.3, "Creating
Attachments." When the application is deployed, the policies in jazn-data.xml are
merged into the system-jazn-data.xml file in weblogic_server_domain_
home/config/fmwconfig.
Log in to the content server and verify that your user name is a member of the
AttachmentsUser role. Note that employees and contingent workers have this role
automatically.
2.
3.
At the command line, type the following line to start the WLST tool, if it is not
currently running.
sh jdev_install/oracle_common/common/bin/wlst.sh
If you have not yet connected to the server, type the following WLST command to
connect to WebLogic Server, replacing the user name and password arguments
with your WebLogic Server user name and password.
connect('wls_username', 'wls_password', 'wls_uri')
From WLST, execute the following commands to store the credentials. The user
names and passwords must be the same as for the Content Server domain. For
more information about the WebCenter Content keystore credentials, see the
"Configuring Oracle WebCenter Content Applications" chapter in the Oracle Fusion
Middleware Installation Guide for Oracle Enterprise Content Management Suite.
When executing the commands, replace user name and password for user with the
user names and passwords that are used in the WebCenter Content credentials.
updateCred(map="oracle.wsm.security", key="keystore-csf-key", user="user name",
password="password for user", desc="Keystore key")
updateCred(map="oracle.wsm.security", key="enc-csf-key", user="user name",
password="password for user", desc="Encryption key")
updateCred(map="oracle.wsm.security", key="sign-csf-key", user="user name",
password="password for user", desc="Signing key")
exit()
Note:
createCred(map="oracle.wsm.security", key="keystore-csf-key",
user="user name", password="password for user", desc="Keystore
key")
createCred(map="oracle.wsm.security", key="enc-csf-key", user="user
name", password="password for user", desc="Encryption key")
createCred(map="oracle.wsm.security", key="sign-csf-key",
user="user name", password="password for user", desc="Signing key")
exit()
6.
7.
Table 551
Parameter
Value
jaxws
Admin Username
8.
Click Test Connection and verify that the status returned is Success!
If the test is unsuccessful, verify that the values that you
entered are correct and try again.
Note:
9.
Click OK.
10. From the Application Resources panel, expand Connections to see the new
11. Complete the following steps to verify that the application contains all required
2.
From the Applications Resources panel, select the content repository, drag it
onto the JavaServer Faces page, and choose Document Manager.
3.
Delete DocumentLibrary.jspx.
Ensure that the code grant entry for the Attachments-Model.jar file exists in the
application's jazn-data.xml file, as described in Section 19.3, "Creating
Attachments." When the application is deployed, the policies in jazn-data.xml are
merged into the system-jazn-data.xml file in weblogic_server_domain_
home/config/fmwconfig.
Ensure that the sockets on the WebCenter Content Managed Server are enabled.
For more information, see the "Completing the Initial WebCenter Content
Configuration" section in the Oracle Fusion Middleware Installation Guide for Oracle
Enterprise Content Management Suite.
You need the following information to create a content repository connection:
Host name of the machine that is running the WebCenter Content Managed
Server.
2.
Table 552
Parameter
Value
socket
Server Hostname
abc.example.com
4444
Authentication: Select External Application. Click the Add icon and complete the
following information to create a new External Application:
a.
Enter a unique name for the External Application. Click Next to continue to
Step 2.
b.
c.
d.
e.
Click Test Connection and verify that the status returned is Success.
If the test is unsuccessful, verify that the values that you
entered are correct and try again.
Note:
4.
Click OK.
5.
From the Application Resources panel, expand Connections to see the new
content repository connection, as shown in Figure 555.
6.
Complete the following steps to verify that the application contains all required
libraries and jazn-data.xml entries.
1.
2.
From the Applications Resources panel, select the content repository, drag it
onto the JavaServer Faces page, and choose Document Manager.
3.
Delete DocumentLibrary.jspx.
For more information, see the "Diagnosing Problems" chapter in the Oracle Fusion
Middleware Security and Administrator's Guide for Web Services.
password in the credentials for the content server's domain. If the stack trace reports
"Access Denied," verify that the code grants described in Section 19.3, "Creating
Attachments" have been added to the jazn-data.xml file. For information about
applications logging, see the "Troubleshooting Oracle Fusion Applications Using
Incidents, Logs, QuickTrace, and Diagnostic Tests" chapter in the Oracle Fusion
Applications Administrator's Troubleshooting Guide.
If your search through the application logs does not find an "Unable to generate digital
signature" string, the cause might be that the content server cannot verify the digital
signature. To diagnose the problem, set up tracing for fusionappsattachments, as
described in the "System Audit Tracing Sections Information" section in the Oracle
WebCenter Content System Administrator's Guide for Content Server. Be sure to enable full
verbose tracking and enable save. Access the system audit information server output
and search for XFND_SIGNATURE, as described in the "System Audit Information"
section in the Oracle Fusion Middleware Administering Oracle WebCenter Content. A blank
signature indicates that the signature was not generated by the Oracle Fusion
application. If the signature is not blank and the "$DefaultCheckinSigningScheme:
Signature Verification Failed" message exists, the cause might be that the credentials
for the application's server domain do not match the credentials for the content
server's domain and you need to repeat the connection steps described in this section
for the appropriate application type.
If you are using the file-based policy store for grants, then ensure that you have a
<grant> element similar to Example 551 in the <jazn-policy> element in the
jazn-data.xml file. Replace application-short-name with the name for your application.
Note that the application short name appears as the resource value in the error
message.
Example 551
<grant>
<grantee>
<codesource>
<url>file:${common.components.home}/modules/oracle.wsm.agent.common_
11.1.1/wsm-agent-core.jar</url>
</codesource>
</grantee>
<permissions>
<permission>
<class>oracle.wsm.security.WSIdentityPermission</class>
<name>resource=application-short-name</name>
<actions>assert</actions>
</permission>
</permissions>
You use Oracle Data Integrator Studio to access the repositories; administer the
infrastructure; reverse-engineer the metadata; develop projects; and perform
scheduling, operating, and monitoring executions.
To learn how to connect to the ODI master and work repositories, see the
"Administering the Oracle Data Integrator Repositories" chapter in the Oracle Fusion
Middleware Developer's Guide for Oracle Data Integrator.
For information about the role of ODI in securing Oracle Fusion applications, see
Section 48.1.1.7, "Oracle Data Integrator,"
Business Process Execution Language (BPEL) project is currently supported. For more
information about BPEL integration, see the Oracle Fusion Middleware Developer's Guide
for Oracle SOA Suite.
When building an application in JDeveloper, the methods of connecting to Oracle
BAM Server are:
Note:
Select the General > Connections category, then select BAM Connection. Click
OK to open the Oracle BAM Connection wizard, as shown in Figure 556.
3.
4.
5.
BAM Web Host: Enter the name of the host on which Oracle BAM Report Server
and the web server are installed. In most cases, the web host and the server host
are the same.
BAM Server Host: Enter the name of the host on which the Oracle BAM Server is
installed.
User Name and Password: Enter the Oracle BAM Server user name and password.
The user name is typically bamadmin.
HTTP Port: Enter the port number or accept the default value of 9001. This is the
HTTP port for the Oracle BAM Web Host.
JNDI Port: Enter the port number or accept the default value of 9001. The Java
Naming and Directory Interface (JNDI) port is for Oracle BAM Report Cache,
which is part of Oracle BAM Server.
Use HTTPS: Select this option if you want to use HTTP with Secure Sockets Layer
(HTTPS) to connect to the Oracle BAM Server during design time.
6.
Click Next.
7.
8.
Click Finish.
For more information about using Oracle BAM Adapter in a SOA composite
application, see the "Integrating Oracle BAM with SOA Composite Applications"
chapter in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
56
Defining Profiles
56
This chapter describes how to define a profile, which is a set of changeable options
that affect the way your application looks and behaves. Profiles control how Oracle
Fusion Applications operate for users by the values that are set. Profiles can be set at
different levels depending on how the profiles are defined.
This chapter includes the following sections:
Evaluate if there is a genuine need for an option before creating a profile. Do not
force the customer to make a decision about an issue that is of no concern to them.
Look for duplicate or similar profiles, even in other products, before creating a
new one. For example, you do not need multiple profiles to choose a preferred
currency.
Integrating Profiles Task Flows into Oracle Fusion Functional Setup Manager
Do not use profiles to cache temporary session attributes. Profiles are permanent
user preferences and system configuration options.
56.2 Integrating Profiles Task Flows into Oracle Fusion Functional Setup
Manager
Every Oracle application registers task flows with a product called Oracle Fusion
Functional Setup Manager. Functional Setup Manager provides a single, unified user
interface that allows customers and implementers to configure all Oracle applications
by defining custom configuration templates or tasks based on their business needs.
The Functional Setup Manager user interface (UI) enables customers and
implementers to select the business processes or products that they want to
implement.
Function Security controls your privileges to a specific task flow, and users who do not
have the required privilege cannot view the task flow. For more information about
how to implement function security privileges and roles, see Chapter 51,
"Implementing Function Security."
For more information about task flows, see theOracle Fusion Applications Common
Implementation Guide.
Table 561 lists the task flows related to profiles and their parameters.
Table 561
Task Flow
Name
Manage
Administrator
Profile Values
Parameters
Passed
mode='search'
[moduleType]
[moduleKey]
[categoryName]
[categoryApplicat
ionId]
mode='edit'
profileOptionNa
me
[pageTitle]
Behavior
Comments
moduleType/moduleKey
and
categoryName/categoryA
pplicationId are mutually
exclusive and cannot be
passed in together.
moduleType/moduleKey
and
categoryName/categoryA
pplicationId are mutually
exclusive and cannot be
passed in together.
In 'search' mode:
In 'search' mode:
In 'edit' mode:
In 'edit' mode:
56.3.1 How to View and Set Profile Values Using the Setup UI
You can use the Profile Option Values page to view the profile values. The page is
shown in Figure 561.
Notes:
2.
Note:
3.
In the Search Results: Profile Options section, highlight the required profile
option.
4.
In the Profile Values section, add a new value or delete an existing one.
Create a new row for every value set for this profile for every level/level value
pair. The Profile Value is the value that has been defined in the profile definition's
SQL Validation.
Before you can use this profile, you must add the Applications Core library to your
Model project. For more information, see Section 3.3, "Adding Necessary Libraries to
Your Data Model Project."
To access profile values programmatically:
Import the Profile class and call the Profile.get()method to get the values for the
profile name provided.
For example:
import oracle.apps.fnd.applcore.Profile;
...
fndDiagnostics = Profile.get("AFLOG_ENABLED");
After the bean is defined, you can refer to any profile value as:
# {Profile.values.PROFILE_OPTION_NAME}
Product
As most profiles are user preferences and can potentially be set at these three levels,
this is the default hierarchy. Profiles can be set at one or more levels.
Note:
Profile Settings
Hierarchy
Level
Profile Setting
1 (Lowest)
Site
Product
3 (Highest)
User
When a profile is set at more than one level, Site has the lowest priority, superseded by
Product, with User having the highest priority. A value entered at the Site level may be
overridden by values entered at any other level. A value entered at the User level has
the highest priority and overrides values at any other level.
For example, assume the Printer profile is set only at the Site and Product levels. When
a user logs on, the Printer profile assumes the value set at the Product level, since it is
the highest -level setting for the profile.
Tips:
1.
2.
In the Search Results: Profile Options section, highlight a profile option and do
any of the following:
Edit an existing profile option. The Edit window is shown in Figure 564.
3.
In the Search Results: Profile Option Levels section, do any of the following:
Updateable: Select this option to give the user update privileges. Leave
unselected if you want the user to have read-only access. This option is
disabled unless the Enabled option is selected.
Enabling the profile for end-user access allows the user to set their own
values.
Note:
Note:
2.
In the Search Results: Profile Categories section, highlight the required profile
category and do any of the following:
Edit an existing profile category. The Edit window is shown in Figure 566.
3.
57
Initializing Oracle Fusion Application Data
Using the Seed Data Loader
57
This chapter discusses the Seed Data Loader and using it from within Oracle
JDeveloper.
This chapter includes the following sections:
Note:
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-1
Table 571
Is the Module Striped?: Does this view object require a module argument?
Loader
View Object
Is the
Module
Striped?
attachments.attachmentLoader.applicationModule.attachm FndDocumentEntitiesVL
entsLoaderAM
attachments.attachmentLoader.applicationModule.attachm FndDocumentCategoriesVL
entsLoaderAM
attachments.attachmentLoader.applicationModule.attachm FndDocCategoriesToEntitiesVO
entsLoaderAM
Note: Before running this loader, you need to run the first two
loaders listed in this table that have the
FndDocumentEntitiesVL and the FndDocumentCategoriesVL
view objects.
dataSecurity.dataSecurityService.applicationModule.Dat FndMenus
aSecurityAM
dataSecurity.dataSecurityService.applicationModule.Dat FndGrants
aSecurityAM
dataSecurity.dataSecurityService.applicationModule.Dat FndObjects
aSecurityAM
dataSecurity.dataSecurityService.applicationModule.Dat FndFormFunctions
aSecurityAM
Loader
View Object
DocumentSequencesLoader
DocumentSequencesBULoader
DocumentSequencesLedgerLoader
DocumentSequencesLegalLoader
Is the
Module
Striped?
Y
docseq.docSeqService.applicationModule.DocSeqServiceAM DocSequenceAudit
docseq.docSeqService.applicationModule.DocSeqServiceAM DocSequenceUsers
flex.dff.category.categoryService.applicationModule.Ca Category
tegoryServiceAM
flex.dff.descriptiveFlexfieldService.applicationModule DescriptiveFlexfield
.DescriptiveFlexfieldServiceAM
flex.dff.descriptiveFlexfieldService.applicationModule DescriptiveFlexfieldSecondaryUsage
.DescriptiveFlexfieldServiceAM
flex.kff.keyFlexfieldService.applicationModule.KeyFlex KeyFlexfield
fieldServiceAM
flex.kff.keyFlexfieldService.applicationModule.KeyFlex KeyFlexfieldSecondaryTableUsage
fieldServiceAM
flex.vst.valueSetService.applicationModule.ValueSetSer ValueSet
viceAM
lookups.lookupService.applicationModule.LookupServiceA LookupView1
M
lookups.lookupService.applicationModule.LookupServiceA StandardLookupType1
M
lookups.lookupService.applicationModule.LookupServiceA CommonLookupType1
M
lookups.lookupService.applicationModule.LookupServiceA SetIdLookupType1
M
messages.messageService.applicationModule.MessageServi Message
ceAM
nls.currencyService.applicationModule.CurrencyServiceA Currency
M
nls.isoLanguageService.applicationModule.IsoLanguageSe IsoLanguage
rviceAM
nls.languageService.applicationModule.LanguageServiceA Language
M
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-3
Loader
View Object
Is the
Module
Striped?
nls.naturalLanguageService.applicationModule.NaturalLa NaturalLanguage
nguageServiceAM
nls.territoryService.applicationModule.TerritoryServic Territory
eAM
nls.timezoneService.applicationModule.TimezoneServiceA Timezone
M
profiles.profileService.applicationModule.ProfileServi ProfileCategory
ceAM
profiles.profileService.applicationModule.ProfileServi ProfileHierarchy
ceAM
profiles.profileService.applicationModule.ProfileServi ProfileLevel
ceAM
profiles.profileService.applicationModule.ProfileServi ProfileOption
ceAM
ref.industryService.applicationModule.IndustryServiceA Industry
M
setid.setIdService.applicationModule.SetIdServiceAM
SetIdSet
setid.setIdService.applicationModule.SetIdServiceAM
SetIdSummary
setid.setIdService.applicationModule.SetIdServiceAM
SetIdAssignmentsAB
SetIdAssignmentsBU
SetIdAssignmentsCST
SetIdAssignmentsPU
SetIdAssignmentsSet
SetIdReferenceGroup
trees.loader.applicationModule.TreeStructureLoader
FndTreeStructure
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomyVO
yAM
Special
case - all
the data
extracte
d into a
single
file.
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomyHierarchyVO
yAM
Special
case - all
the data
extracte
d into a
single
file
Loader
View Object
Is the
Module
Striped?
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomyPVO
yAM
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomySeedDataVO
yAM
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomySeedDataPVO
yAM
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomyComponentsVO
yAM
taxonomy.taxonomyService.applicationModule.ApplTaxonom ApplTaxonomyNodeComponentsVO Y
yAM
trees.loader.applicationModule.DefaultTreeLoader
FndTree
oracle.apps.fnd.appltest.diagfwk.seeddata.model.DiagFw FndDiagTag
kSeedDataAM
oracle.apps.fnd.appltest.diagfwk.seeddata.model.DiagFw FndDiagTest1
kSeedDataAM
2.
Create the ADF Business Components artifacts to represent the logical data model,
including entity objects and view objects in the project. Create the relationships
between the entity objects and view objects in accordance with the Applications
Standards. Add the objects to an application module that will serve as the entry
point for the Business Service Object. The application module also serves as the
container for the Seed Data Framework Configuration meta-data.
3.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-5
The Seed Data Configuration wizard launches and displays the Driver Definition
Panel.
This panel, shown in Figure 572, initially shows the available view objects in the
root level of the application module data model that can serve as Driver view
objects.
Figure 572 Seed Data Configuration Driver Panel
a.
Select the Driver check box for those view objects to serve as the Driver for
Seed Data Extract. More than one Driver can exist within an application
module; however, only one Driver can be specified at Extract time.
b.
Select the Configure radio button for the Driver view object to configure it
during this session. Only one driver view object can be configured during a
single editing session.
4.
View object relationships: The tree displays the model of the Seed Data
Configuration. Relationships between the view objects are displayed. The
relationship is either contained or just a reference. View links between the view
objects that are based on Associations marked explicitly as Composition
Association are shown as contained. Seed Data operations will be performed for
all the view objects that are identified as contained.
Foreign key relationships are called reference relationships. They are identified by
the existence of a view link between view objects backed by non-composite entity
associations, or no entity associations at all, or a join between two entity objects
(the referred entity object is marked as Reference in the View Definition) and a
List of Values on the name field.
Tables Information: The list shows the tables that are updated during Seed Data
upload. A non-editable list of tables is generated based on the declared data model
indicated by a Source column value of Model. The Type column indicates whether
the table is just Referenced or Updated. These tables and the explicitly added
tables with Type Updated will be frozen for (near) Zero-Downtime patching.
Table Freeze involves making the table in the Production edition read-only and
creating a replacement table in the Patch edition. The list of seed tables that will be
inserted, updated or referenced during seed data upload is provided as metadata
to the patching utility. This is auto-generated by the Configuration wizard by
inspecting the underlying entity objects and base tables for a given driver view
object.
If the entity objects of the configuration are not ADF Business Components-based,
or custom insert or updates exist (such as through PL/SQL code), the seed data
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-7
framework will not be able to accurately determine the set of tables participating
in the seed data upload. In such cases, the seed data framework will not be able to
accurately determine the set of tables to be frozen. The owner of the seed
application module must declare the additional tables in the container panel.
Failure to review and declare tables (such as by specifying a list that is incorrect or
incomplete) that are participating in seed data upload is likely to cause data
invalidation or corruption, as some tables will not be frozen and the Production
Instance will directly be aware of seed data upload changes that should be limited
to Patch Instance. Patch rollback also could leave orphan records in these cases.
Use the Add and Remove buttons to add or remove additional tables that are
affected from the list. The list of updated tables is for information only. This
information is used during patch application.
Table Name: This column shows the name of the table that is affected during seed
data upload.
View Name: This column shows the name of the ADF Business Components view
object where this table is declared. This column can also contain the name of the
Java class or PL/SQL procedure which would be used for seed data upload.
Source: Shows the source of this definition. The value of M is reserved to indicate
that the Table Name is derived from the ADF Business Components Model. You
can create your own definitions for additional table entries.
Type: This column shows the update type of the definition. A value of Updated
indicates that the definition table will be Updated at Seed Data Upload time. A
value of Referenced indicates that this is a Referenced table only, and will not be
updated by Seed Data Upload.
Click the Surrogate Panel.
Use the Surrogate Panel, shown in Figure 574, to declare surrogate attributes of
the view objects of the Seed Data Configuration.
Figure 574 Seed Data Configuration Surrogate Panel
The tree displays the model of the Seed Data Configuration. View objects can be
selected in the tree to declare a surrogate attribute of the selected view object.
If you have an entity object with a Surrogate ID that is
involved in a parent-child relationship, but you are not able to view or
select that Surrogate ID on the Surrogate panel, check the data model
and confirm that you have checked the composition check box for that
association. See the "Creating and Configuring Associations" section
of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
Note:
Surrogate Attribute Available: The left panel lists the attributes of the selected
view object that can possibly be a surrogate attribute. The list will include primary
key (PK) attributes that are of data type numeric.
Surrogate Attribute: The list on the right contains the attribute of the view object
that has been identified as a Surrogate Attribute.
Alternate Key: Select the Alternate Key that will be used as the unique row
identifier for the selected view object. The Alternate Key choice is based on the
Alternate Keys available on the entity object of the selected view object. If the
Primary Key has many attributes and one of them is being marked as a surrogate,
all the other attributes in the Primary Key, except the one being marked as
surrogate, must be included in the alternate key for that alternate key to be
displayed in the list.
For Date Effective models, the above rule has been relaxed so that Effective Start
Date, Effective End Date, Date Effective Sequence and Date Effective Flag are not
required to be in the alternate key, even if they happen to be in the Primary Key to
appear in the list.
To declare an attribute as a Surrogate Attribute:
a.
Select the view object that contains the surrogate attribute. The left bottom
panel will show the list of attributes that are potential surrogate attributes.
b.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-9
The tree displays the model of the Seed Data Configuration. Reference view
objects can be selected in the tree to declare information about the Seed Data
Configuration of the referred view object. All the external references must be specified
for the patch to succeed.
a.
In the tree view, select the reference view object. The bottom left panel will
contain a list of available application modules.
b.
Select the application module that contains the Seed Data Configuration
information for the reference view object.
c.
Note:
Table 572
Scenario
3.
4.
5.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-11
Each alternate key attribute needs to have an LOV defined, and each
LOV should have all the alternate key attributes as the driving attribute,
and the foreign key ID as the derived attribute.
1.
2.
3.
4.
5.
6.
1.
2.
3.
4.
5.
6.
7.
Each foreign key ID will be dealt with individually. For example, the
foreign key id is OrgId+SourceId, then orgId and SourceId should be
resolved based on solution in #1 or #2 or #3 separately. Then a validator
must be defined to make sure combination of OrgId and SourceId is
valid. This has the assumption that each individual attribute are a
primary key itself.
Note:
2.
3.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-13
If you change the name of a seed data file after Extract, you
also must manually update any references to that file name.
Otherwise, proper ordering for Upload during patching run time for
the files will not work as expected. So long as the physical file names
and the names in task references match, the patching utilities will
sequence the seed data tasks correctly.
Note:
The Seed Data Extract is driven off the Driver view object, as defined in the application
module Configuration. This Driver view object serves as the root of the extract, and
any contained child objects are extracted as containing data. Only one Driver view
object is active during the Extract process.
There are two methods of starting a Seed Data Extract process:
If there are multiple database connections in the workspace, the Seed Data Console
Select Database dialog, shown in Figure 577, displays.
Although this is not the normal case, if you need to debug data on two different
databases, this lets you choose which one to use.
Select from the list of database connections available to the project. The default
selected database is the default connection set on the Project Properties, under
Business Components.
Click OK to launch the Seed Data Console with the selected connection information.
The Seed Data Console main page, as shown in Figure 578, displays.
Figure 578 Seed Data Console Main Page
The tree view shows the selected application module name as the root node, and each
of the configured Driver view objects as child nodes under the root. Only Driver view
objects as configured by the Seed Data Configuration wizard will show in this view.
The right side of Console is the output area, where processing messages of Seed Data
tasks are displayed.
The Seed Data Console does not specify the last applied
version of the seed data file. Consequently, users always will see a
warning message indicating incremental uploads have been turned
off. This is harmless and can be ignored.
Note:
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-15
Type a directory path location in the File Name text box, or browse to an existing
location using the directory browser. The directory location need not necessarily exist
when typing a new name, as the directory paths will be created as needed during the
Extract process. The Extract directory path selected is used as the Seed Data Extract
Root for the generated extract files.
known beforehand, users can pick them from the list of available products. Optionally,
click Filter to filter the list of products to show only those products and Logical
Business Area (LBA) modules for which records exist in the selected view object.
Occasionally, when there are a large number of records involved, the it might take a
while to filter the list of products.
Figure 5711
If any Products or LBAs are selected that are not actually available in the view object,
no attempt is made to extract for that partition. This is done by applying implicit
Partition criteria, binding for each selected partition, and verifying at least one row
exists for the Partition row set before attempting to extract.
For internal development test cases and debugging for Extract, you will need to know
which partitions are available. To do so, you have to select the ModuleIds from the
driver and discover which Product that ModuleId equates to from the Taxonomy table.
If the driver view object moduleId is an LBA, you also will need to know under which
Product that LBA falls; this involves selecting from the Taxonomy hierarchy table.
An alternate method is to just select all the Products and all the LBAs when prompted
by the dialog. Then extract files are created for only those modules that actually exist.
This will be a little slower, since building the complete LBA list from all Products can
take a few seconds or longer. Then each selected partition is bound to determine the
availability. This will not be the typical Applications use case, as developers will know
which Products to select. It is necessary in a development case in which the Products
are not known.
LBA Taxonomy Partitions
After selecting the Products, the second dialog, Select Application Taxonomy LBA
Modules, may or may not be shown. If the selected Products were parents of explicitly
available seed-enabled LBA modules, all the available LBAs for the selected Products
are shown. Again, only LBA module types found in the driver view object rows, and
set as Seed Enabled in the Taxonomy Service, are shown in the list.
If the selected Products were not parents, or there are no LBAs available, no LBA
selection dialog is shown, and Extract is started for all the selected Products.
For the LBA selection dialog, the full LBA taxonomy path is shown, showing any
parents of subLBAs, and the parent Product short name. Again, the user selects the
desired LBA values by shuttling values to Selected.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-17
Figure 5712 shows the Select LBA Taxonomy Partitions dialog showing all the
available LBAs found for the previously selected Receivables (AR), Payments (IBY),
and Human Resources (PER) Products.
Figure 5712
Extract Processing
After selecting LBAs, Extract proceeds to extract selected LBAs and selected base
(non-parent) Product types, if any. Each Product and LBA type name value
corresponds to a unique Extract file. Each Extract file will contain all rows containing
the Taxonomy Partition Attribute (ModuleId or ApplicationId) value corresponding to
each selected type.
Extract files are placed in folders according to the taxonomy path, starting at the
Product short name, and including any LBAs and subLBAs as subdirectories. All the
Extract file names follow the same pattern: <driver view object name>SD.xml.
Figure 5713 shows a sample output selecting the three Receivable (AR) LBAs,
creditCardErrors, customerProfileClasses, and miscellaneousReceipts, and General
Ledger (AR) and Opportunity Management (MOO) Applications. The applications,
AR and MOO, were explicitly defined in the entity, and contained no child LBAs.
Figure 5713
1.
2.
3.
4.
adxml are the comments added to the extract file at the beginning of the file. They are
the same as normal xml comments except they have adxml: prepended to the
commented text.
Extract gathers this information by using the Reference view object from Reference
application module. Reference application module is configured by the user in the
Reference panel of Seed Data Configuration. See Figure 575.
This information is used by the Patching Utility to create the order in which the files
need to be uploaded so that the Reference data is available before the Referring data is
loaded.
Static File Dependencies
For the cases where dynamically finding the file dependencies is not possible, or
dynamic dependencies are not complete, you can set static file dependencies using an
application module custom property for a view object instance, as shown in
Table 573.
All files extracted from that view object would have the dependencies stamped in
adxml comments.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-19
Table 573
Value
Example
SD_DEPENDENT_FILES_<View
object instance name>
<product>:<path>:<filename>,
<product>:<path>:<filename>,..
Property: SD_DEPENDENT_FILES_
TimeDefinition1
Value:
HCM:HCM/Per:LookupsSD.xml,FND:F
ND:ValueSetSD.xml
Value
Example
true
Property: SD_NO_DYNAMIC_EXT_REFS_FndObjects
Value: true
By using a command property file that is singularly passed on the command line
instance name>
string without username and password>
seed configured AM>
instance name>
The command property file is an external file that contains the command line
properties in standard Java Properties format for each of the required and optional
Extract command line properties. The format can be name=value, or name:value.
Seed Data Extract Command Line Parameters
The available Seed Data Extract parameters are listed in Table 575.
Table 575
Property
Value
Required?
Example
dburl
Yes
jdbc:oracle:thin:@fully_qualified_
server_name:1991:database_name
dbuser
Yes
fusion
AM
Yes
oracle.apps.fnd.applcore.flex.dff.des
criptiveFlexfieldService.
applicationModule.DescriptiveFlexf
ieldServiceAM
VO
Yes
DescriptiveFlexfield
ExtractRootPath
No
/home/seed/data
PartitionKeyIds
No
PartitionKeyNames
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-21
Value
Required?
Example
loglevel
No
-loglevel FINE
log
No
-log /home/seed/ex.log
Entid
No
-entid 1
Note:
PartitionKey<Ids|Names> Properties
The PartitionKey properties drive how the seed data extract derives the data file
partitions, which is the number of files generated. Each partition key will equate to a
single extracted seed file, with all the rows that are owned by that particular module
being extracted to its seed file.
You can use either the PartitionKeyIds or the PartitionKeyNames property, or a
combination of both, to supply to the extract each of the unique file partitions that will
be created. If no PartitionKey properties are specified, the default behavior is to extract
all file partitions found from the driver view object, and all rows extracted to each
corresponding seed data file.
You should use one of the PartitionKey parameters to limit the amount of files
generated. Otherwise, the expected partitions will need to be determined from
executing the driver view object query and perform a complete table scan of all rows.
For very large tables with many thousands of rows, this could be a potentially large
performance hit, and, depending on the complexity of the view object query and its
joins, could take several minutes to hours to determine.
Property File Comments
In the command property file, any lines beginning with a pound sign (#) will be
considered comments, and not processed in any way by the Extract tool.
You also can comment out specific entries in the multi-value comma delimited
properties. For example:
PartitionKeyNames = FND, HCM, #FCM, GL, AM
This will ignore the FCM value entry, but keep others intact. A sample
PartitionKeyNames command line option is shown in Example 572.
Example 572
scriptiveFlexfieldServiceAM
-VO DescriptiveFlexfield
-ExtractRootPath /home/seed/data
-PartitionKeyNames HCM, invoices, cashManagement
-loglevel FINER
Example 573 shows the contents of the sample Seed Extract Command Property File,
located at /home/extract.properties:
Example 573
In addition to the Load Seed Data option, discussed in Section 57.2.5.1, "Uploading
Seed Data," three other options are available:
Set Log Level
Set how much information you want written to the log file. The least amount of
information will be if this is set to Severe, and the largest amount of information will
be is this is set to Finest. The default setting is Info, which will log Information,
Warning and Severe messages.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-23
Clean Mode
The default setting is Disabled. If Clean Mode is Enabled, it basically deletes all the
existing records before proceeding to upload the given file. This option is exposed both
through the command line interface for upload (-clean) and here.
Caution: This option should be used extremely carefully as it might lead to
irreversible data loss.
Customization Mode
The default setting is Do Not Preserve.
Seed Data Loader always sets the last_updated_by and created_by to zero when it
inserts new records, and it always sets the last_updated_by to zero when it updates
existing records.
Customers who have customized some of the Seed Data records are expected to set
last_updated_by to a non-zero value.
By default when using the Seed Data Console, customizations are not preserved. They are
overwritten.
However, on the command line, which is primarily intended for use at the customer
site and for automated uploads, customizations are preserved by default. To override
this, use the -nocust option.
Important:
Figure 5715
Select either an XML file or its corresponding translation xliff file to initiate a National
Language Support (NLS) upload.
Click OK to begin the Upload process on the selected file.
Upload Output
When the Seed Data upload finishes, the processing messages are shown in the output
tabbed view window, in the tab corresponding to the view object against which the
upload was run. See Figure 5716.
Figure 5716
You may see warning messages about columns being not updateable. Review these
messages to determine if you can ignore them for your specific case.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-25
57.2.5.1.1
The Seed Data Upload process can be initiated externally from JDeveloper using the
Command Line Interface (CLI).
To run the command line version of the Seed Data Loader from within an ADE view,
ensure the JDEV_HOME environment variable, shown in Table 576, is set to a valid
JDeveloper installation directory. Include the jdeveloper sub folder if you are using
JDeveloper integrated with WebLogic Server.
Table 576
Variable name
Required? Purpose
JDEV_HOME
No
APPLSEED_
CLASSPATH
No
APPLSEED_TS_
CLASSPATH
No
APPLSEED_
CLASSPATH_FILE
No
APPLSEED_TS_
CLASSPATH_FILE
No
Note:
Example 575
57.2.5.1.2 How to Invoke Seed Loader Modes Three modes can be invoked when running
a Seed Data Upload from the command line.
-clean: This flag's primary purpose is to make the set of records in the database
reflect exactly what is delivered in the seed data file. If the set of records in the
database becomes out of sync with what is delivered in the file, the -clean flag can
be used to load the seed data file and make sure the database only has those
records delivered from the file. This is turned off by default.
-atomic: This flag's primary purpose is to let the seed framework ensure that all
the records in a given file are loaded. If all records are not loaded, none will be
loaded. If even one record fails, the loading is stopped and all the previously
loaded records are rolled back. That is, a single commit is issued towards the end
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-27
of the file. This is turned off by default and a commit is done after every top level
record.
-nocust: This flag's primary purpose is to let the seed framework know that it
should not preserve any customizations done by the customer in the database
version of the records. Data from the file is expected to overwrite anything that is
in the database. This is turned off by default.
Important Points
The database password would be prompted. The password can be piped in to
avoid prompting. The password must be piped in if output is redirected.
A failure during the cleanup stage does not prevent the subsequent loading of the
records from the file.
The -clean, -nocust and -atomic flags can be used independently of each other.
The clean mode deletes all the records that satisfy a particular condition. In
normal use cases, this is the partitioning criteria (ModuleId or ApplicationId)
used when the data was extracted. The Seed data file has metadata about the
partitioning attribute (ModuleId, ApplicationId or any other partitioning
scheme) and the exact values for those attributes used during extract.
Example
Using the Messages model from the Oracle Fusion Middleware Extensions for
Applications, when PER/SomePerLba developers extract their messages, they
will receive a set of Messages owned by that LBA. The seed data file captures
this metadata that is used during -clean to determine the set of records to
remove. In this case, all the messages owned by PER/SomePerLba will be
removed.
The set of records deleted does not depend on the set of records in the file. It is
only driven by the partitioning metadata stored inside the file. The loader
would not have even read the records in the file by the time the cleanup is
made.
Example
If PER/SomePerLba owns 10 messages in the database and an incoming
MessageSD.xml brings in only six messages, which might be the same as or
different from those in the database, the 10 messages in the database are all
removed and the ones from the file are all loaded. If the loading succeeds, the
database should have only six records owned by PER/SomePerLba - exactly
what the seed data file brought in.
top level records fail, they all will be left out of the database. Therefore, only a
subset of the records that came in the file will remain. This behavior changes when
using the -atomic flag. This flag essentially says "make sure all the records, or none
of the records, in the file are loaded." In this case, the cleanup and the loading are
committed only once towards the end of the file. Even if one record fails, the
deletes and any intervening loads are rolled back.
The imported Business Components can be seen using the Business Components
Import feature of JDeveloper. Once imported, developers can use these libraries to
extract and upload seed data, but cannot edit the Seed Data configuration.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-29
Figure 5718
Since Application Modules shared using an ADF Business Components library are not
shown by JDeveloper in the Application Navigator, users must right-click the Business
Components project into which they imported the shared libraries. The Seed Data
menus would also be available on any Business Components project node in the
Applications Navigator tree of JDeveloper.
Figure 5719
Clicking any of the Seed Framework menu items will display a tree structure showing
all the Seed Framework-enabled Application Modules (those that have at least one
Seed Data driver view object configured within them) available to that project.
Figure 5720
Users can choose an available application module and click OK to display the familiar
Seed Data console to perform and extract or upload activities.
Feature
Applicable
to
Default
Setting
Runtime Control
Incremental Only US
Updates
language
seed data
files
On
On for
Disabled by setting SD_NLS_USE_ Disabled by setting APPLSEED_NLS_
USE_ADF to true
newly
ADF_<ViewDefinitionName> to
extracted true
files
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-31
For certain kinds of requirements where it is desirable to have the seed data loaded as
a set, and therefore incremental updates are not desirable, the Seed Data Framework
provides an optional feature that allows product teams to disable this feature.
During extract, the Seed Data Framework computes MD5 checksums on the source
record by taking all the fields that make up the record (excluding key attributes,
history columns and non persistent fields). This checksum is embedded in the seed
data file as additional record level metadata. At load time, if the record is found
existing in the target database, the same algorithm is used to compute the checksum
on the target record. By comparing the two checksum values, the seed data loader
identifies if the record has undergone a change and needs an update. Updates are
triggered only for those records for which the checksums do not match.
This incremental update feature is applicable to only US language seed data XML files
and is enabled by default. For translated seed data, there is no provision to do
incremental updates.
To disable this feature for a particular seed data driver view object and all its child
view objects, the SD_INCR_MIDTIER_<ViewDefinitionName> property should be added
to the application module.
Set the value of this property to false to turn off incremental updates.
SD_INCR_MIDTIER_ValueSetVO false
Note that the incremental updates feature requires new metadata, in the form of
checksums, to be embedded into the seed data file. Consequently, only newer seed
data files can take advantage of this feature. Note that the incremental updates feature
requires new metadata in the form of checksums to be embedded into the seed data
file. Consequently, only newer seed data files can take advantage of this feature. With
older seed data files, the seed data loader shall continue to update all the records, even
if the application module has the feature enabled using the SD_INCR_MIDTIER property
As a debugging aid, the seed data loader also allows for incremental updates to be
conditionally turned off at run time. Use the -noincr optional command line
parameter to the loader or set the APPLSEED_NO_INCREMENTAL environment variable to
true.
kinds of translated seed data need to be always loaded using ADF, it is possible to do
so using one of these ways:
57.3.1.1 Treating Seed Data Base XML and Language XLIFF as a Single Entity
The seed data base and XLIFF files must be treated as a single entity. Any changes to
either base or translated attributes that would require a re-extract, would necessitate
that both the re-extracted base XML and US XLIFF files be delivered as units. There is
metadata in the files to ensure that the base and XLIFF files match and were extracted
together.
Initializing Oracle Fusion Application Data Using the Seed Data Loader
57-33
When loading the base seed XML file, the language rows are initially created using the
US translation values. Then when loading the language translation files, the rows are
updated using the incoming language values. This way, it is not necessary to have
translations for every single row. If no translations exist, the fall back is then to use the
US language row.
It is not necessary to upload the US language XLIFF file, as US translation data is
already saved in the base seed data XML file.
58
Using the Database Schema Deployment
Framework
58
This chapter discusses database modeling and database schema deployment in Oracle
Fusion Middleware.
When designing an application to interact with the database, you will need to
understand the database schema and be able to modify the schema as needed. This
chapter contains information regarding database modeling and database schema
deployment in Oracle Fusion Middleware. Developers should not use SQL DDL
scripts for deployment and source control of database objects, because they tend to be
error-prone and do not serve as a single accurate source. Instead, developers should
use the JDeveloper offline database schema object files in SXML persistence mode.
Before SXML migration, these were referred to as XDF
(extension) files.
Note:
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
possible to create, edit, delete and manipulate aspects of a database schema offline and
access database objects in a database through JDeveloper's connections.
All schema modeling can be done through JDeveloper. The XDF extension provides
developers with a set of tools to do the data physical modeling, such as create, edit,
deploy, and import the schema objects used in applications. The extension also
provides Application Data Modeling Standard validation, modification, and template
object plugins in JDeveloper to help users to follow the Data Model standards.
Developers will use XDF extensions for their database modeling development.
Information covered here includes:
The purpose of the offline database and how to create the database objects in the
offline database using JDeveloper.
The functions provided by the XDF extension how to use the XDF deployment
and import tools in JDeveloper.
The definitions of all User Defined Properties (UDP) that are provided by the XDF
extension user property library.
The UDPs developers should and can define for their schema objects in
JDeveloper.
3.
From the New Gallery, select Database Tier > Offline Database Objects > Offline
Database, as shown in Figure 581.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
4.
In the Create Offline Database dialog, enter a name for the offline database, as
shown in Figure 582. For more information at any time, press F1 or click Help
from within the Create Offline Database dialog.
The following types of objects are modeled using offline database objects.
Table
Trigger
View
Materialized View
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Sequence
Synonym
JDeveloper offline database objects do not support these objects. However, SXML
persistence files for these object types can be imported using the applxdf extension.
Queue
Queue tables
Policy
If the length of the object name is greater than the length standard and if the
short name is null or empty, display a warning.
If the short name is not null or empty, check if the length of the short name is
greater than the length standard. If it is, display a warning message.
If the length of the object name is not greater than the length standard and if
the short name is null or empty, automatically set the short name to be the
same as the object name.
If the short name is not null or empty, check if the length of the short name is
greater than the length standard. If it is, display a warning message.
The name length standard for a Table is 24; for all others, it is 27.
Adxml (UDP)
The UDP adxml is set automatically for these schema object types:
Table.TYPE
View.TYPE
Synonym.TYPE
Sequence.TYPE
MaterializedViewLog.TYPE
MaterializedView.TYPE
Trigger.TYPE
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
The content of the UDP adxml will be determined by the current value of the UDP
adxml and the UDP useExistingAdxml.
AdxmlFK (UDP)
For table type only, automatically set the UDP adxmlFk according to the values of
the UDP adxmlFk and useExistingAdxml.
AdxmlDeferredIndexes (UDP)
For table and MaterializedView.type only, automatically set the UDP
adxmlDeferredIndexes according to the current value of this UDP and the value
of UDP useExistingAdxml.
Dependencies/Risk
This feature uses JDeveloper's Offline database APIs and therefore has a
dependency on all the offline database JAR files. The risk for this feature is some
enforcement of standards may fire wrongly due to potential bugs preventing
developers from modeling their objects as needed.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 581
UDP
Display Name
Values in JDeveloper
enableAudit
Enable Audit
Is Flashback
Allowed
isLogical
The value of this UDP
indicates whether the
deployment program
will create an editioning
view for this table or not.
This UDP is required.
runTwice
LOGICAL
VARCHAR2(1) Not
N: The deployment program will not create an Null
editioning view for this table.
Run
Deployment
Twice
N/A
Y: Specifies that the table must be deployed
twice and the appropriate patching metadata
will be stamped in the file. This is typically
used when a product team adds or modifies a
column as a not-null column to a existing
table, and does not want to use a RBMS
default value. The column will be populated
with an upgrade script having a more
complex logic. The column needs to exist in
the target database before the upgrade script
is run. Also, the upgrade script cannot enforce
the not-null constraint since it is against the
standards to have DDL in scripts. Setting this
UDP to Y will accommodate this.
N (default).
shortName
The short name of the
table is used by the Zero
Downtime programs to
uniquely identify the
table. The maximum
length of this UDP is 24
characters.
objectOwner
This UDP stores the
Short Name of the
application that the table
belongs to.
This UDP is mandatory.
Table Short
Name
N/A
Table Owner
N/A
SHORT_NAME
APPLICATION_
SHORT_NAME
VARCHAR2(10)
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Display Name
Values in JDeveloper
Definition in FND_
TABLES
tsClassification
Tablespace
Classification
N/A
REFERENCE
INTERFACE
SUMMARY
ARCHIVE
TOOLS
MEDIA
MLS Support
Model
MLS_SUPPORT_
MODEL
VARCHAR2(30)
Status
Extension of
Table
STATUS
VARCHAR2(30)
N/A
EXTENSION_OF_
TABLE
VARCHAR2(30)
Deploy To
DEPLOY_TO
VARCHAR2(30)
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Display Name
Values in JDeveloper
conflictResolution
Conflict
Resolution
Definition in FND_
TABLES
CONFLICT_
RESOLUTION
VARCHAR2(30)
Shared Object
SHARED_OBJECT
VARCHAR2(30)
N/A
N/A
ADXML for
Foreign Keys
N/A
N/A
ADXML for
Deferred
Indexes
N/A
N/A
Use Existing
ADXML
Is Select
Allowed
Y (default)
SELECT_ALLOWED
VARCHAR2(1) Not
Null
Is Update
Allowed
Y (default)
UPDATE_
ALLOWED
VARCHAR2(1) Not
Null
Is Insert
Allowed
Y (default)
INSERT_ALLOWED
VARCHAR2(1) Not
Null
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Display Name
Values in JDeveloper
isDeleteAllowed
Is Delete
Allowed
Y (default)
DELETE_
ALLOWED
VARCHAR2(1) Not
Null
Is Truncate
Allowed
TRUNCATE_
ALLOWED
N (default)
VARCHAR2(1) Not
Null
Maintain
Partition
MAINTAIN_
PARTITION
N (default)
VARCHAR2(1) Not
Null
Exchange
Partition
EXCHANGE_
PARTITION
N (default)
VARCHAR2(1) Not
Null
Maintain Index
maintainIndex
Definition in FND_
TABLES
MAINTAIN_INDEX
N (default)
VARCHAR2(1) Not
Null
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 582
UDP
Display Name
Values in JDeveloper
Definition in FND_
COLUMNS
logging
Supplemental
Logging
N/A
Column Short
Name
N/A
Translate
TRANSLATE_FLAG
VARCHAR2(1) Not
Null
STATUS
VARCHAR2(30)
N (default)
SHORT_NAME
VARCHAR2(27)
Null
Status
Custom Default
Value
N/A
N/A
denormPath
Denormalization N/A
Path
N/A
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
UDP
Display Name
Values in JDeveloper
routingMode
Routing Mode
Histogram
N/A
histogramSize
N/A
Disconnected
Mobile Version
Column Name
N/A
VERSION_
COLUMN
VARCHAR2(30
CHAR)
58-11
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 583
UDP
Display Name
Values in JDeveloper
Definition in FND_
INDEXES
shortName
Index Short
Name
N/A
SHORT_NAME
Index Deferred
(Y/N)
VARCHAR2(30)
Null
N/A
status
The value of this UDP
indicates the status of the
index.
STATUS
VARCHAR2(30)
DEPLOY_TO
deployTo
The value of this UDP
indicates the deployment
mode of the index for the
Oracle Fusion
Disconnected Mobile
Framework.
This UDP is required.
VARCHAR2(30)
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 584
UDP
Display Name
Values in JDeveloper
isLogical
Logical
Constraint
Definition in FND_
PRIMARY_KEYS or
FND_FOREIGN_
KEYS
LOGICAL
VARCHAR2(1)
Constraint
Short Name
SHORT_NAME
VARCHAR(30)
Defer
Constraint
N/A
status
The value of this UDP
indicates the status of the
constraint.
N/A
58-13
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 585
UDP
Display Name
Values in JDeveloper
Definition in FND_
VIEWS
adxml
ADXML
N/A
N/A
Is Flashback
Allowed
FLASHBACK_
ALLOWED
useExistingAdxml
N/A
View Owner
N/A
APPLICATION_
SHORT_NAME
Status
STATUS
VARCHAR2(30)
Is Select
Allowed
Y (default)
SELECT_ALLOWED
VARCHAR2(1) Not
Null
Is Update
Allowed
Y (default)
UPDATE_
ALLOWED
VARCHAR2(1) Not
Null
Is Insert
Allowed
Y (default)
INSERT_ALLOWED
VARCHAR2(1) Not
Null
Is Delete
Allowed
Y (default)
DELETE_
ALLOWED
VARCHAR2(1) Not
Null
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 586
UDP
Display Name
Values in JDeveloper
objectOwner
Sequence
Owner
N/A
APPLICATION_
SHORT_NAME
Status
STATUS
VARCHAR2(30)
Null
ADXML
N/A
N/A
Use Existing
ADXML
N/A
Is Select
Allowed
Y (default)
SELECT_ALLOWED
VARCHAR2(1) Not
Null
Reset Sequence
RESET_SEQUENCE
N (default)
VARCHAR2(1) Not
Null
58-15
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 587
UDP
Display Name
Values in JDeveloper
Definition in FND_
MVIEWS
objectOwner
Mview Owner
N/A
N/A
Materialized
View Short
Name
N/A
SHORT_NAME
Status
VARCHAR2(30)
VARCHAR2(30)
adxml
STATUS
N/A
tsClassification
TRANSACTION_TABLES
N/A
REFERENCE
INTERFACE
SUMMARY (default)
ARCHIVE
TOOLS
MEDIA
useExistingAdxml
This UDP is mandatory.
Use Existing
ADXML
N/A
Is Select
Allowed
Y (default)
SELECT_ALLOWED
VARCHAR2(1) Not
Null
ADXML for
Deferred
Indexes
N/A
N/A
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Table 588
UDP
Display Name
Values in JDeveloper
status
Status
objectOwner
Materialized view log
owner.
ADXML
adxml
The value of this UDP is
patch metadata used by
the patching tool.
useExistingAdxml
N (default)
UDP
Display Name
Values in JDeveloper
status
Status
objectOwner
Trigger Owner
adxml
ADXML
N/A
Use Existing
ADXML
Select any Offline database object definition that you wish to create.
You also can create an offline database object definition by importing an existing
definition from an online database schema.
58-17
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
In the Edit dialog, select an information category on the left and change the values
in the panel on the right. Any items that are grayed out cannot be selected or
changed.
1.
The target database connection name can be selected from the list of all defined
database connections, or a new connection can be created in the Specify Source
dialog, shown in Figure 584.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
2.
Select the Project and Offline database to which the objects from the target
database need to be imported, as shown in Figure 585.
Filters can be applied to select the objects that are displayed as available for
import. When there are a large number of objects in the schema, you should apply
filters.
In the Object Picker, shown in Figure 586, you can:
Enter characters in the Name Filter to filter the list of available objects by
name. The Name Filter is case sensitive.
58-19
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
When there are a large number of objects, you can turn off Auto-Query and
click Query when you have entered the filter you want to use.
Select the object types you want to view.
3.
4.
Click Finish to import the selected objects to the specified offline database.
Standalone deployment program that can be invoked from the command line.
58.2.9.1.1 How to Use the Database Object Deployment Wizard in JDeveloper To start the
deployment wizard in JDeveloper, you need to choose APPS: Deploy DB Object from
the context menu on the offline object definition in the Application Navigator.
This can be used to deploy an offline database to a target online database. These
options are available for deployment:
Deploying a single database object file. Only one item is selected, as shown in
Figure 587.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Deploying multiple database object files (Bulk Deployment). Several items are
selected, as shown in Figure 588.
58-21
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Deploying offline schema object (and thereby deploying the entire designed data
model), as shown in Figure 589.
The Generate Fusion Applications Objects wizard will prompt for the following
information:
Database Connection: The target database connection name can be selected from
the list of all defined database connections, or a new connection can be created, as
shown in Figure 5810.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Figure 5810
Deployment Parameters. Figure 5811 shows how the dialog appears for single
database deployment parameters.
Figure 5811
Figure 5812 shows how the Deployment Parameters dialog appears for multiple
database deployment parameters.
58-23
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Figure 5812
Owner User: Oracle schema name in which the object exists or should be
created.
Log File Path: Specify a logfile name if it has to be written to a log file. By
default, the log will be displayed in the JDeveloper log window.
For Single Database Object deployment, this is optional. For bulk Database
Object and schema deployment, it is mandatory to provide a directory for
saving log files.
Log File Format: The format of the log file. Permitted values are text (the
default) or xml.
Debug Level: The Debug level controls the level of detail to be captured in the
log. Debug Level=3 will show the most information. Permitted values are 0
(the default), 1, 2 or 3.
Stand Alone: If this option is selected, the XDF comparison utility will execute
in a standalone mode. This mode does not have any applications
dependencies and it creates database objects without applications standards
for physical attributes such as TABLESPACE/STORAGE; the database
defaults are used.
Change Database: This option indicates whether the deployment should just
report or execute the necessary Alter DDLs, based on comparison of the offline
Database object definition against target database. If unchecked, the
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
deployment will report on the differences but will not actually apply the
changes to the database.
58.2.9.1.2 How to Use the Database Object Deployment Command Line Interface Use this
command and parameters shown in Example 581 to deploy a database object from
the command line.
Example 581
Mandatory Arguments
owner_un: Oracle schema name in which the object exists or should be created.
Note that in the consolidated fusion schema model, owner_un will be the same as
apps_un. These parameters are maintained for cases where they could be different.
Password Arguments
The command line deployment tool will prompt to get the database password from
the user in an interactive mode. The password cannot be a parameter, because it is
against Security guidelines. If you have a script in which you are invoking schema
deployment, you can pipe the password in the script, such as:
$JDEV_JAVA_HOME/bin/java oracle.apps.fnd.applxdf.comp.XdfSchemaDeploy owner_
un=$FUSION_SCH apps_un=$FUSION_SCH jdbc_protocol=thin jdbc_db_addr=$JDBC_ADDR
changedb=y logfileformat=text xdf_file_name=$xdfFile xdf_mode=$xdf_mode
logfile=$logfile <<! $FUSION_PASS
Optional Parameters
xdf_xsl_dir: The XSL directory, which contains all the XSL files required for XSLT
transformation. This parameter is optional and is automatically determined in
most cases if the JAR file format of deploying Java class files is being used. This
parameter is maintained for flexibility, in case the format for deploying Java files
becomes similar to what existed in previous versions.
standalone: This option is used to execute the XDF comparison utility in a
standalone mode. Permitted values are y, Y, n or N. The default value is n.
Standalone=y does not have any applications dependency. This mode creates
database objects without applications standards for physical attributes such as
58-25
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
TABLESPACE/STORAGE and uses the database defaults. It also does not update
applications metadata.
changeDb: The default is "y." If changedb is specified as "n," the SQL statements
generated by the XDF comparison utility are not executed but are displayed on the
standard output or a log file.
logfileformat: The format of the log file. Permitted values are text or xml. If
logfileformat is not set, the default is text.
logfile: The output of the comparison utility is written to standard out. Specify a
logfile name if it has to be written to a log file. If logfile is not set, the outputs will
be displayed on the screen.
debuglevel: Debug levels determine how much information is to be shown in the
log. Debuglevel=3 will show the most information. Permitted values are 0, 1, 2 or
3. The default value is 0.
from_jdev: This parameter is set to "y" when the XDF comparison utility is called
from JDeveloper. The default value is "n."
force_mode: The force deployment mode introduces an additional input
parameter that when specified will drop any additional column, index or
constraints that are present in a target database. The applications metadata stored
for the object is also updated to be in sync with the new definition.
index_category: Values are small, large, and both. If the table is partitioned, the
index is always created. If the table is not partitioned, there is no index creation if
one of these conditions is true:
xmlparserv2.jar
ojdbc6.jar
orai18n.jar
oracle.apps.fnd.applxdf.jar
Example 582 shows the set of commands to set the CLASSPATH.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Example 582
The JDeveloper installation directory could potentially change with newer versions of
JDeveloper being available. Check the JDeveloper installation directory to make sure
that it exists. You could also use the XML parser and JDBC driver that comes with the
database. Note that so far XDF has been tested with the same JAR files with which it
has been compiled. It should not be a problem setting the CLASSPATH with a higher
version of these JAR files and testing them. If you encounter any issues, try using 11g
JDBC and xmlparsers.
Option 1
58-27
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Product teams can specify an RDBMS default value for the column. This
default value will be used by schema deployment utility to update the existing
null rows with that value before changing the column to not null.
Option 2
If a product team does not want to use a RDBMS default value, it can add or
modify a column as a not-null column to an existing table by using a script having
a more complex logic. The column needs to exist in the target database before the
script is run. The script cannot enforce the not-null constraint because it is against
the standards to have DDL in scripts.
To use a script to populate the column, the UDP named runTwice must be set to
Yes. This UDP will be used by XDF to ensure that the required patch metadata is
present in XDF to run it twice in a patch. In the first run, the script will not error
out if it is not able to enforce the not-null constraint, but it will error out in the
second run if it still is not able to enforce the not-null constraint.
If the user does not set this UDP, the default behavior of the deployment utility is
to error out if it is not able to enforce the not-null constraint while adding or
modifying the column.
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Columns, obsolete. Doing this may make a significant effect to existing customizations
or extensions currently implemented on the system. Making obsolete database objects
that contain data, such as Tables, requires particularly close analysis for potential
effects. Development teams should take the necessary steps to review and understand
the implications of such updates in these areas.
Making obsolete certain database objects or certain attributes of a database object may
require those objects to be dropped as part of clean up. Considering any existing
customization or extensions to such objects, the act of making obsolete and dropping
the object should be kept separate. Dropping the obsolete database objects or columns
should be an optional step that is invoked at the demand of customers. The Patching
(AD) utilities will provide such an option as a post-patching step.
Follow these steps to make obsolete a database object or attribute.
1.
Set Status User Defined Property for the specific database objects or attributes to
Obsolete. This can be done using User Defined Properties for Applications specific
metadata that is part of the offline database model.
2.
If the table does not already exist in the database, the Applications schema
deployment utilities (XDF) will create the table without columns marked as
obsolete.
If the column does not already exist in the table, the Applications schema
deployment utilities (XDF) will not add the column to the table.
If the column already exists in the table, the Applications schema deployment
utilities (XDF) will remove any NOT NULL, PK/FK constraints on the column.
Any indexes that comprise only the obsolete columns could be dropped. In other
cases, the development team owning the obsolete objects will be expected to
update the definition of any affected indexes.
58.2.9.5.2 How to Use the Force Mode Option in Schema Deployment During the initial
development of the product before release, product teams may not want to mark the
object as obsolete and may prefer directly dropping the object; that is, removing the
definition from the offline database file. To support this, the force_mode=y parameter
can be passed to the schema deployment tool. The additional input parameter which,
when specified, will drop any additional column, index or constraints that are present
in a target database and not present in the offline object file definition. The XDF
dictionary metadata stored for the object is also updated to be synchronized with the
new definition. Note that this option, in certain cases, will not change the definition of
the table to exactly match the definition in the file. For example, if the database does
not allow some changes, such as changing of certain column datatype, or changing an
unpartitioned table to a partitioned table, force mode will not override the database.
Force mode only handles the removal of column, index and constraints, and
synchronizing the corresponding definition in the XDF dictionary. If the primary
object, such as a table, sequence or view, is dropped, the fnd_cleanup_pkg must be
used to synchronize the XDF dictionary.
58.2.9.5.3 How to Use fnd_cleanup_pkg and fnd_drop_obsolete_objects Use fnd_cleanup_
pkg and fnd_drop_obsolete_objects to clean a database.
58-29
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Using fnd_cleanup_pkg
Procedure fndcleanup(name): Remove table, sequence, or view with name that is in
fnd_tables, fnd_views or fnd_sequences tables, but not in the database. All the
required XDF dictionary tables will be updated when fnd_tables, fnd_views, or fnd_
sequences is updated.
name: Optional, but using fnd_cleanup_pkg.fndcleanup without the name parameter
may cause some issues. You should use fndcleanup(object name) for a clean and safe
removal. This can be a table name, a view name or a sequence name. If a name is
provided, the procedure will clean only the named object and related components. If it
is not defined, the fndcleanup procedure removes all table, view, or sequences that are
in fnd_tables, fnd_views, or fnd_sequence tables, but that do not exist in the
database.
It also removes the entries that refer to that name object in all related database schema
deployment (xdf) dictionary tables, including fnd_columns, fnd_indexes, fnd_
primary_keys, fnd_primary_key_columns, fnd_foreign_keys, fnd_foreign_key_
columns, and fnd_histogram_cols.
Procedure clean_fndcons(tbname): Remove the tbname table's Primary Key (PK),
Unique Keys (UKs), and Foreign Keys (FKs) that are not in the database from the fnd
constraint dictionary tables. Although the tbname parameter is optional, you should use
it. If tbname is not specified, then all tables' PK, UKs, and FKs that are not in the
database will be removed from the fnd constraint tables.
Procedure TableFndCleanUp(tbname, deleteType, delname): Remove the specified
deleteType with the specified delname on the specified tbname table from related fnd
tables. Although the delname parameter is optional, you should include it. If it is not
specified, all table properties on that deleteType will be removed from the specified
table. The deleteType includes column, index, pkuk, and fk.
Examples
Remove table1 from the fnd_tables table if table1 is not in the database. All
required XDF dictionary tables will be updated when fnd_tables is updated.
execute fnd_cleanup_pkg.fndcleanup('table1')
Remove view1 from the fnd_views table if view1 is not in the database.
execute fnd_cleanup_pkg.fndcleanup('view1')
Remove all table names LIKE HZ% in fnd_tables or fnd_views tables that do not
exist in the database.
execute fnd_cleanup_pkg.fndcleanup('HZ%')
Remove table XF1's PK, UKs, and FKs that are not in the database, from the fnd
constraint dictionary tables.
exec fnd_cleanup_pkg.clean_fndcons('XF1');
Remove a Foreign Key named XF2_T1_FK on table XF2 from the fnd constraint
dictionary tables. XF2_T1_FK may or may not be in the database.
exec fnd_cleanup_pkg.tablefndcleanup('XF2', 'fk', 'XF2_T1_FK');
fnd_drop_obsolete_objects
Procedure drop_object(objectname): Drop obsolete objectname from the database.
This procedure is used to delete obsolete views, tables and columns that are marked as
Obsolete in the table.
Examples
58-30 Developer's Guide
Implementing Applications Data Modeling and Deployment JDeveloper Extensions (Data Modeling Extensions)
Drop Table table1 from the database if it is marked as obsolete. If table1 is not
obsolete, drop any columns in table1 that are obsolete.
execute fnd_drop_obsolete_objects.drop_object(table1)
Verify all tables and views with name like 'HZ_%" for dropping tables and views,
or drop columns if the tables are not obsolete.
execute fnd_drop_obsolete_objects.drop_object('HZ_%')
58.2.9.5.4 Frequently Asked Questions Use this information when dropping an object in
the database.
2.
3.
What happens when you deploy an obsolete object or an object that has obsolete
columns or indexes?
Only the FND dictionary is updated. Objects in the database are not dropped.
How do I remove an object from the database and keep the FND data dictionary
synchronized?
There are three ways this can be done. SQL scripts can be used to achieve the same
outcome.
If the object is not a primary object and is a column, index or constraint that is
being dropped:
Use the force_mode optional parameter to deploy the object to the target
database.
Change the object obj status UDP to Obsolete from JDeveloper. Deploy the
object to the database either by command line (XdfSchemaDeploy) or use
Generate Fusion Applications Objects from JDeveloper.
How do I clean up the FND data dictionary if many objects are no longer in the
database?
Execute this command from sqlplus or use a SQL script.
Using the Database Schema Deployment Framework
58-31
execute fnd_cleanup_pkg.fndcleanup
How do I clean up the FND data dictionary if I had deleted columns and indexes
from table, but did not cleanup from the FND data dictionary.
Execute this command from sqlplus or use a SQL script.
execute fnd_cleanup_pkg.fndcleanup
UDP Name
Description
Values
Insert Allowed
Y/N Default Y
Update Allowed
Delete Allowed
Y/N Default Y
Select Allowed
Y/N Default Y
Table 5810
UDP Name
Description
Values
Truncate Allowed
Y/N Default Y
Maintain Partition
Y/N Default Y
Exchange Partitions
Y/N Default Y
The value of this UDP
indicates whether it is possible
to exchange partitions on the
table. The ADM_DDL
program when handling
requests for dynamic DDL
operations uses this
information.
Maintain Index
Y/N Default Y
The value of this UDP
indicates whether it is possible
to maintain indexes on the
table. The ADM_DDL
program when handling
requests for dynamic DDL
operations uses this
information.
Table 5811
UDP Name
Description
Values
Insert Allowed
Y/N Default Y
Update Allowed
Delete Allowed
Y/N Default Y
Select Allowed
Y/N Default Y
Table 5812
UDP Name
Description
Values
Select Allowed
Y/N Default Y
Reset Sequence
Y/N Default Y
The value of this UDP
indicates if the sequence can
be reset to a specific value.
The ADM_DDL program
when handling requests for
dynamic DDL operations uses
this information.
58-33
Table 5813
UDP Name
Description
Values
Select Allowed
Y/N Default Y
59
Improving Performance
59
This chapter provides guidelines for you to write high-performing, highly scalable,
and reliable applications on Oracle Fusion Middleware.
This chapter includes the following sections:
Section 59.4, "SOA Guidelines for Human Workflow and Approval Management
Extensions"
You override the DML (PL/SQL entity objects are in this category).
You have one or more streaming attributes, such as character large object (CLOB)
or binary large object (BLOB).
One or more attributes are marked as retrieve-on-insert or retrieve on-update.
For more information, see the "Batch Processing" section in the Oracle Fusion
Middleware Performance and Tuning Guide.
59.2.1.2 Children Entity Objects in Composite Entity Associations Should not set
the Foreign Key Attribute Values of the Parent
Children entity objects can expect that their parent primary key attribute values are
passed through the attributeList parameter in create(attributeList) and ADF
Business Components calls super.create(attributeList) to populate these foreign
key attribute values. Repopulating the foreign key attribute values in the children
entity object unnecessarily decreases performance.
The same principle applies for view accessor rowsets. If your view accessor returns
more than one row, then every time you start fetching rows from the view accessor
with a different bind value, a new row set is created, along with a new underlying
database cursor to execute the query. If you do not need all the rows, then you should
configure the MaxFetchSize setting on the view accessor to include only the number of
rows you need. Then Oracle ADF closes the database cursor immediately upon
fetching all the rows up to MaxFetchSize. Alternatively, for cases where you expect to
execute the view accessor several times with different bind values, in a single request,
you should consider calling closeRowSet on the view accessor rowset explicitly.
Your entity object is Multi-Language Support (MLS)-enabled and has more than
one translated attribute.
You have defaulting logic or multiple validators that need to access the same
association attribute.
Using the Retain Association Accessor RowSet option may adversely affect memory
usage since it postpones when the retained rowset becomes garbage collectible. Before
you enable this option, (as shown in the following figure), you should profile your
flow to make sure you would indeed get a noticeable benefit.
Figure 592 Entity Object Editor Tuning: Retain Association Accessor RowSet
If you see the top CPU consumers (sort by exclusive CPU) are related to code that
loops through the rowsets, then you would likely get a benefit by using this option. An
example where you may want to consider using the Retain Association Accessor
RowSet option is if you profile your code and see that
oracle.jbo.server.ViewObjectImpl.addRowSet is using a lot of CPU, and most of the
CPU is in a call stack that includes AssociationDefImpl.get. The following figure
illustrates an example profiler output showing addRowSet being expensive.
Figure 593 Profiler Output Example
Before you decide to retain association accessor, you should try the guideline
Section 59.2.1.5, "Close Unused RowSets."
If you decide to use the Retain Association Accessor RowSet option, you should be
aware of the potential behavior changes. For more information, see the Advanced Entity
Association Techniques section in the "Advanced Entity Object Techniques" chapter of
the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
You should capture the SQLs the view object is generating, with relevant view criteria
applied, by enabling Java Business Objects (JBO) debug logging. (For expert-mode
view objects, you should capture the SQL that you are providing). You should also
generate explain plans against a volume database to ensure performance is optimal
and the correct indexes are in place.
If you must use hints to get a desirable execution plan for your query, set the Query
Optimizer Hint field in the View Object Editor - Tuning section as shown in the
following figure.
Figure 594 View Object Editor Tuning
For user interface (UI) driven queries, the FIRST_ROWS(10) hint is necessary to instruct
the optimizer to pick a plan that is optimized to return the first set of rows. Set this
hint for view objects that are used for UI components, which typically just display the
initial set of rows (such as table). If you are fetching all the rows, then do not use the
FIRST_ROWS hint.
If you have a view object that is used in both query and insert, then you should call
setMaxFetchSize(0) programmatically when you know it is being used in insert
mode. In this case, you need to unset it when using it in query mode. You cannot set
the No Rows option because the same view object is used in both insert and query
mode in the same application module.
For view objects used for the List of Values (LOV) combo box, the number of rows
fetched by Oracle ADF is controlled by the ListRangeSize setting in the LOV
definition. The default value is 10 and a fetch size of 11 is appropriate. You should
modify the value to 11.
For LOV text output, Oracle ADF fetches about 31 rows in the LOV search results
window. To simplify retrieval, a fetch size of 11 is acceptable, to make it the same fetch
size as the view object used in the LOV combo box. In this case, the data comes back in
three round-trips which is also acceptable.
ADF Business Components only recognizes fetch size if the
SQL flavor is Oracle, which is what you should be using.
Note:
Fetch size can be set based on the usage of the view object. This is the appropriate
place to set the fetch size for view objects that are used in different scenarios and the
fetch size cannot be pre-determined when the view object is created. You can edit the
setting per view object usage by selecting the view object in the Data Model panel of
the Application Module editor, clicking Edit, and then selecting the Tuning panel.
Fetch size can also be set at the view accessor level. This is typically used by teams
consuming public view objects from other teams, such as for LOVs. The producer team
would likely not set a fetch size since they cannot anticipate how their public view
object would be used. For more information, see the "Working with List of Values
(LOV) in View Object Attributes" section in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
59.2.2.5 Include at Least One Required or Selectively Required View Criteria Item
When creating view criteria, include at least one view criteria item that is required or
selectively required, to use a database index and avoid a full table scan. Otherwise, the
SQL generated will be of the form:
((MyTableColumn_name = :bvOrgId) OR (:bvOrgId IS NULL))
"Configuring View Object Data Fetching" section in the Oracle Fusion Middleware
Performance and Tuning Guide.
The setForwardOnly API is actually defined on the RowSet interface, which
ViewObjectImpl implements, so you can use it on secondary rowsets that you create
via ViewObjectImpl.createRowSet(String name) as well.
Note:
For those attributes that do not need to be part of the key, deselect the Key Attribute
option in the View Object Attribute Editor. However, ensure that you include
sufficient attributes. If your view object is updateable, comply with
File.AdfModel.112.
For more information, see the "Optimize large data sets" row in the "Additional View
Object Configurations" table in the Oracle Fusion Middleware Performance and Tuning
Guide.
Note:
When you call an association accessor, an internal view object is created. If you insert
or update via the association accessor, you can call setListenToEntityEvents(false)
for the internal view object by casting it to a RowSet as shown in the following
example.
Example 591
Use setListenToEntityEvents(false)
If you must use the generic getAttribute or setAttribute, consider using the index
instead of the name for a small performance gain. It may be more troublesome to
maintain the numeric attribute indexes, but for cases where you are looping through a
large number of attributes, you should consider using getAttribute(int index) and
setAttribute(int index).
when you are programmatically inserting rows and the reference entity object
attributes do not need to be shown.
59.2.2.18 Do Not Use the "All at Once" Fetch Mode in View Objects
If you select the "All at Once" view object fetch mode, the view object query returns all
rows, even though you are looking at only the first row. Depending on the query, this
could cause OutOfMemory errors as the result of too many rows being fetched. Use
the default "As Needed" fetch mode instead.
59.2.2.19 Do Not Use the "Query List Automatically" List of Value Setting
If you use the "Query List Automatically" option in the UI hints panel in the edit LOV
screen, a query is executed by default, which could be expensive. This setting impacts
only whether a search is executed by default when the LOV search list displays. For
LOV combo boxes, regardless of this setting, the smart filter executes when the LOV
combo is clicked and the dropdown list displays.
Application module state management and application module pooling are very
important features provided out of the box by Oracle ADF. The combination of
application module state management and pooling makes ADF Business Components
based web application more scalable by multiplexing application module instances in
pool to serve large volume concurrent HTTP user sessions, and more reliable (failover)
by serializing pending user session state into persistent storage (Database or File
system).
Passivation is the process of serializing current states of an active application module
instance to persist it to make it passive. Activation is its reverse process to activate a
passive application module instance.
After coding and debugging all functional issues of an ADF Business Components
based application, it is necessary to disable application module pooling to test and
verify the application code is passivation-safe. Disabling application module pooling
enforces the application module instance to be released at the end of each request and
be immediately removed (destructed), and passivation is triggered before its removal.
On subsequent requests made by the same user session, a new application module
instance must be created to handle this user request. A pending state must be restored
from the passivation storage to activate this application module instance.
To disable application pooling for all application module pools, add
-Djbo.ampool.doampooling=false to the JVM options when you run your page. You
can also disable application pooling for select application modules.
To disable application pooling for select application modules:
1. Launch Oracle JDeveloper.
2.
3.
Click Edit, and select the Pooling and Scalability tab, as depicted in the following
figure.
4.
For more information about application module state management, see the
"Application State Management" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
For more information about application module pooling, see the "Tuning Application
Module Pools and Connection Pools" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
To disable passivation for a subset of view objects' transient values, deselect Include
All Transient Values in the View Object Editor - Tuning section as shown in
Figure 598. Then check the Passivate check box only for the attributes that require
passivation in the view object attribute editor.
For more information, see "Managing the State of View Objects" in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
User session state cached in Application Session UserData hash table. Go through:
ApplicationModule.getDBTransaction().getSession().getUserData()
Caution: This is not the user session. This is the Application Module
session that ties to an application module and is maintained by ADF
Business Components.
The following is sample code from the Pathfinder Application to passivate and
activate the UserLoginPrincipal object. The following example shows one way that
you can passivate custom state.
Note: XML documents can only handle String. Therefore, an object
must be serialized before saving.
Example 592
//
catch (IOException e)
{}
catch (ClassNotFoundException e)
{}
getSession().getUserData().put(Constants.LOGIN_
PRINCIPAL,principal);
break;
}
}
}
}
}
Caution:
Setting the release level to Reserved makes Data Control "sticky" to an application
module instance and all requests from the same HTTPSession associated with this Data
Control are served by the same application module instance. This is contrary to the
initiative of introducing application module state management and application
module pooling, so using this release level is strongly discouraged.
When the release level is changed to Reserved by calling
DCJboDataControl::setReleaseLevel() with input argument
ApplicationModule.RELEASE_LEVEL_RESERVED, it stays at this level
until explicitly changed.
Caution:
Table 591
Release Mode
Unmanaged (Stateless)
Managed (Stateful)
Reserved
Application
Module
Behavior
Preserves the
application module
instance's state in the
database between
page-processing
requests. This permits
the application to
maintain a user's data
without involving a
single application
module instance for
long periods of time.
Allocates the
application
module instance
for the duration of
the browser
session. The
instance is released
only at the end of
the session. This
mode is provided
primarily for
compatibility with
certain application
module
definitions.
Failover is not
supported in this
mode.
DBTransaction
& User Action
Note: Reserved
mode is primarily
useful when the
application
module requires a
non-standard
JDBC connection
definition. Failover
is not supported in
this mode.
Oracle ADF
automatically
posts any changes
to the database
(and initiates
DML-specified
database triggers
on the effected
tables). In this
mode, the user is
expected to click
either the Commit
button or Rollback
button in the
process JSP page.
Because the
application
module itself is not
released for the
duration of the
HTTP session, the
user can initiate
the Commit or
Rollback at any
point.
Unmanaged (Stateless)
Managed (Stateful)
Reserved
Application
Module Locking
Behavior
In stateless mode, it is
recommended that the
Business Components
property
jbo.locking.mode should
be set to optimistic.
Pessimistic locking is not
compatible with stateless
mode because the
database transaction is
always rolled back to
allow the connection to be
reused by another user.
This results in the lock
being released and makes
pessimistic locking
unusable.
In stateful mode, it is
recommended that the
Business Components
property
jbo.locking.mode
should be set to
optimistic. Pessimistic
locking is not
compatible with
stateful mode because
after the application
module is preserved,
the database
transaction is rolled
back to allow the
connection to be
reused by another
user. This results in the
lock being released
and makes pessimistic
locking unusable.
In release mode,
you can reliably
use pessimistic
locking and may
set the property
jbo.locking.mode
to pessimistic.
For more information about application module release level and state management,
see the "Application State Management" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
59.2.4.1 Set the Find Criteria to Fetch Only Attributes that are Needed
By default, when you call the find service, the child service data objects are also
fetched. If you do not need those children, then make sure you set the find criteria to
fetch only the attributes you need.
The following example is sample code showing how to create a find criteria.
Example 593
FindCriteria fc = (FindCriteria)DataFactory.INSTANCE.create(FindCriteria.class);
//create the view criteria item
List value = new ArrayList();
value.add(new integer(10));
ViewCriteriaItem vci =
(ViewCriteriaItem)DataFactory.INSTANVCE.create(ViewCriteraItem.class);
vci.setValue(value);
vci.setAttribute("Deptno");
List<ViewCriteriaItem> items = new ArrayList(1);
items.add(vci);
//create view criteria row
ViewCriteriaRow vcr =
(ViewCriteriaRow)DataFactory.INSTANCE.create(ViewCriteriaRow.class);
vcr.setItem(items);
//create the view criteria
List group = new ArrayList();
group.add(vcr);
ViewCriteria vc = (ViewCriteria)DataFactory.INSTANCE.create(ViewCriteria.class);
vc.setGroup(group);
//set filter
fc.setFilter(vc);
List cfcl = new ArrayList();
ChildFindCriteria cfc =
(ChildFindCriteria)DataFactory.INSTANCE.create(ChildFindCriteria.class);
cfc.setChildAttrName("Emp");
cfc.setFetchStart(1);
cfc.setFetchSize(1);
cfcl.add(cfc);
fc.setChildFindCriteria(cfcl);
DeptResult dres = svc.fndDept(fc, null);
pw.println("### Dept 10 and 2nd Emp ###");
.......
59.2.4.4 Set Only Changed Columns on Service Data Objects for Update
When creating a list of service data objects to pass for update using the processXXX()
method, if possible, set only the columns that you really need to change. Service data
objects with fewer attributes that have been set are updated faster than service data
objects with all the attributes set.
Note:
select the value ifNeeded for the Refresh property, the iterator or action may get
refreshed twice and therefore impact performance. The following figure shows how
the JavaServer Faces (JSF) and Oracle ADF phases integrate in the lifecycle of a page
request.
Figure 599 Lifecycle of a Page Request in an Oracle Fusion Web Application
In particular, the value always should not be used as the Refresh property for
invokeAction bindings. Using ifNeeded is the best option for most cases. Note that if
invokeAaction binds to the methodAction, which does not accept any parameters, or
to any action then it will fire twice per request. To avoid this situation, use the
RefreshCondition attribute on invokeAction to control when the action needs to fire.
For more information about the Refresh property, see the What You May Need to Know
About Using the Refresh Property Correctly section in the "Understanding the Fusion
Page Lifecycle" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
((HttpServletRequest)
(FacesContext.getCurrentInstance().getExternalContext().getRequest())))
.getSession().setAttribute("UserLoginPrincipal",sessionLoginPrincipal);
To achieve the best performance, do not set the client component property to true.
some cases where using Isolated is functionally necessary. For more information, see
the "Sharing Data Controls Between Task Flows" section in the Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
If you use the same taskflow multiple times on a page, and you are using shared data
control scope, by default it may not work because the data controls will show the same
data. To address this, instead of switching to isolated data control scope, follow the
approach described in
https://blogs.oracle.com/groundside/entry/maintaining_row_
currency_separation_in.
59.3.1.17 Select the No Save Point Option on a Task Flow when Appropriate
Select the No Save Point option if you do not need the functionality to roll back
changes at the end of the task flow. If you do not use this option, the model state is
passivate at the beginning of the task flow, which is expensive.
59.3.1.19 Avoid Unnecessary Task Flow Activation for Regions Under Popups
By default, task flows that use a region under popups are activated when the page
loads, not when the popup displays. This causes unnecessary memory and CPU usage
if the user does not use the popup. There are two approaches for activating the task
flow region only when the popup displays:
1.
2.
Set the activation property on the task flow binding to "conditional" and specify a
condition in the "active" to an EL expression that returns true when the popup
displays. Usually this requires creating a view scope variable that is set using a
setPropertyListener executed on popupFetch. The EL expression must return
true if the popup is displayed. (A request scope variable will not work in most
cases unless you cannot submit any server requests from the popup.)
Approach (1) is simpler but you must use approach (2) for these cases:
Any of the following tags are present inside the popup attribute:
f:attribute
af:setPropertyListener
af:clientListener
af:serverListener
You need to refer to any child components of the popup before the popup is
displayed. Setting childCreation="deferred" postpones the creation of any child
components of the popup and you cannot refer to them until after the popup
displays.
Any of the following tags are present inside the popup attribute:
f:attribute
af:setPropertyListener
af:clientListener
af:serverListener
You need to refer to any child components of the popup before the popup is
displayed. Setting childCreation="deferred" postpones the creation of any child
components of the popup and you cannot refer to them until after the popup
displays.
59.3.1.21 Avoid Unnecessary Task Flow Activation for Regions Under Switchers
By default, task flows that use an af:region under switchers are activated regardless
of whether the facet displays. This causes unnecessary memory and CPU usage for the
facets that do not display. To activate the task flow region only when it displays, set
the "activation" property on the task flow binding to "conditional", under the
Executables section in the page definition file. Also specify a condition in the "active"
to an EL expression that returns true when the facet displays.
Typically, you may already have an EL expression to control the return value for the
facetName property in the switcher. For example, if your switcher looks like this:
<af:switcher id="s1" defaultFacet="1" facetName="#{pageFlowScope.facet}">
<f:facet name="1">
<af:region value="#{bindings.TF1.regionModel}" id="r1"/>
</f:facet>
<f:facet name="2">
<af:region value="#{bindings.TF2.regionModel}" id="r2"/>
</f:facet>
</af:switcher>
The associated binding should have activation set to "conditional", and active set to an
EL, as follows:
<taskFlow id="tTF1" taskFlowId="<some task flow>"
active="#{pageFlowScope.facet=='1'}" activation="conditional"
xmlns="http://xmlns.oracle.com/adf/controller/binding"/>
<taskFlow id="tTF2" taskFlowId="<some other task flow>"
active="#{pageFlowScope.facet=='2'}" activation="conditional"
xmlns="http://xmlns.oracle.com/adf/controller/binding"/>
59.3.1.22 Avoid Unnecessary Root Application Module Creation from UI-layer Code
Creating additional root application modules is expensive when you can reuse the root
application module that is associated with the data bindings on your page. For
59.3.1.27 Delay Activation of Taskflow Regions That are not Always Rendered
If the parent component of a taskflow region has an EL expression on the rendered
property, set the activation property of the taskflow executable in the page definition
to "conditional". Set the active property to the same EL expression as the one that
controls the rendered property. This setup avoids activating the taskflow unless the
region is actually rendered.
This is optimized to first find the profile value in an internal cache, so it checks out an
application module only if needed. Avoid calling ProfileServiceAM.getInstance as it
checks out a ProfileService application module instance, which is expensive.
or:
<taskFlow id="attachmentRepositoryBrowseTaskFlow1"
taskFlowId="/WEB-INF/oracle/apps/fnd/applcore/attachments/ui/attachments-docpicker
-taskflow.xml"
This task flow is unnecessarily activated. To avoid this situation, navigate to the
bindings tab of the page where the Attachments component was added. Select
attachments task flow, attachmentRepositoryBrowseTaskFlow1, from the list of
Executables. Set the following attributes in the property inspector under Common:
activation="conditional"
active="#{pageFlowScope.FND_ATTACHMENTS_LOAD_TF==true}"
59.5.5 Set the Data Control Scope to Isolated for Page Level Item Nodes
If the data control scope is shared for taskflows pointed to by certain item nodes, then
the life span of these taskflow data controls is tied to the parent, which is either Main
TF or Regional TF in the UI shell. This scenario applies to those item nodes with
taskType equal to "defaultMain", "dynamicMain", or "defaultRegional". This means
that DC frame is not removed for the duration of the session, regardless of any
navigation or closing tab. This is because the Main TF and Regional TF in the UI shell
have the DC scope set to shared, due to the requirement to share CE between the
regional and main areas.
If there is no requirement to share transactional data between the regional and main
areas, then set dataControlScope="isolated" on the page level item node in the menu
file. This recommendation assumes that the underlying taskflows used in the regional
area or the task menu already have data control scope set to isolated. Note that you
should not change the data control scope on the taskflow itself.
59.6.1.1 Use StringBuilder Rather than the String Concatenation Operator (+)
When doing String concatenations inside a loop, see if the operation can be moved
outside of the loop. Frequently, the concatenation code is put inside the loop even
though the value can never change there.
The String concatenation operator + involves the following:
This increases cost in both space and time, especially if you're appending more than
one String. You should consider using a StringBuilder directly instead.
StringBuilder was introduced in Java Development Kit (JDK) 1.5 and is more
efficient than StringBuffer since the methods are not synchronized. When using
StringBuilder (or StringBuffer), optimally size the StringBuilder instance based on
the expected length of the elements you are appending to it. The default size of a
StringBuilder is 16. When its capacity is exceeded, the JVM has to resize the
StringBuilder which is expensive. For example, instead of:
String key = granteeType + ":" + granteeKey;
This way, the StringBuilder object is initialized with the correct capacity so it can
hold all the appended strings it needs to resize its internal storage structure.
59-28 Developer's Guide
For the sake of simplicity, it is acceptable to do String concatenation using "+" for
debug log messages, if you follow the logging standard and check log level before
constructing the log message.
Avoid unnecessary use of String.substring calls since it creates new String objects.
For example, instead of doing this:
if (formattedNumericValue.substring(0,1).equals("-")) negValue = true;
Do this instead:
if (formattedNumericValue.charAt(0) == '-') negValue = true;
The hashCode method is another common place where you do String concatenation.
The following example uses the hashCode implementation and requires String
concatenation on every call.
Example 596
Note:
Plan carefully before deciding to concatenate Strings. There are often alternative ways
to implement the intended logic without concatenation.
Legacy collections (like Vector and Hashtable) are synchronized, whereas new
collections (like ArrayList and HashMap) are unsynchronized, and must be wrapped
via Collections.SynchronizedList or Collections.synchronizedMap if
synchronization is desired. Do not use synchronized classes collections, including
collections from java.util.concurrent package, that are not shared among
threads.
Do not use object collections for primitive data types. Use custom collection
classes instead.
Size a collection based on the number of elements it is intended to hold to avoid
frequent reallocations and rehashing in case of hashtables or hashmaps.
For more information about Collections, see "Configuring Garbage Collection" in the
Oracle Fusion Middleware Performance and Tuning Guide.
Read-only objects
Minimize the size of the synchronized block of code. For example, instead of
synchronizing the entire method, it may be possible to synchronize only part of the
method.
In JDK 1.5, there is a new package, java.util.concurrent, that contains many classes
designed to reduce contention. For example,
java.util.concurrent.ConcurrentHashMap provides efficient read access while still
maintaining synchronized write access. These new classes should be evaluated instead
of simply using a Hashtable whenever synchronization is required.
The following example shows how the compiled code basically creates a new Integer
object based on the int value:
Example 598
Compiled Code
8: bipush 100
10: invokestatic #2;
//Method
java/lang/Integer.valueOf:(I)Ljava/lang/Integer;
13: astore_2
If this piece of code is called repeatedly, then each call creates one Integer object and
could have adverse performance impact.
59.6.4.4 Avoid Repeated Calls to the same APIs that have Non-Trivial Costs
Avoided repeated calls to the same APIs that have non-trivial costs. Use a local
variable to hold the result instead. For example, instead of:
if (methodA() >= 0)
return methodA() + methodB();
Use:
int res = methodA();
If (res >= 0)
return res + methodB();
" :5);"+
" END;";
setGrant = txn.createCallableStatement(s1,1);
setGrant.setInt(1,v);
setGrant.setString(2,guid);
setGrant.setDate(3,sd);
setGrant.setDate(4,edt);
setGrant.registerOutParameter(5,Types.VARCHAR);
setGrant.execute();
if (rs.next())
{
ret = getAppsCtxtFileInfoFromResultSet(rs);
}
rs.close();
}catch(SQLException e)
{
Logger.println(e,Logger.DEV_LEVEL);
if (update)
{
if (e.getErrorCode()== ROW_LOCKED_ERROR_CODE )
throw new RowLockedException();
}
else
throw e;
}
return ret;
}
Caching Data
In this case, the result set is being closed via rs.close(). However, the statement
(stmt) has not been closed. For every statement opened, you should close it in the final
block of a try-catch, as shown in the following example.
Example 5911 Close Statement Example
try
{
...
<open the statement>
<process the statement>
...
}
catch
{
...
<process any exceptions>
...
}
finally
{
...
try
{
<close the statement>
}
catch
{
<process any exceptions>
}
...
}
Caching Data
mechanism for storing database results and other objects, such as in-memory ADF
Business Components objects for repeated usage. This minimizes expensive object
initializations and database round-trips, which ultimately results in improved
application performance.
Shared Objects: Data that is common across users is more appropriate than user
specific data.
Long-Lived: Data that is long-lived is more appropriate than short-lived data that is
valid only for a user request.
Expensive to Retrieve: Objects that take a long time to retrieve, such as objects that
are obtained from expensive SQL queries, are good candidates.
Expensive to Create: Objects that are frequently created or take a long time to create
are appropriate. Frequent creation can be avoided by caching the instances.
Frequent Use: Objects that have a high probability of being frequently used are
appropriate. Caching objects that are not actively used needlessly occupy JVM
memory.
Infrequently Changed: The cached data is invalidated and removed from cache
whenever it is changed, which makes caching frequently changed data more
costly.
Lookup codes are an example of data that meets most of the above criteria.
(Optional) Create commonly used view criteria for the shared view object.
3.
(Optional) Configure the shared view object's property, such as time to live, and so
on.
4.
Create one application module for each product that contains all the view objects
to store the cached data.
For information about how to create a shared application module, see the "Sharing
Application Module View Instances" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
5.
Cache a short list of data by pre-loading all the data into memory. This prevents
subsequent queries requiring additional database trips. To do this, generate the
Caching Data
VOImpl class for the shared view object and override the create() function of
VOImpl to fully populate the view object cache as shown in the following example.
Example 5912 Pre-load all Data into Memory
protected void create()
{
super.create();
setRangeSize(-1);
executeQuery();
getAllRowsInRange();
}
Note:
59.7.3.1 Creating ADF Business Components objects for shared MLS data
The procedure for creating ADF Business Components objects for shared MLS data
varies depending on where the shared data requirement exists. The steps you follow
are different for sharing data from the base table, from the translatable, or _TL, table or
from both the base and the _TL table.
59.7.3.1.1
How to create objects if only the data from the base table must be shared
1.
Create an entity object on top of the base table if you need the change notification
feature. This means that your data in cache is refreshed when there is a change in
the underlying table. This is required because the database change notification
feature doesn't work against database views.
2.
Create a view object on top of the _VL entity object if you do not require change
notification. Otherwise, create a view object on top of the entity object created
from the previous step
3.
Exclude all language dependent attributes from the _VL entity object.
59.7.3.1.2
1.
How to create objects if only the data from the _TL table must be shared
2.
3.
Create commonly used view criteria, with language being part of the criteria using
a bind variable.
Caching Data
Caution: The language must always be part of any view criteria. This
is very important.
59.7.3.1.3
shared
1.
How to create objects if both the data from the base table and the _TL table must be
2.
Create an entity object on top of the base table if you need the change notification
feature. This means that your data in cache is refreshed when there is a change in
the underlying table. This is required because the database change notification
feature does not work against database views.
If you do not need the change notification feature, then you can use the existing _
VL entity object, which should have been created already because it is required by
MLS Framework.
3.
Create a view object to join the entity object created in the previous step (either a _
VL entity object or an entity object based on the base table) and the _TL entity
object. The view object should have all the language dependent attributes from the
_VL entity object excluded, which allows the language dependent attribute to
always come from the _TL entity object.
Tip: This is important as it allows different users to see data for their
language.
4.
Create commonly used view criteria, with language being part of the criteria using
a bind variable.
Caution: The language must always be part of any view criteria. This
is very important.
59.7.3.2 Creating ADF Business Components Objects that Join to MLS tables
The procedure for creating ADF Business Components objects that join to MLS tables
varies depending on where the data requirement exists. The steps you follow are
different if the data is from the base table, from the translatable, or _TL, table, or from
both the base and the _TL table.
59.7.3.2.1
How to create objects if only the data from the base table is required
1.
Create an entity object on top of the base table if you need the change notification
feature. This means that your data in cache is refreshed when there is a change in
the underlying table. This is required because the database change notification
feature does not work against database views.
2.
Create a view object that joins to the _VL entity object if you do not need the
change notification feature, or create one that joins to the entity object created in
previous step if change notification feature is required.
3.
Exclude all the language dependent attributes from the _VL entity object.
59.7.3.2.2
1.
How to create objects if only data from the _TL table is required
Caching Data
2.
Create view criteria with language being part of the criteria using a bind variable.
Caution: The language must always be part of any view criteria. This
is very important.
59.7.3.2.3 How to create objects if data from both the base table and the _TL table is required
Create an entity object on top of the base table if you need the change notification
feature. This means that your data in cache is refreshed when there is a change in
the underlying table. This is required because the database change notification
feature does not work against database views.
1.
2.
Create a view object that joins to the _VL entity object or the entity object created in
the previous step, and the _TL entity object.
3.
Exclude all the language dependent attributes from the _VL entity object so that
the language dependent attributes always come from the _TL entity object.
Tip: This is important as it allows different users to see data for their
language.
4.
Create commonly used view criteria, with language being part of the criteria using
a bind variable.
Caution: The language must always be part of any view criteria. This
is very important.
Identify the shared application module that contains the shared data.
2.
3.
(Optional) Build validators on top of the view accessors that you created in Step 2.
This allows defaulting and derivation, and other business logic to use these view
accessors.
4.
(Optional) Use the shared view object instead of using entity object as the
validation target type for the key exist validator that validates shared data.
Tip: If you use entity object target type, it does not use
application-level cache.
If you rely upon the database change notification feature to refresh your shared AM
cache, then you also need to manually invoke the processChangeNotification
method on the shared AM to get the latest data. For more information, see the "Sharing
Application Module View Instances" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
59.7.5 What Happens at Runtime: When Another Service Accesses the Shared
Application Module Cache
During runtime, only one instance of a shared application module is created in the
application module pool. If there is an existing application module in the pool, then
the existing application module instance is returned when you request a shared
application module. For more information, see the "What Happens at Runtime: When
Another Service Accesses the Shared Application Module Cache" section in the Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
Sample CPU time with Collect Elapsed Time: Using this mode, you can find the
methods using the most CPU. The Collect Elapsed Time option also shows the
method taking the most time, including time spent in the database. This mode has
low overhead and does not significantly slow down the application.
Figure 5910
If you find a method with a high elapsed time but low CPU time and that method
includes a database call, this could indicate either a slow query or too many
database roundtrips between the database and the middle-tier over a slow
network. Look for methods with the highest exclusive CPU (sort on the CPUx
field), and use the stack trace to determine where they are called from and if they
can be optimized.
Memory Profiling: Using this mode, you can find out how much memory is
allocated during the test.
Call Count Profiling: This is part of the CPU profiler and can be used to find out
how many times each method is called.
Caution: Call count profiling has very high overhead and therefore,
you should increase Oracle JDeveloper starting memory before using
it.
3.
Deselect the Halt Execution option and select the Log Breakpoint Occurrence and
the Stack option. Selecting the Stack option gives you the stack trace, as shown in
the following figure.
Figure 5911
Edit Breakpoint
Each time the breakpoint is hit, the stack is written to the console. To capture this, you
must log the console output to a file.
To log the console output to a file:
1. Go to Tools, Preferences and select the Environment: Log category.
2.
Select the Save Logs to File option and specify the Log directory, as shown in the
following figure.
Figure 5912
After running your project, you can find the console logged to a file in the
specified directory.
60
Debugging Oracle ADF and Oracle SOA
Suite
60
Section 60.1, "Introduction to Debugging Oracle ADF Debugging and Oracle SOA
Suite"
Collecting Diagnostics
simulate the interaction between a SOA composite application and its web service
partners before deployment in a production environment. This helps to ensure that a
process interacts with web service partners as expected by the time it is ready for
deployment to a production environment.
For more information, see the "How to Turn On Diagnostic Logging for
Non-Oracle ADF Loggers" section in Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
When you test using Integrated WebLogic Server with Oracle WebLogic Server
data sources, the database connection is obtained from fusion_apps_
wls.properties and not from connections.xml. However, when you use the
application module tester to run an application module, the connection details
from connections.xml are used, even when you set your application module
configuration to use an Oracle WebLogic Server data source. Since the application
Collecting Diagnostics
module tester does not use Oracle WebLogic Server, it builds a database
connection from the information in connections.xml.
If you do not do this, some of the translated view will not return any data. For
example, if you are based in the United Kingdom, select userenv('lang') may
return GB by default, which does not match any of the data in the TL tables. This is
particularly important in the development environment where only the US
messages are available.
There may be other security restrictions that prevent you from viewing certain
data from a SQL*Plus session, such as data that is protected by virtual private
database (VPD) or data that requires you to initialize your userenv.
You may receive ORA-600 errors, which typically manifest themselves as
ORA-3114 or ORA-3113 on the client and indicate that the database session has
terminated abnormally. In this case, a trace file is always created automatically,
and the RDBMS alert log is updated with a record of the failure and the name of
the trace file. You do not need to enable SQL trace in this case because the trace file
is always created and should include a full dump, which will help RDBMS
Support and Development diagnose the cause. Both the alert log and the trace file
will be in the RDBMS User Directory.
You can also enable Oracle ADF tracing. For information, see the "Use SQL Tracing to
Identify Ill-Performing Queries" section in Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
Collecting Diagnostics
Add the following logging profile options for the required user:
For information on setting the profile options for logging, see Chapter 56,
"Defining Profiles".
3.
Make sure your logging.xml has the oracle.apps logger configured against a
handler. In your standalone server, logging.xml is located in the standalone
domain at <....> / domains/fusion_
domain/config/fmwconfig/servers/AdminServer/logging.xml.
The following logger should exist in logging.xml:
<logger name='oracle.apps' level='ALL'
useParentHandlers='false'>
<handler name='apps-handler'/>
</logger>
Diagnosing Problems
60.2.2.3.1
flow.
Enabling Database Tracing Enable database tracing before you start your test
From the Help menu in the work area of the Oracle Fusion application, choose
Troubleshooting and select Troubleshooting Options.
3.
60.2.2.3.2 Locating Your Trace File The trace file can be found in the USER_DUMP_DEST
directory specified by the user_dump_dest init.ora parameter, which is usually
ORACLE_HOME/log/diag/rdbms/sid/sid/trace. The trace filename includes the FND
session ID appended to the end, for example, mysid_ora_4473_
881497BF7770BEEEE040E40A0D807BB1.trc. You must identify the session ID to locate
your trace file.
From SQL*Plus, you can execute SQL> show parameter user
to show user_dump_dest. An operation system login is required to
access this directory.
Note:
From the Firefox will list, select Use custom settings for history, then click Show
Cookies.
3.
In the Search field, enter Oracle, then look for a cookie that contains FND_SESSION
in the name.
4.
5.
Open a SQL*Plus session (log in as fusion user) and locate your Applications Core
session ID by executing:
select session_id from fnd_sessions where session_cookie = value from Step 4
For example,
select session_id from fnd_sessions where session_cookie = 'BsdhOZScx9NeAA..'
The value returned if your session ID, which you can use to locate your trace file.
Diagnosing Problems
From the JDeveloper menu, select Run, then Start Server Instance.
2.
3.
4.
Log in to the Integrated WebLogic Server console using the username and
password weblogic and weblogic1.
5.
6.
From the list of configured data sources, select each data source and click the Test
button to make sure that the specified database can be reached with the connection
information.
Log in as an administrator.
3.
4.
60.3.1.3 Sanity Checking Your EAR File in the Integrated WebLogic Server
Environment
Sanity checking your EAR file helps to diagnose problems in the Integrated WebLogic
Server environment. Download the EAR file and open it using a decompression utility.
You can then drill down into the WAR file and individual Oracle ADF libraries.
While sanity checking your EAR file, verify the following:
The Model libraries are in the APP-INF/lib directory of the EAR file.
The service middle tier JAR and the service WAR files are directly under the EAR
file.
The service common JAR file is directly under the EAR file or under the
APP-INF/lib directory, depending on how it was set up.
The individual Oracle ADF libraries only contain components from the project that
was deployed to create the Oracle ADF library, and do not contain any
Debugging in JDeveloper
components from referenced projects. (This could happen if you have "build
output" dependencies.) If components from other projects were included, it should
be obvious from the package, since every project has a unique default package.
All standalone components (that is, those not in an Oracle ADF library) in the
WAR file belong to the UI project that was deployed (such as SuperWeb for Oracle
Fusion Applications). There should therefore be no standalone model components
in the WAR file.
None of the Model and Service Oracle ADF libraries have a public_html directory.
No technology JAR files are included in the EAR and WAR files. Tech stack JAR
files added to the WAR or EAR file take precedence over the ones in the shared
libraries, but the shared libraries contain the correct versions. The technology JAR
files in your EAR or WAR file may not be the correct versions.
60.3.2.1 Sanity Checking Your EAR File in the Standalone WebLogic Server
Environment
The procedure for sanity checking your EAR file in the standalone WebLogic Server
environment is the same as the procedure for Integrated WebLogic Server. For
information, see Section 60.3.1.3, "Sanity Checking Your EAR File in the Integrated
WebLogic Server Environment".
This method may be useful if you are actively debugging code from JDeveloper or
using the AM Tester.
Debugging in JDeveloper
JDeveloper Debugger.
For information, see the JDeveloper online help.
Related Links
The following document provides more information about the topic discussed in this
section:
For information, see the "Using the ADF Declarative Debugger" section in Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework.
3.
4.
5.
Select New and enter a name for the new profile. For example, Remote Debug.
6.
Click OK.
7.
Edit the new Remote Debug profile by entering the following information:
a.
b.
c.
Note:
8.
On the toolbar, click the Bug icon. Select the new Remote Debug profile. A dialog
appears to confirm attaching to the Administration Server.
The debugging log file will contain an entry similar to the following:
Debugger attempting to connect to remote process at ab6052cdef.us.example.com
8453.
Debugger connected to remote process at ab6052cdef.us.example.com 8453.
Processing 10008 classes that have already been prepared...
Finished processing prepared classes.
Debugger process virtual machine is Java HotSpot(TM) Server VM.
Set your break points and initiate your program. When you have finished, click the red
Stop button, and a dialog will appear asking if you want to Detach, Terminate, or
Cancel. Detach detaches from the remote Oracle WebLogic Server, and Terminate
terminates the remote Oracle WebLogic Server.
Tip:
Close the workspace and re-open it to refresh the references to the Oracle ADF
libraries. (Closing and restarting JDeveloper with a workspace open does not
refresh the references to the Oracle ADF libraries.)
If you have a specific project selected in the JDeveloper navigator pane, select
View, then Refresh ADF Library Dependencies for .jpr to refresh the
references to the Oracle ADF libraries.
When you make any changes to the components in a project,
where the components are being referenced as an Oracle ADF library
by your user interface (UI) project, you must redeploy the Oracle ADF
library and refresh the Oracle ADF library dependencies for your UI
project. The same applies to one model project referencing from
another model project. If you are developing or debugging code in a
model project while running the referencing UI project to test it, it may
be easier to add the model project as a build output dependency, so
you do not need to go through the cycle of redeploying the Oracle
ADF library or refreshing the Oracle ADF library references each time
you make a change.
Note:
60.5.1.3 "No def found" or "No class def found" Exception Occurs
Either a No Def Found or No Class Def Found runtime exception occurs.
Problem
Lower level dependency changes were made outside of the design time session.
Solution
Refresh the library in one of the following ways:
Close the workspace and re-open it to refresh the references to the Oracle ADF
libraries. (Closing and restarting JDeveloper with a workspace open does not
refresh the references to the Oracle ADF libraries.)
If you have a specific project selected in the JDeveloper navigator pane, select
View, then Refresh ADF Library Dependencies for .jpr to refresh the
references to the Oracle ADF libraries.
When you make any changes to the components in a project,
where the components are being referenced as an Oracle ADF library
by your user interface (UI) project, you must redeploy the Oracle ADF
library and refresh the Oracle ADF library dependencies for your UI
project. The same applies to one model project referencing from
another model project. If you are developing or debugging code in a
model project while running the referencing UI project to test it, it may
be easier to add the model project as a build output dependency, so
you do not need to go through the cycle of redeploying the Oracle
ADF library or refreshing the Oracle ADF library references each time
you make a change.
Note:
should refresh from the Data Controls panel before launching the Applications Core
component wizards.
In the Message Log window, select the Running Integrated WebLogic Server tab
and click the URL that launched your page in Integrated WebLogic Server.
Remove the Oracle ADF state related information from the URL displayed in the
browser (for example, ?_adf.ctrl-state=ku8guslcz_4) and reload the page.
Problem
Changes were made to the page binding definition file (PageDef), the resource (XLF)
files, or the Oracle ADF libraries.
Solution
Generally if the change you make is contained within a page or page fragment of the
current project, you do not need to redeploy your application. However, if changes are
made to the page binding definition file (PageDef), the resource (XLF) files, or the
Oracle ADF libraries then you must redeploy your application.
Solution
Check the EAR file to make sure that the missing component is actually present in the
expected location.
Close the workspace and re-open it to refresh the references to the Oracle ADF
libraries. (Closing and restarting JDeveloper with a workspace open does not
refresh the references to the Oracle ADF libraries.)
If you have a specific project selected in the JDeveloper navigator pane, select
View, then Refresh ADF Library Dependencies for .jpr to refresh the
references to the Oracle ADF libraries.
When you make any changes to the components in a project,
where the components are being referenced as an Oracle ADF library
by your user interface (UI) project, you must redeploy the Oracle ADF
library and refresh the Oracle ADF library dependencies for your UI
project. The same applies to one model project referencing from
another model project. If you are developing or debugging code in a
model project while running the referencing UI project to test it, it may
be easier to add the model project as a build output dependency, so
you do not need to go through the cycle of redeploying the Oracle
ADF library or refreshing the Oracle ADF library references each time
you make a change.
Note:
Force recompilation by right-clicking the JSP and selecting Build, then Clean All,
then rebuild and redeploy.
Solution
Check the settings for the ApplicationDB in the Oracle WebLogic Server
Administration Console.
Problem
The CHANGE_PERSISTENCE parameter value is incorrect.
Solution
Locate the following context parameter in web.xml:
<context-param>
<description>
This parameter turns on the session change persistence.
</description>
<param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
<param-value>oracle.adf.view.rich.change.MDSDocumentChangeManager</param-value>
</context-param>
60.5.1.17 Application Cannot Fetch Data from Oracle Fusion Applications Database
Your application is unable to fetch data from the Oracle Fusion Applications database.
Problem
The fusion_apps_wls.properties file does not contain the correct connection strings
for the application's data source.
Solution
Run the Configure Fusion Domain Wizard to create or update the fusion_apps_
wls.properties file with the correct connection information. For instructions on using
the wizard, see Chapter 2, "Setting Up Your Development Environment."
Problem
You modified the configuration of the server and did not activate the changes.
Solution
Go to the Administration Console (http://localhost:7101/console). Check the upper left
hand corner regarding messages about changes not being activated.
Problem
Service logic is taking longer than the default 300 seconds defined for Java Transaction
API (JTA). Services may have heavy validation which will take more time to create
row.
Solution
Set the JTA timeout condition to more than 300.
1.
2.
3.
4.
5.
Increase the value of the Timeout Seconds property based on the expected
completion time of the longest transaction. The default value is 300.
61
Designing and Securing View Objects for
Oracle Business Intelligence Applications
61
This chapter provides guidelines and best practices for designing and securing Oracle
Application Development Framework (Oracle ADF) view objects and other
supporting business component objects for use by Oracle Business Intelligence
Applications.
This chapter includes the following sections:
Designing and Securing View Objects for Oracle Business Intelligence Applications
61-1
Oracle BI Enterprise Edition (Oracle BI EE) needs to efficiently access data from two or
more master/detail-linked view objects to aggregate, present, or report on that
combined data set. An essential requirement is to efficiently retrieve the
multiple-levels of related information as a single, flattened query result, to perform
subsequent aggregation or transformation on it. Oracle ADF Composite View Object
API allows the caller to create a new view object at runtime that composes the
hierarchical results from two or more existing view-linked view objects into a single,
flattened query retrieving the same effective set of data.
From a performance perspective, such queries would need to be performed on
low-level data in Oracle BI EE, since the Oracle ADF layer does not directly support
aggregation. This would generally slow query performance down. Also, going
through additional servers (that is, JavaHost and Oracle ADF) in the network would
also be slower than directly querying the database. Therefore, the SQL Bypass feature
has been introduced to directly query the database and push aggregations and other
transformations down to the database server, where possible, thereby reducing the
amount of data streamed and worked on by Oracle BI EE.
The SQL Bypass functionality in Oracle BI EE utilizes the Composite View Object API
feature to construct and return a flattened SQL Bypass query that incorporates all of the
required columns, filters, and joins required by the Oracle Business Intelligence query.
Oracle BI EE then executes this query directly against the database.
View links must not contain custom SQL functions such as TRUNC and BETWEEN.
Use the BI_JOINTYPE custom view link property to define outer joins on view
links.
There is no support for Java or Groovy calculated attributes.
Programmatic view objects, transient view objects, and transient attributes are not
supported.
SQL Bypass
Full SQL can be obtained at runtime using vo.getQuery().
Designing and Securing View Objects for Oracle Business Intelligence Applications
61-3
If you are using Multi-Organization Access Control (MOAC) you must not enable
MOAC for the view objects for Oracle Business Intelligence Applications. You
should use the underlying Fusion Data Security instead.
For more information, see "About Specifying a SQL Bypass Database" in Oracle Fusion
Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise
Edition.
SQL Pruning
You should create your view objects in Declarative SQL Mode.
For more information about Declarative SQL Mode, see "Working with View
Objects in Declarative SQL Mode" in Oracle Fusion Middleware Fusion Developer's
Guide for Oracle Application Development Framework.
You should set primary entity usage to identify the fact and dimension grain
because primary entity usage cannot be pruned.
You must set the Selected in Query property for non-primary key and unsecured
attributes to false.
You should limit view criteria on non-primary entity derived attributes because
attributes used in applied view criteria cannot be pruned.
You should limit order by clauses on non-primary entity derived attributes
because attributes used in applied order by clauses cannot be pruned.
As a general rule, you should include all attributes from the underlying primary
and reference entity objects in your view objects.
Flex attributes are an exception from this rule. These attributes are not required
because they are exposed using the Flex Extender utility.
You should only include name and description attributes from the reference entity
objects that are included to only resolve ID and Code columns.
You should include Standard Who Columns from all participating entity objects on
your view objects for Oracle Business Intelligence Applications. This is to support
Oracle BI Applications's Change Data Capture requirements.
Exceptions include entity objects that are only included to resolve ID and Codes
into meaningful descriptions. For example, entity objects included to only resolve
Business Transactional Intelligence-only attributes into a view object using entity
object associations.
Table 611 shows the Standard Who Columns.
Table 611
CREATION_DATE
LAST_UPDATED_BY
LAST_UPDATE_DATE
You should set the Selected in Query property to be false on all non-primary key
view object attributes.
You should resolve duplicate attribute names on view objects, which are made up
of multiple entities, by using an attribute prefix.
Use an alias property as both the table alias and column alias in the SQL as well as
the view object attribute prefix. For example:
This view object includes HeaderId attributes from both HeaderEO and
LinesEO.
The POLinesVO is then created using Header as the prefix for all Header
attributes, and Lines as the prefix for all Lines attributes. For example,
HeaderHeaderId and LinesHeaderId; HeaderBusinessUnitId and
LinesBusinessUnitId.
If the foreign key is neither a dimension nor a warehouse domain, you should
should resolve the foreign key using entity object associations. For
MLS-enabled entities, ID and Code attributes should be resolved using _VL
views.
61-5
LEFTOUTER
RIGHTOUTER
FULLOUTER
INNER (default)
Security filters
For more information about security filters, see Section 61.3.4, "Understanding
Business Intelligence Filters."
Filters to distinguish different logical entities based on the same entity object. (For
single entity object view objects).
For more information, see "Working with Named View Criteria" in Oracle Fusion
Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Flattened view objects should be modeled in the Oracle Business Intelligence layer as a
single logical table with multiple logical table sources.
Create separate view objects for fact entities and dimension entities.
Do not flatten relationships between facts and dimensions into a single view
object.
InvoiceId
InvoiceNum
TaxRelatedInvoiceId
CreditedInvoiceId
If you decide that these should be modeled as three separate facts, then you create two
additional view instances, TaxRelatedInvoicesVO and CreditdInvoicesVO, with view
links to the InvoiceHeaderVO.
If you decide that they do not need to be modeled as separate objects, then you should
create the two additional joins inside the InvoiceHeaderVO to bring in
TaxRelatedInvoiceNum and CreditedInvoiceNum.
Row and Column flattening is required for view objects with self-joins that are
modeled as dimensions in Oracle Business Intelligence Applications. You should
determine the level of flattening required on a case-by-case basis.
Designing and Securing View Objects for Oracle Business Intelligence Applications
61-7
Note:
Date effective entity objects and view objects should be marked as such according
to Oracle ADF.
Flattening requirement excludes scenarios where other design considerations
require not flattening the entity objects in the view object. For example, 1:n
relationships.
Both entity objects are date effective.
The PersonsVO should be flattened to include both PersonEO and PersonDetailEO
and should also be marked as Date Effective.
In other words, there should be a single current person details record for each
person record.
For more information, see "How to Store Data Pertaining to a Specific Point in
Time" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
Create a separate view object for these entity objects. The entity object is removed
from the flattened view object.
Create view links to join these view objects.
You must only include one historical entity object for any given view object in
Oracle BI Applications.
You should still mark view objects as date effective so that Transactional Business
Intelligence can share and date effective predicate can be applied in the Oracle
Business Intelligence layer.
Fact Grains
POHeaderVO
Header
POLinesVO
Header + Lines
POShipmentsVO
PODistributionsVO
Entity objects can be included in flattened view objects as required if the view object
grain does not change.
Note:
Designing and Securing View Objects for Oracle Business Intelligence Applications
61-9
For example, For Payment Invoices fact view object using Business Unit security
(MOAC style), the privilege is:
"FNDDS__AP_MANAGE_PAYABLES_INVOICE_DATA__FUN_ALL_BUSINESS_UNITS_V__BU"
The fact view object requires an entity object for securing the table. (BU in this
example). The join between the fact and the securing table should be properly
resolved. The alias used in the view criteria should be that of the entity object
corresponding to the Object in privilege (BU in this example).
If a non-MOAC grant is made for a transaction object, such as, for example, the
Payment fact of the Fusion Incentive Compensation Management (ICM) Application,
the object and alias refer to the ICM Payment entity. For example:
"FNDDS__VIEW_INCENTIVE_COMPENSATION_PAYSHEET_DATA__IC_INCENTIVE_COMPENSATION_
PAYSHEET__ICPAY"
61.4.2.1 Securing the Same Transaction by Multiple Entities for Different Roles
In Oracle Fusion Applications, transaction data can be secured by more than one
entity, based on the role used to access the transaction data. For example, consider the
case of the Fusion Incentive Compensation Management (ICM) Application, in which:
In the above case, because the view object for the transaction object implements single
data security privilege, the privilege should be able to provide access based on
business unit as well as participants. Building this privilege provides a logical filter
similar to:
"for the participants for who they are responsible" OR "for business units for which they are
authorized"
You can achieve this by creating a new privilege and having two policies created using
the same privilege. One policy should be created using instance set to provide "for
business units for which they are authorized", and the second policy should be created
using instance set to provide "for the participants for who they are responsible". The
policies should be granted to existing roles.
To secure transaction by more than one entity:
The following steps are based on the Fusion ICM Paysheet use case.
1.
Create a new data privilege titled View Incentive Compensation Paysheet Data.
2.
Author the following data security policies, using existing duties and the new data
privilege defined in Step 1:
3.
a.
b.
b.
Note:
4.
Use privilege View Incentive Compensation Paysheet Data in data security view
criteria in Incentive Compensation Paysheet. The view criteria should be like
Example 611 assuming IC_INCENTIVE_COMPENSATION_PAYSHEET is the object
registered in FND_OBJECT and ICPAY is the alias used for the entity object.
Example 611
"FNDDS__VIEW_INCENTIVE_COMPENSATION_PAYSHEET_DATA__IC_INCENTIVE_COMPENSATION_
PAYSHEET__ICPAY"
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-11
There are other use cases that fall into same design pattern of a transaction being
secured by multiple entities and Oracle Business Intelligence implementation needing
UNION access. For example, in Oracle Fusion Projects, the transaction table Expenditure
Item is secured by Business Unit as well as by Project. For Oracle Business Intelligence
reporting, the query on Expenditure Item should return rows for authorized business
units for a user as well as authorized project for user.
In general, while the Oracle Business Intelligence use cases for transaction being
secured by multiple entities will be similar; application teams can make their own
decisions about how they implement an Oracle Business Intelligence solution. For
example, in the case of the Oracle Fusion Incentive Compensation Management and
Oracle Fusion Projects applications, you can implement different solutions for
achieving the same results by having different styles of grants and roles. Therefore,
application teams should choose their own implementation based on their existing
roles and privileges, and the approach they want to take for Oracle Business
Intelligence solution.
The first dimension view object implements data security. This is used in
dimension browsing and can include all columns required for dimension
browsing. To ensure BI EE uses the secured version for dimension browsing, make
sure it is higher up in the list of Logical Table Sources (LTS) than the unsecured
one.
The second dimension view object should be unsecured. To ensure that the
unsecured view object is used to combine with the fact, physical joins should be
defined between the physical fact table and the physical table for the unsecured
version of the dimension view object.
Caution: Dimensions, for which unsecured view objects are created,
may contain sensitive attributes. If this is the case, then you must
make sure that the unsecured view object does not contain these
sensitive attributes.
Dual (secured and unsecured) view objects are only required for entities that fall in
this design pattern. Entities not requiring both secured and unsecured access do not
require dual view objects.
logical layer entity in the RPD and it uses the same view object as the underlying fact.
Consequently, the data security for degenerate fact is the same as that of underlying
fact table.
This may create a problem when the degenerate dimension is used in another fact that
has different security than the degenerate dimension (or more accurately, the fact
underlying the degenerate dimension). For example:
Fact B is secured using a different dimension (or different privilege) than Fact A,
which was used to source for Dimension A.
In such cases, the security of both Fact B and Fact A should be applied; where as the
desired result was just to apply security of Fact B.
These should be modeled as a single Geography logical dimension table with multiple
logical table sources, one for each of the dimension grains.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-13
InventoryOrgParameters
HrOrganizationUnits
HrLocations
Human Resources (HR) entities may have their own security. However, for the
InventoryOrgParameters entity, only the security defined by inventory product
Manage Inventory Org Parameters is necessary. In other words, data security on HR
entities should be ignored when consumed in InvOrg.
This use case is similar to Section 61.4.2.2, "Securing Transactions Different from
Securing Dimensions," where unsecured view objects are used for dimensions.
A base dimension view object satisfying the basic, functional requirements for
data retrieval is initially developed.
The base dimension view object is used to create a secured dimension view object
by using the methods and strategies described earlier in this section.
An unsecured dimension view object is developed by manually creating an exact
copy of the original base dimension view object.
The unsecured dimension view object is named <VO Name>ListPVO, where <VO
Name> is the name of the base dimension view object.
Consuming applications must build View Links to both the secured and unsecured
dimension view object definitions. Once the secured and unsecured dimension view
objects have been deployed, you can begin developing models based upon them in
Oracle Business Intelligence.
fact is at day level in Financials and the reporting calendar is fiscal (in addition to
gregorian), view links should be created to the day level of the fiscal calendar.
Create a view instance using the above view criteria for each dimension.
Foreign keys to low cardinality lookups, such as FND_LOOKUPS, should not be resolved
in fact or dimension view objects. These should be resolved in the logical layer
through the lookup function.
Business Transactional Intelligence-only low cardinality lookups should be resolved
using entity object associations based on a _VL view.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-17
Each node has a unique identity, in this case denoted by dot-separated numbers that
correspond to the node's relative ordering in the overall parent-child structure. Such
value hierarchies may be arbitrarily recursive (in terms of recurring node types), and
are usually ragged, or unbalanced. There is only a general concept of "level" in these
hierarchies, which refers to the path distance (or depth) from the root node to some
specified node.
Two nodes the same distance from the root are thought of as being at the same level.
However, unlike true level-based trees, there is no requirement for nodes at the same
level to possess a common set of properties. In fact, a node in a value-based tree may
have any arbitrary collection of properties. When these trees are used to represent
dimensional hierarchies, facts, metrics, or transactions, values may be joined to any
node. There is no constraint that facts or transactions only be joined to lowest-level
nodes, as is usually the case with level-based trees.
The example value-based tree shown in Figure 612, also has multiple top-level or
root-level nodes. Since it has five levels (or equivalently, a maximum depth of four), a
column-flattened representation of this tree requires a minimum of five columns. This
is illustrated in Table 613.
In practice, you would never have single node trees. However,
root nodes 2.0 and 3.0 are in Figure 612 to simply illustrate multiple
top-nodes.
Note:
Table 613
C0
C1
C2
C3
C4
Distance
1.0
1.0
1.0
1.0
1.0
1.1
1.1
1.1
1.1
1.0
1.2
1.2
1.2
1.2
1.0
1.2.1
1.2.1
1.2.1
1.2
1.0
1.2.1.1
1.2.1.1
1.2.1
1.2
1.0
C1
C2
C3
C4
Distance
1.2.1.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.2
1.2.2
1.2.2
1.2
1.0
1.2.2.1
1.2.2.1
1.2.2
1.2
1.0
1.2.2.2
1.2.2.2
1.2.2
1.2
1.0
2.0
2.0
2.0
2.0
2.0
3.0
3.0
3.0
3.0
3.0
The first column (C0) contains a complete enumeration of each node in the tree. In
this example, each node is represented by the value of its unique identity.
Having the unique identity of each node of the hierarchy represented exactly once
in the C0 column means that it is always possible to directly address each node,
such as for purposes of joining with a transaction or measure, or for performing a
calculation on that node.
The last column (C4 in the example) always represents the root node of some
rooted ancestral path of the tree.
The intermediate ancestral path nodes between a given node in the C0 column and
its ancestral root node in the C4 column, is represented by columns C1 through C3.
Each column stores a reference to some node of the ancestral path, descending
from C3 toward C0, filling each column (from right to left) with a reference to the
next child node of the path. When a reference to the C0-th column node occurs,
this reference is then repeated, if necessary, so as to pad the remaining columns
until the C0 column is reached.
Having the complete ancestral path, with unused columns padded toward the C0
node value, facilitates more efficient drill down operations.
C0
...
C15
C16
C17
C18
C19
Distance
1.0
...
1.0
1.0
1.0
1.0
1.0
1.1
...
1.1
1.1
1.1
1.1
1.0
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-19
...
C15
C16
C17
C18
C19
Distance
1.2
...
1.2
1.2
1.2
1.2
1.0
1.2.1
...
1.2.1
1.2.1
1.2.1
1.2
1.0
1.2.1.1
...
1.2.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.1.1.1
...
1.2.1.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.2
...
1.2.2
1.2.2
1.2.2
1.2
1.0
1.2.2.1
...
1.2.2.1
1.2.2.1
1.2.2
1.2
1.0
1.2.2.2
...
1.2.2.2
1.2.2.2
1.2.2
1.2
1.0
2.0
...
2.0
2.0
2.0
2.0
2.0
3.0
...
3.0
3.0
3.0
3.0
3.0
Think of the tree in Figure 612 as a true level-based tree, with fixed levels, single
top-nodes, and all leaf nodes residing at the same lowest level of the tree (such as level
zero, represented by column C0). In this case, you would actually have three separate
trees, and the tree rooted at node 1.0 would have the logical column-flattened
representation shown in Table 615, assuming the same "pad toward leaf values"
scheme as with the value-based tree.
Table 615
C0
C1
C2
C3
C4
Distance
1.1
1.1
1.1
1.1
1.0
1.2.1.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.2.1
1.2.2.1
1.2.2
1.2
1.0
1.2.2.2
1.2.2.2
1.2.2
1.2
1.0
The notion of distance from the root is still relevant, even though all of the leaf nodes
are assumed to reside at the same level (level zero, or C0).
Example 612
MDS Configuration
<adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config"
version="11.1.1.000">
<mds-config version="11.1.1.000" xmlns="http://xmlns.oracle.com/mds/config">
<persistence-config>
<metadata-namespaces>
<namespace path="/sessiondef" metadata-store-usage="mdsRepos"/>
<namespace path="/persdef" metadata-store-usage="mdsRepos"/>
<namespace path="/oracle/apps/fnd/applcore/trees/analytics"
metadata-store-usage="mdsRepos"/>
</metadata-namespaces>
<metadata-store-usages>
<metadata-store-usage id="mdsRepos">
<metadata-store name="fs1" class-name="oracle.mds.persistence.
stores.file.FileMetadataStore">
<property name="metadata-path" value="/tmp"/>
</metadata-store>
</metadata-store-usage>
</metadata-store-usages>
</persistence-config>
</mds-config>
</adf-mds-config>
2.
Ensure that each view object attribute of the tree data source view objects is
marked as relevant to Oracle Business Intelligence (or not) via the BI Relevant
property that is exposed in the Property Inspector for the view object attribute.
By default, only primary key attributes are "BI Relevant". For
performance reasons, it is recommended that only those attributes that
are really relevant to Oracle Business Intelligence be marked as such
to avoid generating very large BICVOs.
Note:
3.
4.
Secure the generated BICVO using the data security infrastructure. For more
information, see Section 61.8.6, "Securing ADF Business Components View Objects
for Trees."
The generated BICVO includes a special view criteria named FNDDS__BICVO. To
secure access to data through the BICVO, this view criteria must be enabled for
instances of the BICVO in any application module. At runtime, data security rules
affecting access to the tree data source view objects are automatically carried over
to the BICVO.
In Oracle Fusion Applications V1, only filter-based data
security rules are supported. In addition, only the "is descendant of"
operator is supported.
Note:
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-21
They must have custom, (preferably application-specific) names; for example, PJF_
PROJ_ELEMENTS_CF is currently being used by the Projects team to implement a
column-flattened table for the Task Hierarchy.
The column names and column data types of each custom table must be the same
as those of the corresponding FND table.
Custom versions of FND_TREE_NODE_CF can define an index on each of the
level-based foreign key references to support efficient drill-downs. However, it is
understood that certain application query patterns do not necessitate this degree
of indexing. Indexing is also not necessary if the column-flattened table is
guaranteed to be relatively small.
Custom versions of the FND_TREE_NODE_CF should not include the ENTERPRISE_ID
column as part of the primary key index defined on the custom table. This is
because this column is not currently used by Oracle Fusion tree management.
61.8.3 Using Declarative SQL Mode to Design View Objects for Oracle Business
Intelligence Applications
All view objects for Oracle Business Intelligence Applications should be constructed in
declarative SQL mode. This ensures that correct SQL pruning can be applied to any
composite view object incorporating the Oracle Business Intelligence view object. This
requirement also applies to the BICVO generated by Oracle Fusion tree management.
However, of all the possible configurations of ADF Business Components objects
defining a tree data source, only two configurations in particular actually lend
themselves to the generation of declarative-mode BICVOs by Oracle Fusion tree
management.
These configurations have been formalized as two distinct design patterns:
Design Pattern #1: Single data source view object, single data source entity object
Design Pattern #2: Multiple data source view objects, unique data source view
object per depth of tree, single data source entity object per data source view object
Although either pattern can be used in the realization of either tree type, the first
pattern is generally better suited to value-based trees, while the second pattern is more
natural for level-based trees. However, the patterns are aimed primarily at supporting
the automated generation of declarative-mode BICVOs, rather than supporting either
particular type of tree.
Figure 613 Declarative BICVO Based on Single Data Source View Object, Single Data
Source Entity Object
In this pattern, there is a single data source entity object and a single data source view
object based on that entity object. The data source view object is a declarative-mode
view object built by developers and registered with Oracle Fusion tree management.
The data source entity object in turn is based on a _VL database view that joins the data
source base table (_B) with a table of translated values (_TL).
A second entity object is defined for the column-flattened table. Currently, the
column-flattened table entity object must be created manually and made known to the
generated BICVO via a manual workaround. Additionally, a collection of entity object
associations, each joining the column-flattened entity object with the data source entity
object for a unique level or depth of the tree, must also be created manually. If the
application design requires that the base data source table expose multiple entity
objects for any reason, then a _VL database view must be defined to join the multiple
entity objects (possibly along with any translated attribute values), and that _VL
database view must support the single data source entity object.
Once the data source view object is registered with Oracle Fusion tree management as
part of the tree structure definition process, and the required manually-created objects
are all in place, a declarative BICVO may then be generated by Oracle Fusion tree
management.
This declarative-mode BICVO pattern is well-suited for value-based trees, since
value-based trees are most often represented at the data source level by a single table
with a recursive self-join. However, there is nothing about the pattern that strictly
requires its use in value-based hierarchies, nor prohibits its use from other types of
hierarchies (such as level-based or hybrid). The primary objective of this pattern is to
facilitate the automatic generation of a declarative-mode BICVO from an
ATG-registered tree.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-23
Figure 614 Declarative BICVO Based on Multiple Data Source View Objects, Unique
Data Source View Object per Level, Single Data Source Entity Object per Data Source
View Object
In this pattern, there are multiple data source view objects, with a unique data source
view object representing each level or depth of the tree. Each data source view object is
based on a single, unique data source entity object. Each data source view object is a
declarative-mode view object built by developers and registered with Oracle Fusion
tree management. All of the data source view objects must be declarative-mode view
objects; otherwise, a declarative-mode BICVO can not be generated. As with the
previous pattern, each data source entity object in turn is based on a _VL database view
that joins some data source base table (_B) with a table of translated values (_TL).
While multiple _VL database views are represented in the diagram, there is no
hard-and-fast requirement that each data source entity object actually be built on top
of a unique _VL database view. The diagram simply admits the possibility of multiple
such views, presumably one per level or depth of the tree.
The same as with design pattern #1, an entity object is also defined for the
column-flattened table, and must also be created manually, and is made known to the
generated BICVO via a manual workaround. This column-flattened table entity object
is also joined to the data source entity objects via a collection of entity object
associations. However, each entity object association relates the column-flattened table
entity object to a unique data source entity object representing a particular level or
depth of the tree.
If the application design requires that the base data source table expose multiple entity
objects per tree level or depth, then a _VL database view must be defined to join the
multiple entity objects (possibly along with any translated attribute values) at that tree
level or depth, and that _VL database view must support the single data source entity
object for that tree level or depth.
Once the data source view objects have been registered with Oracle Fusion tree
management as part of the tree structure definition process, and the required
manually-created objects have all been put in place, a declarative BICVO may be
generated by Oracle Fusion tree management.
This declarative-mode BICVO pattern is well-suited for level-based trees, since
level-based trees are often built on top of multiple data sources, with a unique data
source per level. However, there is nothing about the pattern that strictly requires its
use in level-based hierarchies, nor prohibits its use from other types of hierarchies
(such as value-based or hybrid). The primary objective of this pattern is to facilitate the
automatic generation of a declarative-mode BICVO from an ATG-registered tree.
Designate the column-flattened table entity object as the primary entity of the
BICVO.
Designate the data-source entity objects as secondary or reference entities of the
BICVO.
Do not mark primary key attributes of the data source entity objects as
primary-key attributes in the resulting column-set. (These are exposed by the
generated BICVO).
Set the selectedInQuery property of any non-primary key attribute of the
generated BICVO to false.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-25
inspection of the data source view object and its attendant view attributes and view
criteria, as well as inspection of the registered column-flattened table.
The BICVO, as generated by Oracle Fusion tree management, also includes a
placeholder view criteria that is otherwise empty and specifies a logical OR condition as
its connective to any other view criteria that might be defined as part of the BICVO.
This placeholder view criteria is defined for data security purposes, and at the current
time, simply directs ATG logic to invoke the data security view criteria defined on the
data source view object.
There may also be a requirement to supply Oracle Data
Integrator (ODI) with translations via a view object that is separate
from the base data source table or _VL database view. In this case, you
must develop a view object and entity object pair that directly goes
against the translations table (_TL).
Note:
You must take this entire collection of ADF Business Components objects, both
hand-crafted and generated alike, and package them for deployment as part of an
appropriate application module. Note that any ATG-generated artifacts, such as the
BICVO, is generated to reside within the Oracle Fusion Middleware Extensions for
Applications package namespace, which is:
oracle.apps.fnd.bi.applcore.trees.bi.model.view
Most of the Oracle Business Intelligence view objects and other artifacts are packaged
under the Oracle Business Intelligence analytics namespace, which is:
oracle.apps.<LBATop>.<LBACore>.publicview.analytics
BI (RPD)
Application (BICVO)
Top
C31
Level Top +1
C30
.....
.....
Level Base - 1
C18
Base
C0
When mapping application trees to Oracle Business Intelligence hierarchies, there are
two types of problems that may arise:
The application tree exceeds 15 levels and the Transactional Business Intelligence
realization of the hierarchy (provided by the Oracle BI EE server) has been pruned
to 15 levels. However, the Oracle BI Applications realization of the hierarchy
(provided by the ETL process) is allowed to exceed 15 levels. In this case, the
Transactional Business Intelligence and Oracle BI Applications realizations of the
hierarchy have different resolutions at their lowest levels.
The application tree exceeds 15 levels and the Transactional Business Intelligence
and Oracle BI Applications realizations of the hierarchy are both pruned to 15
levels. In this case, Transactional Business Intelligence and Oracle BI Applications
are the same in terms of resolution, but the Oracle Business Intelligence side and
the application side are not the same. For example, the application tree has greater
resolution than its Oracle Business Intelligence counterpart.
The following are two possible consequences that may result from the problems
outlined:
Loss of information (loss of resolution) resulting from the pruning away of several
lower levels of the hierarchy, as well as potential differences in information
(resolution) between Transactional Business Intelligence and Oracle BI
Applications.
An effect on fact-based security at the pruned levels. For example, you have
established certain privileges on facts joined to nodes at tree levels that are
ultimately pruned away. The security privileges of facts that had been joined to the
pruned nodes may have been more restrictive than those at ancestral levels.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-27
Note:
Complete Resolution:
Any application tree that has a realization on the Oracle Business Intelligence side
(Transactional Business Intelligence or Oracle BI Applications) must be restricted
to no more than 15 levels.
Mitigation:
Ensure that, if any application tree exceeds 15 levels, and that tree has realizations
on both Transactional Business Intelligence and Oracle BI Applications, that both
technologies maintain pruned realizations of this tree and have the same number
of levels (such as 15 or less).
For this resolution, it will be necessary that these situations be investigated and
documented on a case-by-case basis. You must decide how you want to adjust the
security privileges of metrics that had previously been joined to the pruned levels,
and then revise your Oracle Business Intelligence models accordingly.
C0
C1
C2
C3
C4
Distance
1.0
1.0
1.0
1.0
1.0
1.1
1.1
1.1
1.1
1.0
1.2
1.2
1.2
1.2
1.0
1.2.1
1.2.1
1.2.1
1.2
1.0
1.2.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.1.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.2
1.2.2
1.2.2
1.2
1.0
1.2.2.1
1.2.2.1
1.2.2
1.2
1.0
1.2.2.2
1.2.2.2
1.2.2
1.2
1.0
2.0
2.0
2.0
2.0
2.0
3.0
3.0
3.0
3.0
3.0
C0
C1
C2
C3
C4
Distance
1.0
1.0
1.0
1.0
1.0
1.1
1.1
1.1
1.1
1.0
1.2
1.2
1.2
1.2
1.0
1.2.1
1.2.1
1.2.1
1.2
1.0
1.2.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.1.1.1
1.2.1.1
1.2.1
1.2
1.0
1.2.2
1.2.2
1.2.2
1.2
1.0
1.2.2.1
1.2.2.1
1.2.2
1.2
1.0
1.2.2.2
1.2.2.2
1.2.2
1.2
1.0
2.0
2.0
2.0
2.0
2.0
3.0
3.0
3.0
3.0
3.0
Note:
When Oracle Fusion tree management generates the BICVO, it automatically adds
an Oracle Fusion data security view criteria to the BICVO (FNDDS__BICVO). You
must not change this view criteria's name but must ensure that it is enabled for the
application module for the Transactional Business Intelligence.
The view criteria predicate for BICVO is generated from the base table view object
at runtime by Oracle Fusion tree management. This ensures that BICVO data
security is in sync with the base object.
The following restrictions are placed on the base object view criteria so that the
base view criteria is mapped to the BICVO view criteria, (which may have
different column names), at runtime:
The base object view criteria must only use "Filter", which stores predicates
using metadata. It cannot use SQL.
The base object view criteria must only use the DescendantOf hierarchy
operator. It must not use any other hierarchy operators.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-29
There may be situations in which a tree must support both secured and unsecured
access. In this case, the BICVO that exposes the tree structure is deployed as both
secured and unsecured versions.
The generated BICVO already has a security mechanism associated with it that is
based on its data source view object. An unsecured version of the BICVO can be
created by manually making a copy of the generated BICVO and editing it to exclude
sensitive columns. Then, secured access to this edited BICVO is turned-off by
de-activating the dummy FNDDS__BICVO view criteria associated with the BICVO. This
causes the data source security view criteria to not be enforced. Again, both the
secured and unsecured versions of the BICVO for the tree are to be deployed together
in the same application module.
For information on how to perform these tasks, see the following sections in this book:
Set-enabled lookups
Build an entity object association between the Fact entity object and the
SetAssignment entity object for each set-enabled lookup on the fact.
2.
Expose setID as an attribute on the FactVO for each set-enabled lookup type on the
FactVO.
The Lookup function is used to retrieve the translated meaning from the warehouse
using setID parameter.
61-30 Developer's Guide
Supporting Multi-Currency
61.10.2 How to Expose the SetID Attribute for Set-Enabled Reference Tables
The setID is stored on set-enabled reference tables. A Unique ID is used as the primary
key of the reference table; ID and language form the unique key of the translated
reference table. The determinant value is not stored on the reference table; the foreign
key used to reference the table is stored on transaction tables.
To expose the setID attribute:
Because the foreign key to the reference table already exists on the transaction,
meanings for set-enabled attributes should be resolved depending on usage.
Warehouse domain:
A separate view object is required. Build a view link from the base view object to
the reference view object. The setID attribute exists on the reference table view
object.
Designing and Securing View Objects for Oracle Business Intelligence Applications 61-31
Supporting Multi-Currency
62
Implementing ADF Desktop Integration
62
This chapter describes how to combine third party desktop applications with Oracle
Fusion web applications.
The chapter includes these sections:
62-1
|
|
|
|
|
|
|
|
|-|
|
|
|
|
|
|
adfmsrc
|-- META-INF
|
|-- <various generated files>
|-- oracle
|-- apps
|-- <LBA Top>
|-- <LBA Core>
|-- di
|
|
|
|
|
|
|
|
|
|
|
|
|-- public_html
|
|-- oracle
|
|
|-- apps
|
|-- <LBA Top>
|
|-- <LBA Core>
|
|-- di
A major benefit to putting ADF Desktop Integration web picker dialog artifacts into a
di folder is that automated standards checks can easily distinguish Desktop
Integration-related objects and adjust their logic as needed. The directory structure
under di will be organized the same way as the directory structure under the ui folder.
For example, the bean, controller, page and util folders under di will be found in
the same relative locations as the equivalent folders under ui.
The Excel Microsoft Office Open XML Format (XLSX) workbooks (and XLSM files, if
required) should be checked into an excel folder within the public_html directory
structure:
|
|
|
|
|
|
|
|
|
|
|-- public_html
|
|-- oracle
|
|
|-- apps
|
|-- <LBA Top>
|
|-- <LBA Core>
|
|
|
|
|
|
|-- di
|-- excel
Example 621 shows some full directory paths for the ADF Desktop Integration
artifacts on a Windows system, for a project in a leaf LBA called desktopJournalEntry.
The folders contain page definitions, Excel and JSPX files, and beans, respectively:
Example 621
D:\FinDashboardPrototype\gl\components\journals\desktopJournalEntry\di\adfmsrc\ora
cle\apps\financials\generalLedger\journals\desktopJournalEntry\di\pageDefs
D:\FinDashboardPrototype\gl\components\journals\desktopJournalEntry\di\public_
html\oracle\apps\financials\generalLedger\journals\desktopJournalEntry\di\[excel|p
age]
D:\FinDashboardPrototype\gl\components\journals\desktopJournalEntry\di\src\oracle\
apps\financials\generalLedger\journals\desktopJournalEntry\di\bean
Example 622 shows some directory paths for the ADF Desktop Integration artifacts in
source control, for a project in a leaf LBA called desktopJournalEntry. The folders
contain page definitions, [excel] and JSPX files, and beans, respectively:
Example 622
scs/gl/components/journals/desktopJournalEntry/di/adfmsrc/oracle/apps/financials/g
eneralLedger/journals/desktopJournalEntry/di/pageDefs
scs/gl/components/journals/desktopJournalEntry/di/public_
html/oracle/apps/financials/generalLedger/journals/desktopJournalEntry/di/[excel|p
age]
scs/gl/components/journals/desktopJournalEntry/di/public_
html/oracle/apps/financials/generalLedger/journals/desktopJournalEntry/di/bean
scs/gl/components/journals/desktopJournalEntry/di/src/oracle/apps/financials/gener
alLedger/journals/desktopJournalEntry/di/bean
62-3
Component Property
Data Type
Description
closeWindowBinding
String
downloadAfterUpload
Boolean
abortUploadOnFailure
Boolean
If you are using the page as a simple dialog (a basic web picker
that only needs ADFdi_CloseWindow), you only need to specify the
closeWindowBinding. Do not specify values for the
downloadAfterUpload and abortUploadOnFailure properties, which
only need to be specified for a custom upload dialog.
Note:
In the Resource Palette (View > Resource Palette), right-click File System and
select New File System Connection.
Enter the connection name, such as DI Components, and the directory path as
/ade/<view name>/fusionapps/jlib.
Test the connection to make sure it is valid. If it is, click OK.
2.
3.
Expand the connection you just created (FileSystem > <connection name>).
4.
5.
To make sure the library was added, open Project Properties > Libraries and
Classpath > ADF Library. You should see an entry for
AdfFinFunPublicDeclarativeComponentsDi.jar.
When you add the library as a library reference to your project, the component palette
will contain the Di Components option that lists all the DI components available for
use.
To add the component to the web page:
1. In the component palette (View > Component Palette), select the
DialogAttributes component and drag it onto the desired web page.
The DI component namespace is added to the jsp:root tag at the top of your
page:
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
xmlns:c="http://java.sun.com/jsp/jstl/core"
xmlns:di="http://xmlns.oracle.com/apps/financials/common/publicDi/component/diC
omponents">
62-5
3.
4.
5.
Select Admin Server in the Names column of the table. The settings page for
AdminServer(admin) is displayed.
6.
7.
8.
Set the Front End Host field to admin.mycompany.com (your LBR address).
9.
2.
In the left pane of the Console, expand Environment and select Clusters.
3.
Select the name of the cluster for which you want to configure HTTP.
4.
Select HTTP and enter the following HTTP frontend information. These HTTP
settings should be set when host information coming from the URL may be
incorrect due to a firewall or proxy.
Frontend Host
Frontend HTTPPort
Frontend HTTPSPort
5.
Click Save.
6.
62-7
63
Creating Customizable Applications
63
Oracle Metadata Services (MDS) framework allows you to create customizable Oracle
Fusion applications. This chapter describes how to configure your application at
design time so that it can be customized by end users.
This chapter includes the following sections:
Some customizations, such as changes to the model or to task flow roles, must be done
from Oracle JDeveloper, as described in the "Using Oracle JDeveloper for
Note:
For more information about customization, see the "Customizing and Extending
Oracle Fusion Applications" chapter in the Oracle Fusion Applications Extensibility Guide
for Developers.
A customized application contains a base application and one or more layers of
customized metadata content. The customized metadata objects are stored in an MDS
repository and, when a customized application is launched, the customized content is
retrieved and applied over the base content. For more information, see the
"Customizing Applications with MDS" chapter in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework and the "Managing the
Metadata Repository" chapter in the Oracle Fusion Applications Administrator's Guide.
When you run your page in JDeveloper, all customizations
created at runtime are, by default, written to a simulated MDS
repository directory, which is stored at a temporary location in your
system directory. The simulated MDS repository that is configured for
the application reflects the metadata information that is contained in
the Metadata Archive (MAR).
Note:
2.
Configure the persistence change manager parameter to use the composer change
manger.
3.
4.
Add Oracle WebCenter Portal Composer technology scope to your project. This
technology scope contains the components that are used for Page Composer
customization.
5.
(Optional) Enable user customization of the user interface (UI) shell template.
6.
database call.
After you complete these steps, you can enable runtime customization for the
application's web pages and task flows as described in Section 63.3, "Enabling Runtime
Customization of Pages and Components."
63.2.1 How to Set Project Properties to Enable User and Seeded Customizations
To enable user customizations, you must configure the view project to persist the
customized metadata objects to an Oracle Metadata Services (MDS) repository so that
the objects are available across sessions. You must also enable seeded customizations
so that the page fragments and JSPX pages that you create will be configured to allow
customizations.
ADF components (such as controller, model, and business
components objects) must have a unique identifier so that they can be
customized. ADF components that are generated by JDeveloper are
created with identifiers by default, except for fragments and pages in
your user interface projects. To cause JDeveloper to generate
identifiers for components on pages that you create in your user
interface projects, you must explicitly specify this at the project level
by enabling seeded customizations.
Note:
In the Project Properties dialog, select ADF View to display the ADF View
settings.
3.
Select Enable User Customizations and select Across Sessions Using MDS, as
shown in Figure 631.
4.
5.
Click OK.
The Persist and Don't Persist attributes that you set for components at design time
will govern which implicit changes that the end users make at runtime will be
persisted during the session as well as across sessions.
The changes that end users make in the design view of Page Composer will be
stored in the MDS repository.
When you enabled user customizations across sessions by completing the procedure in
Section 63.2.1, "How to Set Project Properties to Enable User and Seeded
Customizations," the IDE added the CHANGE_PERSISTENCE context parameter to the
view project's web.xml file, and set the parameter to use the filtered persistence change
manager. You must modify this parameter to use the composer change manager, and
you must add the composer filter and its mapping.
Before you begin:
Modify your view project's properties to enable user customizations across sessions as
described in Section 63.2.1, "How to Set Project Properties to Enable User and Seeded
Customizations."
To configure the persistence change manager:
1. In the Application Navigator, expand the WEB-INF node for your view project
and double-click web.xml.
2.
Add the filter and filter-mapping elements for the WebCenterComposerFilter class
as shown in bold in Example 631.
Note:
1.
JpsFilter
2.
ApplSessionFilter
3.
WebCenterComposerFilter
4.
ADFBindingFilter
Example 631
....
<!-- composerFilter goes here -->
<filter>
<filter-name>composerFilter</filter-name>
<filter-class>
oracle.adf.view.page.editor.webapp.WebCenterComposerFilter
</filter-class>
</filter>
<filter>
<filter-name>adfBindings</filter-name>
<filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class>
</filter>
.....
<!-- composerFilter mapping goes here -->
<filter-mapping>
<filter-name>composerFilter</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
<filter-name>adfBindings</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
....
4.
Enable sessions for the JSPX pages and task flows that you create in your view
project as described in Section 49.2.1, "How to Configure Your Project to Use
Application User Sessions."
This step, among other modifications, adds the Applications Core and Web Service
Data Control libraries to your project, which you need to complete the tasks to
prepare your application for customization.
Note:
3.
Click Add.
4.
Type the following string in the File Name field in the Select Resource Bundle
dialog.
oracle.adf.view.page.editor.resource.ComposerOverrideBundle.xlf
5.
Click Open.
6.
7.
8.
Open the adf-config.xml file, which is located in the Application Resources >
Descriptors > ADF META_INF folder.
9.
Example 632
<pe:page-editor-config>
...
<resource-string-editor>
<enabled>
#{GlobalAreaBackingBean.tipLayerNonUser}
</enabled>
</resource-string-editor>
</pe:page-editor-config>
2.
3.
Add the Oracle WebCenter Portal Composer technology scope to your project
and click OK.
In the Application Navigator, expand the Data Controls hierarchy to locate and
expand the FndUIShellController.
3.
Drag and drop the customizeUIShellTemplate operation onto the page, and
choose Create > Method > ADF Button or choose Create > Method > ADF Link.
4.
In the Edit Action Binding dialog, provide a comma delimited list of fully
packaged qualified customization classes for the custClass parameter, as shown in
Example 633.
Example 633
oracle.apps.fnd.applcore.customization.GlobalCC,oracle.apps.fnd.applcore.customiza
tion.SiteCC
Each of the customization classes supplied in the list must be valid and configured
in the adf-config.xml file, as shown in Figure 632.
Figure 632 adf-config.xml Customization Classes
If any of the classes cannot be instantiated, or if they are not pre-configured in the
adf-config.xml file, an exception is thrown at runtime.
The last customization class specified is the tip customization layer and the
modifications to the UI Shell is written to this layer. In Example 633, the
customization of the UI Shell takes place in SiteCC. The purpose of the earlier
customization in the list is to view the UI Shell with any other customizations
applied.
For information about customization layers, see the "Understanding
Customization Layers" section in the Oracle Fusion Applications Extensibility Guide
for Developers.
5.
Click OK.
6.
7.
8.
Example 634
<bindings>
<methodAction id="custNavigate" RequiresUpdateModel="true"
Action="invokeMethod" MethodName="navigate"
IsViewObjectMethod="false" DataControl="FndUIShellController"
InstanceName="FndUIShellController.dataProvider"
ReturnName=
"FndUIShellController.methodResults.navigate_FndUIShellController_dataProvider_
navigate_result">
<NamedData NDName="viewId" NDValue="TemplateCustomizationUIShell"
NDType="java.lang.String"/>
<NamedData NDName="webApp" NDType="java.lang.String"/>
<NamedData NDName="pageParametersList" NDType="java.lang.String"/>
<NamedData NDName="navTaskFlowId" NDType="java.lang.String"/>
<NamedData NDName="navTaskKeyList" NDType="java.lang.String"/>
<NamedData NDName="navTaskParametersList" NDType="java.lang.String"/>
<NamedData NDName="navTaskLabel" NDType="java.lang.String"/>
<NamedData NDName="methodParameters"
NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>
</bindings>
9.
3.
4.
5.
6.
Click OK.
The database connection appears under the IDE Connections node.
2.
3.
4.
5.
As shown in Figure 633, the settings that you make by following the procedures in
this section affect whether an end user can customize an object under the following
scenarios.
Note:
Wants to Manage
Customizations
Wants to
Customize Page
Can the
components
attribute be
persisted
?
Does
the user have
administrative role
or privilege
?
Does
the user have
administrative role
or privilege
?
Yes
Yes
Yes
Wants to
Personalize Page
Wants to
Reset Page
Is
the page
personalizable
in Page Composer?
(default = false)
Yes
Action appears in
menu. User chooses
action to open tool.
Is
customization
allowed for the page?
(JSPX)
(default =
true)
Yes
Action appears in
menu. User chooses
action to open tool.
Is
the user
authorized to
edit the page or task
flow that holds
the object?
Yes
Is
customization
allowed for
the object?
Yes
Customization
occurs.
2.
Make pages runtime editable by adding Page Composer components to the pages.
Creating Customizable Applications
63-11
3.
If you are enabling the runtime addition of content, set up a resource catalog.
4.
In the Application Navigator, right-click the JSPX page and choose Go to Page
Definition.
2.
If the page does not have a page definition, a Confirm Create New Page Definition
dialog appears. Click Yes to create the page.
2.
Note:
2.
3.
3.
If the Property Inspector is not open, choose Property Inspector from the View
menu.
4.
5.
63-13
For more information about these attributes, see the "Extended Metadata Properties"
section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application
Development Framework.
For information about customization layers, see the "Understanding Customization
Layers" section in the Oracle Fusion Applications Extensibility Guide for Developers.
63.3.4 How to Authorize the Runtime Customization of Pages and Task Flows
As illustrated in Figure 633 a user can edit customizable components in a user
interface page at runtime only if they have permission to edit the page and permission
to edit the task flow that contains the component. For example, an end user can only
customize components in a task flow using Page Composer if that user has permission
to customize the task flow. You use the jazn-data.xml file to define which roles can
edit the page or task flow.
Before you begin:
Enable the desired pages for editing in Page Composer as described in Section 63.3,
"Enabling Runtime Customization of Pages and Components."
To authorize pages and task flows for runtime customizations:
1. In the Application Resources panel, expand Descriptors, expand META-INF
nodes, and then double-click jazn-data.xml.
Tip: If the jazn-data.xml file does not exist, you can create it by
right-clicking the META-INF node, selecting New Oracle
Deployment Descriptor, selecting jazn-data.xml, and then clicking
Finish.
2.
In the overview editor, click the Resource Grants navigation tab, as shown in
Figure 634.
3.
4.
5.
For each Page Composer enabled web page, select the Customize action for each
role for which you want to enable page customization.
You must also authorize customization for the task flows, as described in the
following two steps.
6.
7.
For each task flow, select the Customize action for each role for which you want to
enable customization of the components in the task flow.
8.
If you want the task lists that are exposed in your pages to be customizable for
your application, select the entry for TaskList in the Resources list, and, for each
role for which you want to enable task list customization, select the customize and
grant actions.
For more information, see the "Implementing Task Flow Security" section in the Oracle
Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.
63-15
The attributes that can be persisted are set in the tag library, but you can override these
settings. For example, you might not want the end users to change column widths, but
you want all other default attribute changes for columns to be persisted. You set and
unset these values in the Overview Editor for the adf-config.xml file, as described in
the "Configuring User Customizations" section in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework. You can also override
these settings for specific components, as described in the "Controlling User
Customizations in Individual JSF Pages" section in the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
64
Working with Extensions to Oracle
Enterprise Scheduler
64
This chapter explains how to use extensions to Oracle Enterprise Scheduler to manage
job request submissions in the context of Oracle Fusion Applications. This chapter
includes the following sections:
Section 64.14, "Creating an Oracle ADF User Interface for Submitting Job
Requests"
Section 64.15, "Submitting Job Requests Using the Request Submission API"
Section 64.16, "Defining Oracle Business Intelligence Publisher Postprocessing
Actions for a Scheduled Job"
Section 64.17, "Monitoring Scheduled Job Requests Using an Oracle ADF UI"
Section 64.18, "Using a Task Flow Template for Submitting Scheduled Requests
Through an Oracle ADF UI"
Section 64.19, "Securing Oracle ADF UIs"
Section 64.20, "Integrating Scheduled Job Logging with Oracle Fusion
Applications"
Section 64.21, "Logging Scheduled Jobs and Writing to Output Files"
64-1
Using Oracle JDeveloper, application developers can create and implement jobs. While
implemented in JDeveloper, Oracle Enterprise Scheduler runs the jobs. APIs provide
an interface between jobs executed within applications developed in JDeveloper and
Oracle Enterprise Scheduler.
The Oracle JDeveloper extensions to Oracle Enterprise Scheduler enable the following:
Always use the preconfigured job types provided when defining metadata for job
definitions.
A wizard enables defining a new job within the context of an Oracle Fusion
application. The job can be any one of the following types: Java, PL/SQL, SQL*Loader,
SQL*Plus, Perl, C, or host scripts.
2.
If a job requires parameters to be filled in by end users using an Oracle ADF user
interface, define a standard ADF Business Components view object with
validation.
For example, if a job requires information regarding duration, date, and time,
create an ADF Business Components view object with the properties duration,
date, and time.
3.
4.
5.
6.
64.3.2 What Happens at Runtime: How a Scheduled Job Is Created and Implemented in
JDeveloper
An Oracle ADF interface is provided to enable application end users to submit job
requests from an Oracle Fusion application. The Oracle ADF interface is integrated
into an Oracle Fusion application. As soon as a job request is submitted through the
interface, Oracle Enterprise Scheduler runs the job as scheduled.
Job Definition: This is the basic unit of work that defines a job request in Oracle
Enterprise Scheduler.
Job Type: This specifies an execution type and defines a common set of properties
for a job request.
The extensions to Oracle Enterprise Scheduler provide the following execution types:
64-3
JavaType: for job definitions that are implemented in Java and run in the
container.
SQLType: for job definitions that run as PL/SQL stored procedures in a database
server.
CJobType: for job definitions that are implemented in C and run in the container.
PerlJobType: for job definitions that are implemented in Perl and run in the
container.
SqlLdrJobType: for job definitions that are implemented in SQL*Loader and run
in the container.
SqlPlusJobType: for job definitions that are implemented in SQL*Plus and run in
the container.
BIPJobType: for job definitions that are executed as Oracle BI Publisher reports.
Oracle BI Publisher jobs require configuring the parameter reportID.
For more information about defining an Oracle BI Publisher job, see the Oracle
Fusion Middleware Report Designer's Guide for Oracle Business Intelligence Publisher,
Oracle Fusion Middleware Administrator's Guide for Oracle Business Intelligence
Publisher, and the Oracle Fusion Middleware Developer's Guide for Oracle Business
Intelligence Publisher.
HostJobType: for job definitions that run as host scripts executed from the
command line.
1.
2.
Right-click the project and select Properties. In the Resources tab, add the directory
$MW_HOME/jdeveloper/integration/ess/extJobTypes.
3.
If your job includes any properties to be filled in by end users using an Oracle
ADF user interface at runtime, create an ADF Business Components view object
with validation and the parameters to be filled in by end users.
a.
Right-click the Model project and select Properties. In the Resource Bundle
section, configure one bundle per file and select resource bundle type Xliff
Resource Bundle.
b.
Add the property parametersVO to your job definition and specify the fully
qualified path of the view object as the value of parametersVO. For example,
set parametersVO to oracle.my.package.TestVO. A maximum of 100
attributes can be used for parametersVO. The attributes should be named
incrementally, for example ATTRIBUTE1, ATTRIBUTE2, and so on.
d.
Property
Description
completionText
An optional string value that can be used to communicate details of the final
state of the job.
This property value is displayed in the UI used to monitor job request
submissions in the details section of the job request. It can be useful for
displaying a short explanation as to why a request ended in an error or warning
state.
CustomDatacontrol
The name of the data control for the application to which the parameter task
flow is bound. Following is an example.
<parameter name="CustomDatacontrol"
data-type="string">ExtParameterAM</parameter>
Use this property when adding a custom task flow to an Oracle ADF user
interface used to submit job requests at run time. For more information, see
Section 64.14.2, "How to Add a Custom Task Flow to an Oracle ADF User
Interface for Submitting Job Requests."
defaultOutputExtension
The suffix of the output file. Possible values are txt, xml, pdf, html.
enableTimeStatistics
enableTrace
A numerical value that indicates the level of tracing control for the job. Possible
values are as follows:
1: Database trace
executionLanguage
Stores the preferred language in which the job request should run.
executionNumchar
The numeric characters used in the preferred language in which the job runs, as
defined by executionLanguage.
64-5
Description
executionTerritory
The territory of the preferred language in which the job runs, as defined by
executionLanguage.
EXT_
PortletContainerWebModule
Specifies the name of the web module for the Oracle Enterprise Scheduler UI
application to use as a portlet when submitting a job request. The Oracle
Enterprise Scheduler central UI looks up the producer from the topology based
on the registered producer application name derived from EXT_
PortletContainerWebModule.
Description
incrementProc
Enables a PL/SQL procedure evaluated at runtime which calculates the next set
of date parameter values for a recurring request. Enter the name of the PL/SQL
procedure. The procedure expects one argumenta number signifying the
change in milliseconds between the start dates of the first and current requests.
-- incr_test - Sample PL/SQL incrementProc procedure
-- This procedure gets the list of arguments to be incremented
-- using the incrementProcArgs property and increments each
-- argument by the delta provided. This behavior is identical
-- to the default behavior if no incrementProc is set for the
-- job.
procedure incr_test(
delta IN number ) is
request_id number;
incrProcArgs varchar2(200);
curr_arg_n varchar2(100);
curr_arg_v varchar2(2000);
del_pos number := 0;
prev_pos number := 1;
old_date date;
new_date date;
delta_days number;
begin
request_id := FND_JOB.REQUEST_ID;
delta_days := delta / (1000*60*60*24);
-- incrProcArgs must be defined for this procedure to be
-- called.
incrProcArgs := ESS_RUNTIME.GET_REQPROP_VARCHAR(request_id,
FND_JOB.INCR_PROC_ARGS_P) || ',';
LOOP
del_pos := INSTR(incrProcArgs, ',', prev_pos);
EXIT WHEN del_pos = 0;
curr_arg_n := FND_JOB.SUBMIT_ARG_PREF_P || SUBSTR(incrProcArgs,
prev_pos, del_pos-prev_pos);
curr_arg_v := ESS_RUNTIME.GET_REQPROP_VARCHAR(request_id,
curr_arg_n);
old_date := FND_DATE.CANONICAL_TO_DATE(curr_arg_v);
new_date := old_date + delta_days;
ESS_RUNTIME.UPDATE_REQPROP_VARCHAR(request_id, curr_arg_n,
FND_DATE.DATE_TO_
CANONICAL(new_date));
prev_pos := del_pos+1;
END LOOP;
end incr_test;
64-7
Description
incrementProcArgs
logLevel
The level at which events are logged (between 0 and 4). Each job type has a
logLevel of 1 by default. This optional value is used to override the job type
logLevel in the job definition. For more information about log levels, see the
Oracle Fusion Middleware Developer's Guide for Oracle Enterprise Scheduler.
optimizerMode
This flag enables setting the database optimizer mode for the job. Optimizer
mode is useful for fine-tuning performance.
parametersVO
The ADF Business Components view object you define for additional properties
to be entered at runtime by end users using an Oracle ADF user interface.
ParameterTaskflow
Enter the name of the task flow as a parameter. The name of the taskflow.xml
file must be the same as the taskflowId. Following is an example.
<parameter name="ParameterTaskflow"
data-type="string">/WEB-INF/oracle/apps/prod/project/ParamTestTaskFlo
w.xml#ParamTestTaskFlow</parameter>
Use this property when adding a custom task flow to an Oracle ADF user
interface used to submit job requests at run time. For more information, see
Section 64.14.2, "How to Add a Custom Task Flow to an Oracle ADF User
Interface for Submitting Job Requests."
reportID
rollbackSegment
Enables setting a database rollback segment for the job, which will be used until
the first commit. When implementing the rollback segment, use FND_JOB.AF_
COMMIT and FND_JOB.AF_ROLLBACK to commit and rollback.
srsFlag
A Boolean parameter (Y or N) that controls whether the job displays in the job
request submission user interface (see Section 64.14, "Creating an Oracle ADF
User Interface for Submitting Job Requests").
SYS_runasApplicationID
Enables elevating access privileges for completing a scheduled job. For more
information about elevating access privileges for the completion of a particular
job, see Section 64.13, "Elevating Access Privileges for a Scheduled Job."
4.
Create a new job. From the New Gallery, select Business Tier > Enterprise
Scheduler Metadata and click Job Definition.
5.
In the Job Definition Name & Location page in the Job Definition Creation wizard,
do the following:
Edit the following properties in the job definition as required for the selected job
type:
JavaJobType: Uncheck the read-only checkbox next to className and set its
value to the value of the business logic class.
PlsqlJobType: Uncheck the read-only checkbox next to procedureName and set
its value to the name of the procedure (such as myprocedure.proc). Create a
new parameter named numberOfArgs. Set numberOfArgs to the number of job
submission arguments, excluding errbuf and retcode.
CJobType: Add the parameter executableName and set its value to the name
of the C job to be executed. The executable file identified by the
executableName parameter must exist in the directory $APPLICATIONS_
BASE/$APPLBIN.
PerlJobType: Add the parameter executableName and set its value to the
name of the Perl script.
SqlLdrJobType: Add the parameter executableName and set its value to the
name of the control file to be executed (located under PRODUCT_TOP/$APPLBIN).
Add SQL*Loader options such (such as direct=yes) as a sqlldr.directoption
parameter in the job definition.
SqlPlusJobType: Add the parameter executableName and set its value to the
name of the SQL*Plus job script to be executed (located under PRODUCT_
TOP/$APPLSQL).
HostJobType: Add the parameter executableName and set its value to the
name of the host script job to be executed. The executable file identified by the
executableName parameter must exist in the directory PRODUCT_TOP/$APPLBIN.
Configure the $APPLBIN and $APPLSQL variables in the
environment.properties file. The $APPLBIN and $APPLSQL variables
point to the location of executable files under PRODUCT_TOP. These
variables enable the extensions to Oracle Enterprise Scheduler to
locate the jobs to be run. Typically, these variables are set in a
preexisting environment properties file in the system.
Note:
64-9
Fusion Middleware Administrator's Guide for Oracle Business Intelligence Publisher, and the
Oracle Fusion Middleware Developer's Guide for Oracle Business Intelligence Publisher.
To define file group properties:
1. In the job definition for which you want to define postprocessing, define a file
group.
a.
b.
Example 641
Example 642
File Group Regular Expression Filtering for All Files with the Suffix XML
MYXML = '.*.\xml$'
Example 643
ALL = '.*$'
Example 644
File Group Regular Expression Filtering for All Files with the Suffix PDF
PDF = '.*.\pdf$'
Optionally, rename the file group and store it in the Oracle Metadata Service
repository so that it displays in a more user-friendly way in the scheduled job
request submission UI.
ATGPF_TOP: The TOP directory for ATGPF files, needed to locate key files for
SQL*Plus and Perl jobs.
OUTPUT_WORK_DIR: The directory to which the job writes all output files.
LOG_WORK_DIR: The directory to which the job writes all log files.
INPUT_WORK_DIR: The directory to which input files are saved before the job is
spawned.
USER_NAME: The name of the user submitting the job. The job runs in the context of
this user.
REQUEST_HANDLE: The Oracle Enterprise Scheduler request handle for the current
request.
The environment variables must point to the client ORACLE_HOME and environment so
that spawned jobs can connect to the database.
LD_LIBRARY_PATH
ORACLE_HOME
3.
TNS_ADMIN: The directory which stores files related to the database connection
(such as tnsnames.ora, sqlnet.ora).
TWO_TASK: The TNS name identifying the database to which spawned jobs
should connect. In Windows environments, the environment variable is LOCAL.
Configure the following variables, which are required to locate spawned jobs:
4.
PATH: The full path of the spawned job. In Windows environments, the PATH
must include all directories that are typically part of LD_LIBRARY_PATH.
Creating a Wallet
cd $TNS_ADMIN
mkdir wallet
mkstore -wrl ./wallet -create
2.
3.
Example 647
5.
In a text editor, create a file called sqlnet.ora that includes the lines shown in
Example 648.
Example 648
SQLNET.WALLET_OVERRIDE = TRUE
WALLET_LOCATION =
(SOURCE =
(METHOD = FILE)
(METHOD_DATA =
(DIRECTORY = <$TNS_ADMIN>/wallet)
)
)
6.
In a text editor, create a file called tnsnames.ora that includes the lines shown in
Example 649.
Example 649
dbname =
(DESCRIPTION =
(ADDRESS =
(PROTOCOL = TCP)
(HOST = host.example.com)
(PORT = 1521)
)
(CONNECT_DATA = (SID-sidname))
)
7.
The first command enables anyone to read and execute files in the directory, while
reserving write access to the directory creator.
The second command enables only the file owner to read, write and execute the
file, while anyone can read the file.
8.
Test the wallet by connecting to it. Execute the following command as shown in
Example 6411.
Moves all the properties available in the properties file of the testing
environment to the same file of the production environment.
Generates the MovePlan.xml file, whose values can be modified as required for
the production environment.
Make sure the Oracle Enterprise Scheduler plug-in JAR and the registration XML
file are located under <MW_HOME>/Oracle_atgpf/clone/provision.
3.
4.
At the command line, execute the copyConfig script after entering the names of all
the servers in the domain or cluster, as shown.
copyConfig.sh -javaHome /usr/local/packages/jdk16/ -archiveLocation
/machine/user/11gWLS/DIST/a.jar
-sourceDomainLoc /machine/user/11gWLS/user_projects/domains/mydomain
-sourceMWHomeLoc /machine/user/11gWLS
-domainHostName hostname.host.com -domainPortNo 8001 -domainAdminUserName
weblogic
-domainAdminPassword /machine/user/11gWLS/wlsPassword.txt -silent true
At the command line, execute the extractPlans script as shown in the following
example.
Working with Extensions to Oracle Enterprise Scheduler 64-15
This script extracts the MovePlan.xml file from the archive to the planDirLocation.
The extracted XML document contains environment.properties entries within
the movableComponent of type ESS-EXT.
6.
7.
At the command line, execute the pasteConfig script to recreate the target
environment. This step configures the data sources, LDAP, and so on, and starts
the servers. Following is an example.
pasteConfig.sh -javaHome /usr/local/packages/jdk16/ -archiveLocation
/machine/user/11gWLS/DIST/a.jar
-targetDomainLoc /machine/user/11gWLS/user_projects/domains/domain9
-targetMiddlewareHomeLoc /machine/user/11gWLS
-movePlanLocation /machine/user/11gWLS/EXTRACT/moveplan.xml -logDirLoc /tmp
-silent true
1.
2.
3.
The errbuf is logged when a job request ends in a warning or error state to
provide a quick indication as to why the job request ended in an error or
warning state.
Job submission arguments, as collected from the view object associated with the
job as configured in the job definition. The view object is used to present a
user interface to end users, allowing them to enter the properties listed in
the following lines of code.
interface. These values are submitted by the end user.
run_mode
duration
p_num
p_date
p_varchar
in
in
in
in
in
varchar2
varchar2
varchar2
varchar2
varchar2
default
default
default
default
default
'BASIC',
'0',
NULL,
NULL,
NULL) is
begin
-- Write log file content using FND_FILE API
FND_FILE.PUT_LINE(FND_FILE.LOG, "About to run the sample program");
-- Implement the business logic
-FND_FILE.PUT_LINE(FND_FILE.OUT,
FND_FILE.PUT_LINE(FND_FILE.OUT,
FND_FILE.PUT_LINE(FND_FILE.OUT,
FND_FILE.PUT_LINE(FND_FILE.OUT,
FND_FILE.PUT_LINE(FND_FILE.OUT,
The sample shown in Example 6414 illustrates a PL/SQL job with a subrequest
submission. The no_requests argument identifies the number of subrequests that
must be submitted.
Example 6414 Submitting a Subrequest Using the PL/SQL Runtime API
procedure fusion_plsql_subreq_sample(
errbuf
out NOCOPY varchar2,
retcode
out NOCOPY varchar2,
no_requests in varchar2 default '5',
) is
req_cnt number := 0;
sub_reqid number;
submitted_requests varchar2(100);
request_prop_table_t jobProp;
begin
-- Write log file content using FND_FILE API
FND_FILE.PUT_LINE(FND_FILE.LOG, "About to run the sample program with
subrequest functionality");
-- Requesting the PAUSED_STATE property set by job identifies request as
-- having started for the first time or restarting after being paused.
if ( ess_runtime.get_reqprop_varchar(fnd_job.job_request_id, 'PAUSED_
STATE') ) is null ) -- first time start
then
-- Implement the business logic of the job here.
FND_FILE.PUT_LINE(FND_FILE.OUT, " About to submit subrequests : " || no_
requests);
-- Loop through all the subrequests.
for req_cnt 1..no_requests loop
-- Retrieve the request handle and submit the subrequest.
sub_reqid := ess_runtime.submit_subrequest(request_handle => fnd_
job.request_handle,
definition_name => 'sampleJob',
definition_package => 'samplePkg',
props => jobProp);
submitted_requests := sub_reqid || ',';
end loop;
-- Pause the parent request.
ess_runtime.update_reqprop_varchar(fnd_job.request_id, 'STATE', ess_
job.PAUSED_STATE);
-- Update the parent request with the state of the subrequest, enabling
-- the job to retrieve the status during restart.
ess_runtime.update_reqprop_int(fnd_job.request_id, 'PAUSED_STATE',
submitted_requests);
else
-- Restart the request, retrieve job completion status and return the
-- status to Oracle Enterprise Scheduler.
errbuf := fnd_message.get("FND", "COMPLETED NORMAL");
retcode := 0;
end if;
end;
FND_JOB.SUCCESS_V: Success.
FND_JOB.WARNING_V: Warning.
FND_JOB.FAILURE_V: Failure.
FND_FILE routines: Can be used for producing log data and output files.
FND_JOB API for request values: API calls are initialized for SQL*Plus jobs.
Note:
2.
3.
4.
varchar2(240) := NULL;
boolean;
varchar2(200) := '&1';
BEGIN
DBMS_OUTPUT.PUT_LINE(run_mode);
update dual set dummy = 'Q';
FND_FILE.PUT_LINE(FND_FILE.LOG, 'Parameter 1 = ' || nvl(run_mode,'NULL'));
/*
/*
/*
FND_FILE.PUT_LINE(FND_FILE.LOG,
');
FND_FILE.PUT_LINE(FND_FILE.LOG,
-----------------------');
FND_FILE.PUT_LINE(FND_FILE.LOG,
');
FND_FILE.PUT_LINE(FND_FILE.LOG,
-----------------------');
FND_FILE.PUT_LINE(FND_FILE.LOG,
');
64-20 Developer's Guide
*/
*/
*/
'
'----------------------------------------'Printing a message to the LOG FILE
'----------------------------------------'SUCCESS!
FND_FILE.PUT_LINE(FND_FILE.LOG,
'
');
FND_FILE.PUT_LINE(FND_FILE.OUTPUT,'---------------------------------------------------------------');
FND_FILE.PUT_LINE(FND_FILE.OUTPUT,'Printing a message to the OUTPUT FILE
');
FND_FILE.PUT_LINE(FND_FILE.OUTPUT,'---------------------------------------------------------------');
FND_FILE.PUT_LINE(FND_FILE.OUTPUT,'SUCCESS!
');
FND_FILE.PUT_LINE(FND_FILE.OUTPUT,'
');
retval :=
FND_JOB.SET_SQLPLUS_STATUS(FND_JOB.SUCCESS_V);
END;
/
COMMIT;
-- EXIT; Oracle Fusion Applications
TERM OFF
PAUSE OFF
HEADING OFF
FEEDBACK OFF
VERIFY OFF
ECHO OFF
ESCAPE ON
The Oracle Fusion application calls Oracle Enterprise Scheduler using the provided
APIs. Oracle Enterprise Scheduler runs the job, and the final job statusSUCCESS,
WARNING, BUSINESS ERROR, or FAILUREis communicated to Oracle Enterprise
Scheduler. The Oracle Fusion web application can retrieve the result from Oracle
Enterprise Scheduler and display it in the user interface.
Place control files in the $APPLBIN directory under the product TOP. (Subrequests
using dynamic control files must instead access the working directory of the
parent job request.)
The control file's name must be the same as the executableName parameter in the
job definition.
Ensure that the full path of the data file's location is the first submit argument to
the job.
Add SQL*Loader options such as direct=yes, if needed, as the
sqlldr.directoption parameter in the job definition.
Set the job log file as the SQL*Loader LOG parameter so it will automatically
contain all SQL*Loader log messages.
Set the job output file as the SQL*Loader BAD parameter so it will automatically
receive any output directed there. Alternatively, you can create two output files for
a SQL*Loader job request.
In the parent job request, make sure you have set the system property
workDirectoryRoot to the working directory of the parent job request.
3.
Alternatively, in the case of SQL*Loader subrequests only, configure the job to use
a dynamically created control file.
a.
In the job definition for the subrequest, configure the property execPRWD. Set
this property to Y to enable the dynamic control file.
b.
In the parent job request, configure the name of the control file using the
executableName system property.
4.
Enter the full path of the data file as the first submit argument to the job.
5.
Store the control file under PRODUCT_TOP/$APPLBIN. Skip this step if you are
implementing a SQL*Loader subrequest.
6.
7.
This sample control file will upload data from the data file into the fnd_applcp_test
table, into the columns listed here (id1, id2, idn, mesg). See the SQL*Loader
documentation For more information about writing control files.
OPTIONS (silent=(header,feedback,discards))
LOAD DATA
INFILE *
INTO TABLE fnd_applcp_test
APPEND
FIELDS TERMINATED BY ','
(id1,
id2,
id3,
func CHAR(30),
time SYSDATE,
action CHAR(30),
mesg CHAR(240))
3.
Create a job definition for the Perl job, setting the executableName parameter to
the name of the Perl script. The following functions can be used in the Perl script:
4.
5.
Implement an exit code for the job, with values of 0, 2 or 3 representing the
following states: success, warning, and business error. All other values represent
an errored state.
6.
2.
Prints arguments.
3.
4.
Retrieves contextual information about the scheduled job request, which is stored
in the context object.
5.
6.
print_header("Arguments");
my $i = 1;
foreach (@ARGV) {
print "Argument #", $i++, ": $_\n";
}
# -- Get the request context object
my $context = get_context();
# -- Use this object to retrieve context information about this request
print_header("Context Information");
printf "Request id \t= %d\n", $context->reqid();
printf "User name \t= %d\n", $context->username();
printf "Logfile \t= %s\n", $context->logfile();
printf "Outfile \t= %s\n", $context->outfile();
# -- Writing to the request log file
print_header("Writing to log file");
# -- retrieve a Logfile object from the context
my $log = $context->log();
$log->writeln("This message should appear in the request logfile");
$log->timestamp("This is a timestamped message to the request logfile");
print "Wrote two messages to the request logfile\n";
# -- Print out some useful information
print_header("Environment");
foreach (sort keys %ENV) {
print "$_=$ENV{$_}\n";
}
print_header("Perl Information");
print "PROCESS ID = $$\n";
print "REAL USER ID = $<\n";
print "EFF USER ID = $>\n";
print "SCRIPT NAME = $0\n";
print "PERL VERSION = $]\n";
print "OS NAME = $^O\n";
print "EXE NAME = $^X\n";
print "WARNINGS ON = $^W\n";
print "\n\@INC path:\n";
foreach (@INC) {
print "$_\n";
}
print "\nAll loaded perl modules:\n";
foreach (sort keys %INC) {
print "$_ => $INC{$_}\n";
}
#
#
#
#
#
#
-------
afstd.h and afstr.h: These are Oracle Fusion application header files.
2.
3.
In the main function, call afprcp, passing to it a pointer to the business logic
function.
The business logic function is called by afprcp, taking the arguments argc, argv,
and reqinfo.
4.
5.
Table 642
Function
Description
afprcp
Run C program. The recommended API for writing a C program. The main OC
file should call this function to run the program logic. It initializes the context
and calls the program.
int afprcp (uword argc, text **argv, afsqlopt *options, afpfcn
*function);
afpend
End C program. All programs must call this to signal the completion of the
program. The program should pass completion status and message if necessary.
Indicate completion status with the following constants:
FDP_SUCCESS: Success
FDP_WARNING: Warning
Find request status. For a given request, retrieve the status. The following are
possible request states:
ESS_WAIT_STATE
ESS_READY_STATE
ESS_RUNNING_STATE
ESS_COMPLETED_STATE
ESS_BLOCKED_STATE
ESS_HOLD_STATE
ESS_CANCELLING_STATE
ESS_EXPIRED_STATE
ESS_CANCELLED_STATE
ESS_ERROR_STATE
ESS_WARNING_STATE
ESS_SUCCEEDED_STATE
ESS_PAUSED_STATE
ESS_PENDING_VALID_STATE
ESS_VALID_FAILED_STATE
ESS_SCHEDULE_ENDED_STATE
ESS_FINISHED_STATE
ESS_ERROR_AUTO_RETRY_STATE
ESS_MANUAL_RECOVERY_STATE
Table 642 (Cont.) C Functions Available for Developing Oracle Fusion Applications
Function
Description
fdpgret
Get the error type of a specific job request ID. The following are possible error
types:
ESS_UNDEFINED_ERROR_TYPE
ESS_SYSTEM_ERROR_TYPE
ESS_BUSINESS_ERROR_TYPE
ESS_TIMEOUT_ERROR_TYPE
ESS_MIXED_NON_BUSINESS_ERROR_TYPE
ESS_MIXED_BUSINESS_ERROR_TYPE
fdpgrs
Lock table. Locks the desired table with the specified lock mode and NOWAIT.
fdpscp
Legacy API for concurrent programs. All new concurrent programs should use
afprcp.
boolean fdpscp (sword *argc, text **argv[], text args_type, text
*errbuf);
Routines for creating log/output files and writing to files. These are routines
concurrent programs should use for writing to all log and output files.
fdpwrt
Table 643
Function
Description
fdpgoi
fdpgpn
fdpgrc
fdpimp
fdpldr
Run SQL*Loader.
fdpperl
fdprep
Run report.
fdprpt
fdprsg
fdpscr
fdpsql
fdpstp
Use the syntax shown in Example 6419 to run a C job from the command line for
testing purposes.
Example 6419 Syntax for Running a C Job from the Command Line
%program <heavyweight user connection string> <lightweight username> <flag> <job
parameters> ...
where
<heavyweight user connection string> is the username/password@TWO_TASK
pair used to connect to the database
<lightweight user name> is the name of the lightweight user submitting the job.
This value is used to set the user context in the database connection.
<flag> must be set to 'L' for lightweight user.
An example illustrating running a C job from the command line is shown in
Example 6420.
Example 6420 Running a C Job from the Command Line for Testing Purposes
program username/password@my_db MYUSER L <parameter1> <parameter2> ....
#ifndef FDS
#include <fds.h>
#endif
boolean testupi()
{
text *sqltext;
text buffer[ERRLEN];
text os_user[31];
text session_user[31];
text db_name[31];
aucursor
word
*use_curs;
errcode;
return TRUE;
upierror:
if (use_curs != NULLCURSOR)
DISCARD afurelease (use_curs);
DISCARD fdpwrt(AFWRT_LOG | AFWRT_NEWLINE, "Error in testupi");
return FALSE;
}
void testrpc()
{
text buffer[256];
VARCHAR session_user[31];
VARCHAR db_name[31];
EXEC SQL END DECLARE SECTION;
buffer[0] = os_user.arr[0] = session_user.arr[0] = db_name.arr[0] = '\0';
EXEC SQL SELECT sys_context('USERENV','DB_NAME',30),
sys_context('USERENV','SESSION_USER',30),
sys_context('USERENV','OS_USER',30)
INTO :db_name, :session_user, :os_user
from dual;
nullterm(os_user);
nullterm(session_user);
nullterm(db_name);
DISCARD sprintf((char *)buffer, "%s as %s@%s", os_user.arr,
session_user.arr, db_name.arr);
DISCARD fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, buffer);
}
sword cptest(argc, argv, reqinfo)
/* ARGSUSED */
sword argc;
text *argv[];
dvoid *reqinfo;
{
ub2 i;
text errbuf[ERRLEN+1];
/* Write to the log file */
DISCARD fdpwrt(AFWRT_LOG | AFWRT_NEWLINE, (text *)"Test Success");
/* Write to the out file */
DISCARD fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, (text *)"Test Args:");
/* Loop through argv and write to the out file. */
for ( i=0; i<argc; i++)
DISCARD fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, argv[i]);
/* Call the Oracle Fusion Applications function afpoget to return the value */
/* of a profile option called SITENAME and write the results to the error */
/* buffer. */
DISCARD afpoget((text *)"SITENAME", errbuf);
/* Write the value to the output file. */
DISCARD fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, errbuf);
/* Connect to the database and run a SELECT against the database. Creates a */
/* string and writes the returned data to the output file. Uses prc APIs. */
testrpc();
/* Open a cursor for the SELECT statement, defines variables to collect data */
/* upon running statement, and executes SELECT. Creates a string which it */
/* writes to the output file. Uses afupi APIs. */
testupi();
/* Writes the string "Test Completed." to the output file. */
DISCARD fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, (text *)"Test Completed.");
/* Call afpend to identify the exit status, which in this case is successful. */
/* Other possible values are FDP_WARNING, FDP_ERROR and FDP_BIZERR. The
/* reqinfo originally passed to cptest is passed here. Optionally, additional */
/* text can be passed here, for example explaining the outcome of the exit */
/* status. */
return((sword)afpend(FDP_SUCCESS, reqinfo, (text *)NULL));
};
Complete the steps for configuring a spawned job as described in Section 64.5,
"Configuring a Spawned Job Environment."
Create one script file each for Unix and Windows platforms. Name each script file
the same as executableName parameter in the job definition. For example, if your
executableName is "myscript", the script files would be called myscript.sh (on
Unix platforms) and myscript.cmd (on Windows).
Put host scripts in the $APPLBIN directory under the product TOP.
The script should exit with one of the following exit codes (anything else is
considered a SYSTEM ERROR):
0 for SUCCESS
2 for WARNING
oracle.as.scheduler.Cancellable;
oracle.as.scheduler.Executable;
oracle.as.scheduler.ExecutionCancelledException;
oracle.as.scheduler.ExecutionErrorException;
oracle.as.scheduler.ExecutionPausedException;
oracle.as.scheduler.ExecutionWarningException;
oracle.as.scheduler.RequestExecutionContext;
oracle.as.scheduler.RequestParameters;
1.
2.
3.
In the text field for the SYS_runasApplicationID property, enter the application ID
under which you want to run the job, as shown in Figure 641.
The input string must be a valid ApplicationID value that exists when the job
executes.
You can retrieve the executing user by running either of the methods shown in
Example 6423 and Example 6424.
Example 6423 Retrieving the Executing User with getRunAsUser()
requestDetail.getRunAsUser()
Given a request ID, you can retrieve the submitting and executing users of a job
request.
To retrieve the submitting and executing users of a job request in Oracle
Enterprise Scheduler RuntimeService Enterprise JavaBeans object:
Example 6425 shows a code sample for retrieving the submitting and executing
users of a job request using the Oracle Enterprise Scheduler RuntimeService
Enterprise JavaBeans object.
Example 6425 Retrieving the Submitting and Executing Users of a Job Request Using
the RuntimeService Enterprise JavaBeans Object
// Lookup runtimeService
RequestDetail requestDetail = runtimeService.getRequestDetail(h, reqid);
String runAsUser = requestDetail.getRunAsUser();
String submitter = requestDetail.getSubmitter();
To retrieve the submitting and executing users of a job request from within an
Oracle Fusion application:
Example 6426 shows a code sample for retrieving the submitting and executing
users of a job request from within an Oracle Fusion application.
Example 6426 Retrieving the Submitting and Executing Users of a Job Request from
an Oracle Fusion application
import oracle.apps.fnd.applcore.common.ApplSessionUtil;
// The elevated privilege user name.
ApplSessionUtil.getUserName()
// The submitting user.
ApplSessionUtil.getHistoryOverrideUserName()
2.
Retrieves the application identity information from the job metadata. If the job
metadata does not specify an application identity for the job, Oracle Enterprise
Scheduler executes the job in the context of the job submitter.
Java job: An FND session is established as the user with elevated privileges.
The executing user is taken from the current subject as viewed from the job
logic.
Oracle Enterprise Scheduler does not directly support
invoking a web service or composite. If your job logic invokes a web
service or composite, you must write the client code logic in your job,
establish a connection and propagate the job submitter information as
data for auditing purposes. For an asynchronous web service call, the
job must wait for a response.
Note:
3.
64.13.3 What Happens When Access Privileges Are Elevated for a Scheduled Job
Oracle Enterprise Scheduler validates the user's execution privileges on the job
metadata. If so, the user context is captured and stored in the Oracle Enterprise
Scheduler database as the submitting user, and the request is placed in the queue.
64.14 Creating an Oracle ADF User Interface for Submitting Job Requests
When implemented as part of an Oracle Fusion application, the Oracle ADF user
interface enables end users to submit job requests.
64.14.1 How to Create an Oracle ADF User Interface for Submitting Job Requests
The Oracle ADF UI enables end users to submit job requests. End users can enter
complex data types for the arguments of descriptive and key flexfields. The
Parameters tab in the Oracle ADF UI interface allows end users to enter parameters to
be used when submitting the job request.
Flexfields display in a separate task flow region. This region is a child task flow of the
parent task flow displayed in the Parameters tab.
Define customization layers and authorize runtime
customizations to the adf-config.xml file as described in Chapter 63,
"Creating Customizable Applications."
Note:
Right-click the Model project and select Project Properties > Libraries and
Classpath > Add Library.
3.
From the list, select the following libraries, as shown in Figure 642.
Applications Core
Right-click the View Controller project and select Project Properties > Libraries
and Classpath > Add Library.
Add the library Applications Core (ViewController), as shown in Figure 643.
5.
6.
The Initialize Business Components Project window displays. Click the Edit icon
to create a database connection for the project.
Fill in the database connection details as follows:
User name/Password: Fill in the relevant user name and password for the
database.
Driver: thin
Click OK.
7.
8.
oracle.applcp.model
oracle.applcp.runtime
oracle.ess
oracle.xdo.runtime
oracle.xdo.service.client
oracle.xdo.webapp
Create a new Java Server Pages XML (JSPX) page for the ViewController project by
right-clicking ViewController and selecting New > Web Tier >JSF > JSF JSP Page.
10. Create a new File System connection. In the Resource Palette, right-click File
Provide a connection name and directory path for the Oracle ADF Library files
(<jdev_install>/jdev/oaext/adflib).
b.
11. Expand the contents of the SRS-View.jar file to display the list of available task
12. To include the job request submission page in the application, select the
ScheduleRequest-taskflow item from the Resource Palette and drop it onto the
Java Server Faces (JSF) page in the area where you want to create a call to the task
flow. Create the task flow call as a link or button.
For example, to invoke the job request submission page from within a dialog in the
application, do the following:
a.
From the Component Palette, drag and drop a Link onto the form in the JSPX
page.
b.
In the Property Inspector, configure the behavior of the link to the value
showpopup.
c.
From the Component Palette, drag and drop a Popup component with a
dialog component onto the form.
d.
Figure 645 Including the Job Request Submission Page in the Application
e.
13. When prompted, add the required library to the ViewController project by clicking
b.
c.
centralui: When setting this parameter to true, then the task flow UI does
not display the header section containing the name, description and basic
Oracle BI Publisher actions (such as email, print and notify). This parameter
must be a Boolean value. Optional.
d.
pageTitle: When passed, the task flow will render this passed String value as
the page title. The pageTitle value is currently configured to be truncated at
30 characters. Optional.
e.
requireRootOutcome: If true is passed as the value, then the task flow will
generate a value of root-outcome when the user clicks the Submit or Cancel
buttons. By default, the task flow generates a value of parent-outcome.
Optional.
f.
names and values are parameter values. For example, if you will be using a
paramsMap object in the pageFlowScope context, you might enter a
requestparametersmap value of #{pageFlowScope.paramsMap}. Optional.
In the page that holds the task flow region in the job request submission page,
set the following property for the popup window that opens the job request
submission page window: contentDelivery = immediate.
In the page definition file of the page that contains the task flow region, set the
following property for the task flow: Pagedef > executables > taskflow >
Refresh=IfNeeded.
15. If you are using a map to pass parameters to the task flow (as shown in
Figure 646, the map is called requestparametersmap), create a new task flow
parameter, such as the paramsMap object in the pageFlowScope element of a page
flow.
Figure 646 Defining Parameters for the Task Flow
These values can be accessed in the job executable, for example from the
RequestParameters object in the case of a Java job. Example 6427 illustrates
passing the values stored in the RequestParameters object to a Java job. This code
is used in the class that implements the oracle.as.scheduler.Executable
interface.
Example 6427 Passing Values in a Map Object to a Java Job
public void execute(RequestExecutionContext ctx,RequestParameters props)
throws ExecutionErrorException, ExecutionWarningException,
ExecutionCancelledException,ExecutionPausedException
{
String pageTitle = (String) props.getValue("pageTitle");
// Retrieve other parameters.
// ...
}
Note:
16. If the job is defined with properties that must be filled in by end users, the user
interface allows end users to fill in these properties before submitting the job
request. For example, if the job requires a start and end time, end users can fill in
the desired start and end times in the space provided by the user interface.
The properties that are filled in by end users are associated with a view object,
which in turn is associated with the job definition itself. When the job runs, Oracle
Enterprise Scheduler accesses the view object to retrieve the values of the
properties.
If using a view object to pass parameters to the job definition, do the following:
a.
Create a view object called TestVO using a query such as the one shown in
Example 6428.
Specify control UI hints, for example set the display label for Attribute1 to
Run Mode and for Attribute2 to Duration.
The parameters tab in the job request submission UI renders with the input
fields Run Mode and Duration.
c.
To render the Parameters tab in the job request submission UI, add the
DynamicComponents 1.0 library as follows. Right-click ViewController and
select Project Properties > JSP Tag Libraries > Add. In the Choose Tag
Libraries window, select the library DynamicComponents 1.0 and click OK.
Figure 647 displays the Choose Tag Libraries window.
17. In the JSF application you created, create another project called Scheduler. Select
File > New, and choose General > Empty Project. This project will be used to
create Oracle Enterprise Scheduler metadata and job implementations.
18. In the Scheduler project, add the Oracle Enterprise Scheduler Extensions library to
the class path. Right-click the Scheduler project and select Project Properties >
Libraries and Classpath > Add Library > Oracle Enterprise Scheduler Extensions.
19. Deploy the libraries oracle.xdo.runtime and oracle.xdo.webapp to the Oracle
Note:
64.14.2 How to Add a Custom Task Flow to an Oracle ADF User Interface for Submitting
Job Requests
You can add a custom task flow to an Oracle ADF user interface used to submit job
requests at run time.
To add a custom task flow to an Oracle ADF user interface for submitting job
requests:
1. Create a task flow and bind it to your Oracle ADF user interface for submitting a
job request created in Section 64.14.1, "How to Create an Oracle ADF User
Interface for Submitting Job Requests."
For more information about creating task flows and binding them to an Oracle
ADF user interface, see the following chapters in Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework:
2.
Create an ADF Business Components view object for each UI field. Name the view
objects that are bound to UI fields ParameterVO1, ParameterVO2, and so on.
Name the attributes of the view objects as follows: ATTRIBUTE1, ATTRIBUTE2, and
so on.
For more information about creating an ADF Business Components view object,
see the chapters "Defining SQL Queries Using View Objects" and "Advanced View
Object Techniques" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle
Application Development Framework.
3.
Include the view objects in the relevant application module. Even if their names
are different, the view object instance names ought to be ParameterVO1,
ParameterVO2, ParameterVO3, and so on.
4.
5.
64.14.3 How to Enable Support for Context-Sensitive Parameters in an Oracle ADF User
Interface for Submitting Job Requests
After integrating your application with the Oracle ADF UI for submitting job requests,
enable context-sensitive parameter support in the UI.
The request submission UI will render the context-sensitive parameters first so that the
end user will specify the context-sensitive parameter values. Context is set in the
database based on these parameters. After setting the context, it renders the rest of the
parameters based on context set at database layer. When the job runs, the actual
business logic will run after setting the context based on the context-sensitive
parameter values inside the database.
Working with Extensions to Oracle Enterprise Scheduler 64-45
3.
4.
Specify the parameters shown in Example 6429 and Example 6430 in the job
definition metadata.
contextParametersVO: Enter the fully qualified name of the view object that
holds the context sensitive parameters.
setContextAPI: PL/SQL API to set the context, along with the package name.
The _myPkg1.mySetCtx procedure receives arguments based on attributes in
the contextParametersVO.
data-type="string">_myPkg1.mySetCtx</parameter>_
64.14.4 How to Save and Schedule a Job Request Using an Oracle ADF UI
Saving and scheduling a job request using an Oracle ADF UI involves using the Oracle
Enterprise Scheduler Extensions library with a JSF application that includes a task
flow in which a job is scheduled and saved.
To schedule a job request using an Oracle ADF UI:
1. Follow the instructions in Section 64.14.1, "How to Create an Oracle ADF User
Interface for Submitting Job Requests" up to step 9.
If the custom parameters task flow has no transactions of its
own, it must set the data-control-scope to isolated. This ensures
that multiple parametersVO properties using the same application
module get their independent application module instance.
Note:
2.
Drag and drop the SaveSchedule-taskflow object onto the dialog. No input
parameters are required.
3.
When prompted, add the required library to the ViewController project by clicking
Add Library. Save the JSF page.
4.
In the JSF application you created, create another project called Scheduler. Select
File > New, and choose General > Empty Project. This project will be used to
create Oracle Enterprise Scheduler metadata and job implementations.
5.
In the Scheduler project, add the Oracle Enterprise Scheduler Extensions library to
the class path. Right-click the Scheduler project and select Project Properties >
Libraries and Classpath > Add Library > Oracle Enterprise Scheduler Extensions.
6.
7.
8.
Enter a schedule name, description and package name with the namespace
appended, as shown in Figure 648.
9.
Deploy the application. Open the page using the following URL:
http://<machine>:<http-port>/<context-root>/faces/<page>
3.
Click the Schedule tab. In the Run option field, select the Use a Schedule radio
button.
Working with Extensions to Oracle Enterprise Scheduler 64-47
4.
5.
Enter the namespace and package names for the schedule along with the name of
the schedule.
6.
To view the list of scheduled jobs, click Get Details. Click Submit to submit the
saved job request.
64.14.7 What Happens When You Create an Oracle ADF User Interface for Submitting
Job Requests
The Oracle ADF interface is integrated with the Oracle Fusion application, and the
application is tested and deployed. End users access the Oracle ADF user interface, fill
in optional job properties, and click a button to submit the job request.
64.14.8 What Happens at Runtime: How an Oracle ADF User Interface for Submitting
Job Requests Is Created
The application receives the submitted job request and calls Oracle Enterprise
Scheduler to run the job. The Oracle Fusion application accesses the values of the
properties entered by end users through the view object in which these properties
were defined at design time. The job returns a result of success or failure, and the
result passes from the Oracle Fusion application to Oracle Enterprise Scheduler.
Custom Task Flow
A job that includes properties to be filled in by end users through an Oracle ADF user
interface at runtime includes ADF Business Components view objects with validation
and the parameters to be filled in by end users. These parameters are submitted at
runtime in the order in which they have been defined, meaning the first custom
parameter to be defined is submitted first. The custom parameters must be named as
follows:
ParameterVO1.ATTRIBUTE1, ParameterVO1.ATTRIBUTE2, ParameterVO2.ATTRIBUTE1,
ParameterVO3.ATTRIBUTE1, and so on.
If the job definition includes the properties ContextParametersVO, ParameterTaskflow
and parametersVO, these properties render in that order at run time.
Context-Sensitive Parameters
When starting the job request submission page UI to submit a job or job set request
with context-sensitive parameters, the contextParametersVO parameter initially
renders in the Parameters tab of the Oracle ADF user interface.
The end-user can then enter values for the context-sensitive parameters. Clicking Next
invokes an API called setConextAPI by passing the context parameters. The context is
set at the database level and the remaining parametersVO job parameters are rendered.
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
When the context-sensitive parameters are modified, end users must click Next to set
the context with the new values.
Notifications
When the final status of the job is determined, Oracle Enterprise Scheduler delivers the
notifications to the relevant users using the User Messaging Service. Users receive
notifications based on their messages preferences.
The notification view object defined at design time populates the input box in the
submission request user interface at run time.
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
Create a Java class for the postprocessing action. The Java class uses the
parameters collected by the Oracle Enterprise Scheduler UI and calls Oracle BI
Publisher APIs as required.
Create a native ADF Business Components view object to save parameters for
postprocessing, such as template name, output format, locale, and so on.
1.
Use the following file to set up reporting and seed your database with the relevant
Oracle BI Publisher data:
Example 6431 Location of the File for Setting Up Oracle BI Publisher Reporting and
Seeding the Database
$BEAHOME/jdeveloper/jdev/oaext/adflib/PPActions.jar
2.
3.
Define File Management Group (FMG) properties for the Oracle BI Publisher job
definition as described in Section 64.4.2, "How to Define File Groups for a Job."
Action_SN: Define a short name for the action, used when postprocessing
actions are submitted programatically. For example, OBFUSC8.
Action Name: Enter a name for the action to be displayed in the user interface.
This name is stored separately for translation purposes.
Class: Enter the name of the Java class that defines the logic for the
postprocessing action. For example,
oracle.apps.shh.obfuscate.PPobfuscate.
VO_Def_Name: Enter the name of the view object used to collect the arguments
for the postprocessing action. For example,
oracle.apps.shh.obfuscate.PPobfuscateVO.
Type: Enter the category of the postprocessing action to be taken. Enter one of
the following categories of postprocessing actions:
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
Each action can also specify request parameters used by the postprocessing action
view object. These parameters must be set in the job definition for any job using
this action. The parameter names are stored in the APPLCP_PP_ACTION_PARAMS
table. The values of these parameters are accessible from the parameter view object
at the time of job request submission. postprocessing actions can access all request
parameters at runtime using the request ID.
2.
Define a Java class for the postprocessing action, implementing the interface
oracle.apps.fnd.applcp.request.postprocess.PostProcess. Use the methods
required by the interface as described in Table 644.
Description
PostProcessState
invokePostProcess(long requestID,
String ppArguments[], ArrayList
files);
ArrayList getOutputFileList();
Description
runReport()
Additional methods used by the ReportRequest object are shown in Table 646.
Table 646 Oracle BI Publisher Client API
oracle.xdo.service.client.types.ReportRequest Used by the ReportRequest Object
Method
Description
setAttributeFormat()
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
Description
setAttributeLocale()
setAttributeTemplate()
setXMLData()
oracle.apps.fnd.applcp.request.postprocess.PostProcess;
oracle.apps.fnd.applcp.util.ESSContext;
oracle.apps.fnd.applcp.util.PostProcessState;
oracle.as.scheduler.*;
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
// Check files
if (files[0] == null)
{
// no files - PostProcessing should never call us in this state
// in case it does - log Error to Oracle Diagnostic Logging
return PostProcessState.ERROR;
}
// This example expects a single file
myNewFile = outputDir + System.getProperty("file.separator") +
codedFileName;
Obfuscate.performObfuscation( files[0], obfuscationSeed, myNewFile );
myOutputFiles[0] = myNewFile;
// In case multiple files are used.
for ( i = 1; files[i] != null; i++ )
{
// Appending a counter to the filename to be unique.
myNewFile = outputDir + System.getProperty("file.separator") +
codedFileName + i ;
Obfuscate.performObfuscation( files[i], obfuscationSeed, myNewFile );
myOutputFiles[i] = myNewFile;
}
return PostProcessState.SUCCESS;
} catch (RuntimeServiceException rse)
{
// Log RuntimeServiceException to Oracle Diagnostic Logging.
return PostProcessState.ERROR;
} catch (Exception e)
{
// Log Exception to Oracle Diagnostic Logging.
return PostProcessState.ERROR;
} finally {
if (rHandle != null)
rService.close(rHandle);
}
}
} // end class
3.
Create a native ADF Business Components view object to collect the parameters to
be used in the postprocessing action. Follow the procedure described in
Section 64.4, "Creating a Job Definition." Define any view object attributes
sequentially.
If the view object requires access to action-specific values from the job definition,
specify the required job definition parameters in the action definition. The
submission UI automatically retrieves the values from the job definition metadata
and sets them as Oracle Fusion Middleware Extensions for Applications
(Applications Core) Session attributes that may be retrieved using the
ApplSession standard API.
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
boolean onWarning,
boolean onError,
String fileMgmtGroup,
String[] arguments)
throws IllegalArgumentException
For web service clients, you invoke the method using a proxy, as in Example 6435.
For more on the web service, see the chapter "Using the Oracle Enterprise Scheduler
Web Service" in Oracle Fusion Middleware Developer's Guide for Oracle Enterprise
Scheduler.
Example 6435 Adding Postprocessing Actions for a Request
ESSWebService proxy = createProxy("addPPActions");
PostProcessAction ppAction = new PostProcessAction();
ppAction.setActionOrder(1);
ppAction.setActionName("BIPDocGen");
ppAction.setOnSuccess(true);
ppAction.setOnWarning(false);
ppAction.setOnError(false);
ppAction.getArguments().add("argument1");
ppAction.getArguments().add("argument2");
List<PostProcessAction> ppActionList =
ppActionList.add(ppAction);
new ArrayList<PostProcessAction>();
Defining Oracle Business Intelligence Publisher Postprocessing Actions for a Scheduled Job
Table 647
Parameter
Description
params
actionOrder
actionName
The name of the action to perform. The following lists acceptable values for this
parameter, along with the acceptable values you can use in the arguments
parameter of this method.
description
argument3: maps to to
argument4: maps to cc
Description
onSuccess
onWarning
Determines whether this action should be performed when the job or step has
completed with a warning.
onError
Determines whether this action should be performed when the job or step has
completed with an error.
fileMgmtGroup
The name of the File Management Group. When using a Oracle BI Publisher
template, the value of this parameter is XML, as defined in the job definition
Program.FMG property with the value L.XML.
arguments
A list of arguments for the post processor action. See the actionName parameter
for values you can use for the arguments parameter.
64.16.4 What Happens When You Define Oracle BI Publisher Postprocessing Actions
for a Scheduled Job
Depending on the FMG property set for the job definition, the relevant postprocessing
action is selected for the job.
The ppArguments array stores the values collected from the view object attributes. The
array is passed to the invokePostProcess method which executes in the Java class that
defines the postprocessing action.
Note:
For information about enabling tracing for jobs, see Chapter 60, "Debugging Oracle
ADF and Oracle SOA Suite." For more information about tracing Oracle Enterprise
Scheduler jobs, see the section "Tracing Oracle Enterprise Scheduler Jobs" in the
chapter "Managing Oracle Enterprise Scheduler Service and Jobs" in the Oracle Fusion
Applications Administrator's Guide.
Create a UI Shell page and drop the Monitor Processes task flow onto it
Fields such as submission date, ready time, scheduled date,
process start, name, type, definition, and so on, are not set unless the
job request or subrequest is successfully validated.
Note:
Under the ViewController project, right-click Web Content and create a new JSF
page called Consumer.jspx. Select the following options:
UIShell (template)
3.
Create a new JSF page fragment. This page initializes the project.
4.
5.
6.
7.
Open the XML file created in the previous step. Look for an itemNode element as
follows:
<itemNode id="itemNode_JSF/JSPX page name">
For example, the Consumer.jspx page has the following itemNode value:
<itemNode id="itemNode_Consumer">
8.
In the Structure window, right-click the root itemNode and select Insert inside
itemNode-itemNode_JSF/JSPX page name > itemNode.
9.
id: MonitorNode
focusViewId: /Consumer
Enter a string for the pageTitle parameter, which will become the title for the
monitoring page. If this parameter is not specified, then the page title will be
shown as "Manage Scheduled Processes".
13. Repeat steps 8-12 to create a second itemNode element with the following
properties:
id: __Launcher_itemNode__FndTaskList
focusViewId: /Launcher
label: #{applcoreBundle.TASKS}
taskFlowId:
/WEB-INF/oracle/apps/fnd/applcore/patterns/uishell/ui/publicFlow/Ta
sksList.xml#TasksList
In the Resource Palette, select File System > Applications Core >
MonitorProcesses-View.jar > ADF Task Flows.
3.
Drag and drop onto the page as a region the SearchResultsFlow task flow.
The task flow accepts the following parameters:
scheduledDays: Queries requests for the last n days. If this parameter is not
specified in a work area task flow, job requests from the last three days are
displayed. If the value of this parameter is greater than three days, then the
parameter value will be taken as three and only the last three days of job
requests display.
status: The status of the request. This filter narrows down the result set to
display only the requests with the selected status in the filter.
If the status input parameter is not specified, then the results table shows all
requests with all statuses (by default, the All value is selected in the status
filter list).
If the status input parameter is specified, then the results table show only the
requests of the given status. The selected status is chosen as the default in the
status filter list.
Time Range Filter: This filter is used to narrow down the result set to show
only the requests for last n hours. This filter lists the following values in a
dropdown list: (1) Last 1 Hour, (2) Last 12 Hours, (3) Last 24 Hours, (4) Last 48
Hours and (5) Last 72 Hours.
The default selected item displays based on the value assigned or given to the
task flow parameter scheduledDays.
A scheduledDays value of 1 means the time range filter list displays only the
first three items.
A scheduledDays value of 2 means the time range filter list displays only the
first four items.
If the value of scheduledDays is 1, then by default, the time range dropdown
list displays Last 24 Hours.
If the value of scheduledDays is 3 or more, then by default, the time range
dropdown list displays Last 72 Hours.
pageTitle: When passed, the task flow will render this passed String value as
the page title. Optional.
requireRootOutcome: If the value true is passed, then the task flow will
generate a value of root-outcome when the user clicks on the Submit or Cancel
buttons. By default the task flow generates a value of parent-outcome.
Specifying more than one of these parameters causes the search to run using the
AND conjunction.
The only other valid value for the persistenceMode property is the value content. The
View Log button is hidden for all requests with a persistenceMode property value of
content. If the persistenceMode property is not specified for a given request, then the
monitoring UI defaults to a persistenceMode value of file, and displays the View
Log button when viewing relevant requests.
To log scheduled job requests:
1. Open the server's logging.xml file.
2.
The last definition takes precedence. When the same parameter is defined
repeatedly with the read-only flag set to false in all cases, the last parameter
definition takes precedence. For example, a property specified at the job
request level takes precedence over the same property specified at the job
definition level.
Table 648
The first read-only definition takes precedence. When the same parameter is
defined repeatedly and at least one definition is read-only (that is, the
ParameterInfo read-only flag is set to true), the first read-only definition takes
precedence. For example a read-only parameter specified at the job type
definition level takes precedence over a property with the same name
specified at the job definition level, regardless of whether it is read-only.
Resolving name conflicts between the job or job set metadata name and display
name attributes. By default, the display name takes precedence over the metadata
name. If the display name is not defined, then the UI defaults to displaying the job
or job set name.
Understanding the state of a job request. There are 20 possible states for a job
request, each with a corresponding number value. These are shown in Table 648.
Description
-1
UNKNOWN
WAIT
READY
RUNNING
COMPLETED
BLOCKED
HOLD
CANCELLING
EXPIRED
CANCELLED
10
ERROR
11
WARNING
12
SUCCEEDED
13
PAUSED
14
PENDING_VALIDATION
The job request has been submitted but has not been validated.
15
VALIDATION_FAILED
The job request has been submitted, but validation has failed.
16
SCHEDULE_ENDED
The schedule for the job request has ended, or the job request
expiration time specified at submission has been reached.
17
FINISHED
The job request, and all child job requests, have finished.
18
ERROR_AUTO_RETRY
The job request has run, resulted in an error, and is eligible for
automatic retry.
19
ERROR_MANUAL_
RECOVERY
Fixing an Oracle BI Publisher report that does not generate, even though the
Oracle Enterprise Scheduler schema REQUEST_PROPERTY table contains all the
relevant postprocessing parameters. Verify that the postprocessing parameters
begin with index value of 1. If a set of parameters begins with an index value of 0
Using a Task Flow Template for Submitting Scheduled Requests Through an Oracle ADF UI
(such as the parameter pp.0.action), then the Oracle BI Publisher report will not
generate. Oracle BI Publisher expects parameters to begin with an index value of 1.
In the case of a job set with multiple Oracle BI Publisher jobs, verify that all the
individual step postprocessing actions begin with an index value of 1.
Fixing a scheduled request submission UI that does not display, and throws a
partial page rendering error in the browser indicating that the drTaskflowId
property is invalid. This error may occur due to any of the following.
The job definition name or the job definition package name is incorrect when
passed as task flow parameters. Ensure that the package name does not end
with a trailing forward slash.
The metadata permissions are not properly configured for the user who is
currently logged in. The JobDefinition object, being stored in Oracle
Metadata Repository, requires adequate metadata permissions to read and
modify the JobDefinition metadata. Ensure that the Oracle Metadata
Repository to which you are referring contains the job definition name in the
proper package hierarchy.
64.18.1 How to Use a Task Flow Template for Submitting Scheduled Requests through
an Oracle ADF UI
A bundled task flow template is provided, containing the components required to
enable switching between basic and advanced modes in the Oracle ADF UI. The task
flow template adds a router activity and an input parameter to the custom bounded
task flow. Configure the router activity as the default activity.
You need only extend the task flow template as needed and implement the activity IDs
defined in the task flow template.
Example 6437 shows a sample implementation of the task flow template.
Using a Task Flow Template for Submitting Scheduled Requests Through an Oracle ADF UI
A default-activity,
A router activity,
64.18.2 How to Extend the Task Flow Template for Submitting Scheduled Requests
through an Oracle ADF UI
If you need to create your own custom bounded task flow UI for the parameters
section of the scheduled request submission UI, you will need to extend this template.
To extend the task flow template for the Oracle ADF UI used to submit scheduled
requests:
1. When creating a new task flow, extend the task flow by selecting Use a template.
For more information, see the part "Creating Oracle ADF Task Flows" in Oracle
Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework." Alternatively, add the lines of code shown in Example 6438 to the
task flow XML file.
Using a Task Flow Template for Submitting Scheduled Requests Through an Oracle ADF UI
Ensure your bounded task flow does not define any default
activity.
Note:
2.
Implement the activity IDs defined in the template, which are invoked by the
router activity in the template.
To do this, to the task flow drag and drop the createInsert method from the view
object used in the default view. This creates a pagedef file and adds the binding
details in DateBinding.cpx.
3.
Define a control flow rule to navigate from the initActivity object to the
defaultView object. This navigation depends on the outcome of the initActivity
object, as well as individual use cases.
Example 6439 shows a sample implementation of a control flow rule.
64.18.3 What Happens When you Use a Task Flow Template for Submitting Scheduled
Requests through an Oracle ADF UI
Based on the value of the input parameter, the router invokes the method call activity
or skips it, and invokes the view activity directly. The Oracle ADF UI must pass the
correct parameter values to the task flow while switching modes.
64.18.4 What Happens at Runtime: How a Task Flow Template Is Used to Submit
Scheduled Requests through an Oracle ADF UI
When loading the initial page in basic mode, the method call activity is invoked. While
loading the page in the advanced mode, the custom bounded task flow directly
invokes the view activity. This ensures that the user entered data persists in the view
objects across modes.
If the custom task flow UI does not render correctly, check whether transactional
properties have been set in the custom task flow, such as the requires-transaction
property, and so on.
Remove transactional properties from the task flow definition and set the data control
scope to shared.
As the parent scheduled request submission UI task flow already has a transaction,
Oracle ADF will commit all called task flow transactions if the data controls are
shared.
When using the UI to schedule a job to run for a year, for
example, a maximum of 300 occurrences display when clicking
Customize Times.
Note:
/WEB-INF/ScheduleRequest-taskflow.xml
/WEB-INF/srs-test-task-flow.xml#srs-test-task-flow
/WEB-INF/LayoutRN-taskflow.xml#LayoutRN-taskflow
/WEB-INF/NotifyRN-taskflow.xml#NotifyRN-taskflow
/WEB-INF/ScheduleRN_taskflow.xml#ScheduleRN_taskflow
/WEB-INF/oracle/apps/fnd/applcp/monitor/ui/flow/MonitorProcessesMainAreaF
low.xml#MonitorProcessesMainAreaFlow
/WEB-INF/oracle/apps/fnd/applcp/monitor/ui/flow/EmptyFlow.xml
Note:
If the Oracle Enterprise Scheduler job fails due to an internal software error, log the
detailed failure message to the log called FND_LOG for the system administrator or
support. You can also log a high-level generic message to the request log so as to
inform end users of the error. An example of a generic error message intended for end
users: "Your request could not be completed due to an internal error."
Note:
Note:
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
CONSTANT
NUMBER
NUMBER
NUMBER
NUMBER
NUMBER
NUMBER
/*
** Writes the message to the
** level and module
** if logging is enabled for
*/
PROCEDURE STRING(LOG_LEVEL IN
MODULE
IN
MESSAGE
IN
/*
**
**
**
**
:=
:=
:=
:=
:=
:=
6;
5;
4;
3;
2;
1;
Example 6444 shows how to log a message in PL/SQL after the AOL session has been
initialized.
Example 6444 Logging a Message in PL/SQL After the AOL Session Has Been
Initialized
begin
/* Call a routine that logs messages. */
/* For performance purposes, check whether logging is enabled. */
if( FND_LOG.LEVEL_PROCEDURE >= FND_LOG.G_CURRENT_RUNTIME_LEVEL ) then
FND_LOG.STRING(FND_LOG.LEVEL_PROCEDURE,
'fnd.plsql.MYSTUFF.FUNCTIONA.begin', 'Hello, world!' );
end if;
/
For PL/SQL in a forms client, use the same APIs. Use the
method FND_LOG.TEST() to check whether logging is enabled.
Note:
Using Logging in C
Example 6447 illustrates the use of logging in a C application.
Example 6447 Logging in C
#define
#define
#define
#define
#define
#define
AFLOG_UNEXPECTED
AFLOG_ERROR
AFLOG_EXCEPTION
AFLOG_EVENT
AFLOG_PROCEDURE
AFLOG_STATEMENT
6
5
4
3
2
1
/*
** Writes a message to the log file if this level and module is
** enabled
*/
void aflogstr(/*_ sb4 level, text *module, text* message _*/);
/*
** Writes a message to the log file if this level and module is
** enabled.
** If pop_message=TRUE, the message is popped off the message
** Dictionary stack where it was set with afdstring() afdtoken(),
** etc. The stack is not cleared (so messages below will still be
** there in any case).
*/
void aflogmsg(/*_ sb4 level, text *module, boolean pop_message _*/);
/*
** Tests whether logging is enabled for this level and module, to
** avoid the performance penalty of building long debug message
** strings
*/
boolean aflogtest(/*_ sb4 level, text *module _*/);
/*
** Internal
** This routine initializes the logging system from the profiles.
** It will also set up the current session and user name in its state */
void afloginit();
65
Oracle Enterprise Scheduler Security
65
This chapter explains how Oracle Enterprise Scheduler security features provide
access control for Oracle Enterprise Scheduler resources and application identity
propagation for job execution.
Section 65.3, "Configuring PL/SQL Job Security for Oracle Enterprise Scheduler"
Section 65.6, "Configuring Oracle Fusion Data Security for Job Requests"
Figure 651 Design Time Metadata Security for Oracle Enterprise Scheduler
2.
3.
4.
5.
Assign relevant roles to the metadata, and specify actions for each role.
6.
Assemble the EAR file for the application, including any security-related files.
7.
Deploy the EAR file to Oracle WebLogic Server, which verifies grants in the Oracle
Metadata Store and permissions assigned to roles with the LDAP server.
such as metadata objects. For example, if a user named teller1 must call
getJobDefinition to access a metadata object named caclulateFees, Oracle
Enterprise Scheduler ensures that teller1 has READ permission for the metadata object
caclulateFees before returning the object.
At design time, you must determine the job functions for which you want to enable
access to particular metadata objects by associating each metadata object with one or
more roles and specifying one or more actions for each role.
There are two options for metadata role assignments:
Oracle JDeveloper ADF Security wizard creates the roles you use; the roles must be
created before you can register roles with a metadata object.
65.2.1 How to Enable Application Security with Oracle ADF Security Wizard
These steps describe a minimal, validated security setup for an application using
Oracle Enterprise Scheduler.
Follow these steps to create a working jps-config.xml and a partially-populated
jazn-data.xml. Use these steps to configure servlets to work with JPS.
To enable security using the Oracle ADF Security wizard:
1. In Oracle JDeveloper, with an application open, from the Application menu select
Secure.
2.
From the dropdown list, select Configure ADF Security. The Configure ADF
Security wizard displays.
3.
In the Enable ADF Security page, select either ADF Authentication and
Authorization or ADF Authentication and click Next.
4.
In the Select authentication type page, select either HTTP Basic Authentication or
Form-Based Authentication and click Next.
5.
In the Enable automatic policy grants page, select the appropriate options from the
Enable Automatic Grant area, and click Next.
6.
In the Specify authenticated welcome page, select options as needed and click
Next.
7.
8.
Next, to enable security and ensure that the jazn-data.xml is included in the
application deployment, perform the following steps after assembling the EAR file for
the application. For more information, see "Assembling Oracle Enterprise Scheduler
Oracle Fusion Applications" in the Oracle Fusion Applications Extensibility Guide for
Developers.
Ensure the security-related files are included with the EAR file:
1. In Oracle JDeveloper, select Application > Application Properties.
2.
3.
In the Deployment Profiles area, select the EAR file Deployment descriptor.
4.
Click Edit.
In the Edit EAR Deployment Profile Properties page, expand File Groups >
Application Descriptors > Filters.
6.
7.
8.
Enterprise roles: These are defined directly in Oracle WebLogic Server either using
the Oracle WebLogic Server console, using the WLST scripts, or using the Oracle
ADF Security Wizard in Oracle JDeveloper.
Application roles: These can be defined in the jazn-data.xml file or using the
Oracle ADF Security Wizard.
3.
4.
In the page showing jazn-data.xml, select the Overview tab. If the Overview tab
is not shown, try closing jazn-data.xml and then opening it again.
5.
6.
On the Edit JPS Identity and Policy Store page, in the navigator expand Identity
Store and jazn.com.
7.
8.
9.
Click OK.
10. On the Edit JPS Identity and Policy Store page, in the navigator select Application
Policy Store. If there is a sub-element with the same name as the application, go to
the next step, Otherwise, do the following:
a.
b.
Click New.
The Create Application Policy window displays.
c.
In the Create Application Dialog the Display Name field should contain the
application name.
d.
11. On the Edit JPS Identity and Policy Store page, in the navigator expand
least one enterprise role must be mapped to the application role by adding
enterprise roles in the Member Roles tab.
14. Click OK.
65.2.3 How to Create Grants with Oracle Enterprise Scheduler Metadata Pages
Access to all metadata is controlled by grants. To ensure access by the right identities,
you need to give the correct grants.
First, create any required Oracle Enterprise Scheduler metadata in an application using
File > New > Business Tier > Enterprise Scheduler Metadata. For more information
about defining metadata, see Section 64.4, "Creating a Job Definition."
Using Oracle JDeveloper, you can add security grants to Oracle Enterprise Scheduler
metadata objects.
To secure Oracle Enterprise Scheduler metadata objects:
1. Open the Editor page for any Oracle Enterprise Scheduler metadata object.
2.
In the Access Control area, click Add to add a new access control item.
3.
In the Add Access Control dialog, select a Role from the dropdown list. This
selects a role to grant access privileges.
4.
Select one or more actions from the list, Read, Execute, Update, or Delete.
5.
Click OK. This displays the updated role, as shown in Figure 652.
6.
3.
4.
In the JPS Identity & Policy Store dialog, in the navigator expand Application
Policy Store.
5.
6.
Click New.
7.
Enter the display name you wish for this grant, and click OK.
8.
9.
Enter the name of the application role which will receive the grant; this should be
one of the role names created. Leave the Class field as is.
wildcards; see Table 651 for examples. In the Class field, enter
oracle.as.scheduler.security.MetadataPermission. Click OK.
14. With the new permission selected in the Permissions tab, enter the desired actions
Note:
1.
2.
3.
Table 651
Name
Actions
Effect
package-part.JobDefinition EXECUTE
.MyJavaSucJobDef
mypackage.subpackage.*
CREATE,EXECUTE
JobDefinition.SYS_
AdHocRequest
CREATE,EXECUTE
mypackage.*
Action
Implies
Metadata Functions
READ
None
get<Type>(), query<Type>()
EXECUTE
READ
submitRequest()
CREATE
READ
add<Type>()
UPDATE
READ
update<Type>()
DELETE
READ
delete<Type>()
If you are submitting ad-hoc requests, you can have full wildcard ("*") permission with
both EXECUTE and CREATE actions. When submitting ad-hoc requests, that is, using
submitRequest() without certain MetadataObjectIds, you can grant permissions with
the full wildcard ("*") name using the EXECUTE and CREATE actions.
For all MetadataService methods except queries, an exception is thrown when the
user tries to access a metadata object for which the user does not have permission.
The MetadataService query methods have different behavior. When a user performs a
query Oracle Enterprise Scheduler only returns metadata objects that have READ
permission. Thus a user who has no permissions on metadata objects receives an
empty list for all queries, but this user would not see an exception thrown due to lack
of permissions.
The value of SystemProperty.USER_NAME is overwritten at submission time; the user
cannot spoof an identity at submission time using SystemProperty.USER_NAME.
3.
Example 651
<ejb-jar>
....
<enterprise-beans>
<message-driven>
<ejb-name>ESSAppEndpoint</ejb-name>
<ejb-class>oracle.as.scheduler.ejb.EssAppEndpointBean</ejb-class>
<activation-config>
....
<activation-config-property>
<activation-config-property-name>applicationStripe</activation-config-property-name>
<activation-config-property-value>ESS_FUNCTIONAL_TESTS_APP_
STRIPE</activation-config-property-value>
</activation-config-property>
</activation-config>
</message-driven>
.....
</enterprise-beans>
<interceptors>
<interceptor>
<interceptor-class>oracle.security.jps.ee.ejb.JpsInterceptor</interceptor-class>
<env-entry>
<env-entry-name>application.name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>ESS_FUNCTIONAL_TESTS_APP_STRIPE</env-entry-value>
<injection-target>
<injection-target-class>oracle.security.jps.ee.ejb.JpsInterceptor
</injection-target-class>
<injection-target-name>application_name</injection-target-name>
</injection-target>
</env-entry>
</interceptor>
</interceptors>
</ejb-jar>
4.
If your application has a web module, configure the web module JpsFilter to use
the same applicationStripe in the file web.xml. Example 652 shows a code
sample.
Example 652
<web-app>
<filter>
<filter-name>JpsFilter</filter-name>
<filter-class>oracle.security.jps.ee.http.JpsFilter</filter-class>
...
<init-param>
<param-name>application.name</param-name>
<param-value>ESS_FUNCTIONAL_TESTS_APP_STRIPE</param-value>
</init-param>
</filter>
</web-app>
data exposed to Oracle Fusion Applications (see Section 65.6.1, "Oracle Fusion
Data Security Artifacts").
The job request access control data security policy can be managed using Oracle
Authorization Policy Manager as are other Oracle Fusion Data Security policies. If
Oracle Authorization Policy Manager is not available, you can use SQL scripts to
manipulate the Oracle Fusion Data Security artifacts.
Columns
ess_request_history
request_history_view
ess_request_property
request_property_view
Table 654
RuntimeService.QueryField Columns
Request_history_view Columns
QueryField.REQUESTID
requestid
QueryField.APPLICATION
application
QueryField.USERNAME
userName
QueryField.PRODUCT
product
QueryField.REQUEST_CATEGORY
requestCategory
QueryField.PRIORITY
priority
QueryField.NAME
name
QueryField.ABSPARENTID
absParentId
QueryField.TYPE
type
QueryField.DEFINITION
definition
QueryField.STATE
state
QueryField.SCHEDULE
schedule
QueryField.PROCESSSTART
processStart
QueryField.PROCESSEND
processEnd
QueryField.REQUESTEDSTART
requestedStart
QueryField.REQUESTEDEND
requestedEnd
QueryField.SUBMISSION
submission
QueryField.PARENTREQUESTID
parentRequestId
QueryField.WORKASSIGNMENT
workAssignment
QueryField.SCHEDULE
scheduled
QueryField.REQUESTTRIGGER
requesttrigger
QueryField.PROCESSOR
processor
QueryField.CLASSNAME
classname
QueryField.ELAPSEDTIME
elapsedtime
QueryField.WAITTIME
waittime
QueryField.SUBMITTER
submitter
QueryField.SUBMITTERGUID
submitterguid
Table 655
FND_FORM_FUNCTIONS
ESS_REQUEST_ADMIN
ESS_REQUEST_READ
ESS_REQUEST_UPDATE
ESS_REQUEST_HOLD
ESS_REQUEST_CANCEL
ESS_REQUEST_LOCK
ESS_REQUEST_RELEASE
ESS_REQUEST_DELETE
ESS_REQUEST_PURGE
ESS_REQUEST_VIEW
ESS_REQUEST_READ
ESS_REQUEST_OPERATE
ESS_REQUEST_READ
ESS_REQUEST_HOLD
ESS_REQUEST_CANCEL
ESS_REQUEST_LOCK
ESS_REQUEST_RELEASE
ESS_REQUEST_OUTPUT_ADMIN
ESS_REQUEST_OUTPUT_VIEW
ESS_REQUEST_OUTPUT_DELETE
Table 656 lists the required data privilege (form_function) for a user to perform an
Oracle Enterprise Scheduler runtimeService operation.
Table 656
Notes
open
none
close
none
submitRequest
none
getRequestParameter
ESS_REQUEST_READ
getRequestState
ESS_REQUEST_READ
getRequests
ESS_REQUEST_READ
getRequestDetail
ESS_REQUEST_READ
getRequestDetailBasic
ESS_REQUEST_READ
lockRequest
ESS_REQUEST_LOCK
updateRequestParameter
ESS_REQUEST_UPDATE
queryRequests
ESS_REQUEST_READ
holdRequest
ESS_REQUEST_HOLD
releaseRequest
ESS_REQUEST_RELEASE
cancelRequest
ESS_REQUEST_CANCEL
deleteRequest
ESS_REQUEST_DELETE
Notes
purgeRequest
ESS_REQUEST_PURGE
publishEvent
none
isHandleRollbackOnly
none
setHandleRollbackOnly
none
replaceSchedule
none
INSTANCE_SET Condition
Description
REQS_SUBMITTEDBY_SESSIONUSER
REQS_RUNAS_SESSIONUSER
REQS_SUBREQS_BY_SUBMITTER
REQS_ALL_OF_ONE_APP
ESS_REQS_BY_NAME_VALUE_PARAM
Table 658 lists the Oracle Fusion Data Security policies available for use with Oracle
Enterprise Scheduler out of the box.
Table 658
Description
ESS_REQUEST_SUBMITTER_ADMIN_SUBMITTED_
REQUESTS
ESS_REQUEST_SUBMITTER_ADMIN_SUBMITTED_
REQUESTS_SUBREQS
ESS_REQUEST_RUNASUSER_ADMIN_EXECUTED_
REQUESTS
ESS_REQUEST_RUNASUSER_VIEWOUTPUT_
EXECUTED_REQUESTS
The runAs user is permitted to view the output of the job requests
they executed.
For more information about the runAs user, or elevating access privileges, see
Section 64.13, "Elevating Access Privileges for a Scheduled Job."
If you can use one of these policies, skip to the last step.
2.
Determine whether any of the FND_MENUS listed in Table 655 suit the
out-of-the-box Oracle Fusion Data security policy you selected for your
application. If you cannot apply any of the FND_MENUS listed in Table 655, create
your own FND_MENUS and FND_MENUS_ENTRIES as described in Chapter 50,
"Implementing Oracle Fusion Data Security."
3.
Determine whether you can use the INSTANCE_SET conditions in Table 657 and the
Oracle Fusion Data Security policies in your application. If you cannot use the
conditions, create your own FND_INSTANCE_SET. For more information about
creating an FND_INSTANCE_SET, see Chapter 50, "Implementing Oracle Fusion Data
Security."
4.
Create an Oracle Fusion Data Security policy, as described in Section 65.6.3, "How
to Create Functional and Data Security Policies for Oracle Enterprise Scheduler
Components."
If developing an Oracle Fusion application, do not grant an
Oracle Enterprise Scheduler access policy to the grantee of an
authenticated-role or anonymous-role, as doing so may affect the
behavior of Oracle Enterprise Scheduler or other products.
Note:
5.
65.6.3 How to Create Functional and Data Security Policies for Oracle Enterprise
Scheduler Components
You can use Oracle Authorization Policy Manager to create functional and data
security policies for Oracle Enterprise Scheduler.
For more information about creating policies in Oracle Authorization Policy Manager,
see the section "Managing Authorization Policies" in the "Securing Oracle Fusion
Applications" chapter of the Oracle Fusion Applications Administrator's Guide.
To create functional and data security policies for Oracle Enterprise Scheduler:
1. Create a resource.
a.
From the list of policies, expand the fcsm policy stripe and select fcsm >
Resource Catalog > Resources.
b.
c.
d.
2.
3.
4.
Select the resource you just created and click Create Policy.
b.
c.
In the Add Principal window, search for the relevant application role or roles.
Select the roles and click Add.
d.
In the Actions field, select the relevant actions and click Apply.
In the Authorization Management tab, select Global and search for the
database resource you want to use. Table 658 lists the database resources
related to Oracle Enterprise Scheduler.
b.
c.
d.
Enter a name, display name and SQL predicate for the condition.
b.
In the New Policy window, use the Role and Database Resource fields to add
the relevant roles and resources.
c.
Select the role you defined. In Database Resource Details region, select the
condition name you just created and choose the actions you require.
66
Implementing Oracle Social Network
Integration
66
This chapter documents how developers can implement Oracle Social Network in an
application by creating the Model project in JDeveloper and by displaying it in the
Global Area of the UIShell.
The chapter includes these sections:
Oracle Social Network URL must be defined in Topology Manager with a Module
Short Name of 'OSN'.
On a production instance, there will be an internal and external Topology Manager
URL for Oracle Social Network. The internal URL will be used for all data sent to
Oracle Social Network. The external URL will be used when navigating from
within Fusion Applications.
The Oracle Social Network credential must exist in the WebLogic Server credential
store.
In the weblogic-application.xml file that is present at the workspace level, add a
reference to the Oracle Social Network model shared library:
<library-ref>
<library-name>oracle.social.client</library-name>
</library-ref>
In the weblogic.xml file for the UI project (that is mapped to the WAR
deployment), add a reference to the Oracle Social Network view shared library.
This entry is needed in any UI project that needs to test or run the Oracle Social
Network integration using the UIShell as described in Section 66.4, "Adding
Oracle Social Network to Your Application UI."
<library-ref>
<library-name>oracle.social.client.view</library-name>
</library-ref>
Role
Description
Fusion Applications
Developer
A developer in a product
team that has view object
data that is to be sent to
Oracle Social Network.
Provisioner
Functional
Administrator
End User
At different times during the development process, a person must be able to perform
several of these roles. For example, an Oracle Fusion Applications developer who is
performing development through to testing will need to wear the hats for most or all
of these roles to ensure that their integration pieces work correctly to send the data to
Oracle Social Network.
Design Time - Making a Business Object available for Oracle Social Network
integration.
The prerequisite is that the JDeveloper environment has at minimum the
"Applications Core" extension loaded.
It is underpinned by one or more entity objects that are derived from the
OAViewObjectImpl and OAEntityObjectImpl respectively.
Any rows from the view object must be derived from OAViewRowImpl.
To set up a view object for Oracle Social Network integration, there is a common set of
steps to provide basic integration. This basic integration can be customized based
upon how the integration is to work for that view object. The various customizations
that can be applied are:
A wizard assists with making view objects available for Oracle Social Network
integration. The wizard will guide you through selecting the view objects and the set
of attributes within the view object that are available for a site to send through to
Oracle Social Network. All view objects that are to be available for Oracle Social
Network integration must follow the steps in the next section. Then they can have
additional configuration made to tailor the integration further. Section 66.2.1.1,
"Configuring the Business Object for Oracle Social Network Integration" discusses the
required steps to have a basic integration with Oracle Social Network.
66.2.1.1 Configuring the Business Object for Oracle Social Network Integration
It is underpinned by one or more entity objects that are derived from the
OAViewObjectImpl and OAEntityObjectImpl respectively.
A wizard helps make view objects available for Oracle Social Network integration. The
wizard will guide you through selecting the view objects and the set of attributes
within the view object that are available for a site to send through to Oracle Social
Network. All view objects that are to be available for Oracle Social Network
integration must follow the steps listed here. Then they can have additional
configuration made to tailor the integration further. The required steps to have a basic
integration with Oracle Social Network are:
1.
Find the application module that contains the view object to be made available for
Oracle Social Network integration.
2.
Right-click the application module and select the Add OSN View Instances menu
item. This will start the OSN Enabled View Instances wizard, shown in
Figure 661.
3.
At the top of the wizard is a dropdown list called Module. Choose the module that
best represents the line of business for the current project.
4.
Just beneath the Modules, there is a list of available view objects and a data model
list. Find the view object(s) that are to be made available for Oracle Social Network
integration from the list of available view objects and shuttle them into the data
model. This signifies that the view object will be available for Oracle Social
Network integration.
5.
Clicking the view object in the data model pane will show the list of attributes for
that view object in the Attributes tab.
6.
Select the Enable check box next to any attribute that is to be available within that
view object for Oracle Social Network integration. Only attributes that are enabled
will be allowed to be sent to Oracle Social Network.
7.
If the deployment profile for the project is a ADF Library JAR file, then the META-INF
folder and the fnd-osn-integration.xml file automatically will be bundled into the
JAR file at the correct location. However, if the deployment profile is a regular JAR file,
then the META-INF folder will need to be added as Project Output Contributor and
ensure that the fnd-osn-integration.xml file is selected for inclusion in the JAR file.
There should be no additional steps required for product integrators or special build
When deployed in a ADF Library JAR file, this file will be located at
META-INF/fnd-osn-integration.xml allowing it be looked up directly on the class path
from the "Manage Social Network Objects" page.
The other change that the wizard makes is to modify the view object definition XML
file for the attributes that are available for Oracle Social Network integration. It adds
or updates a new custom property called fnd:OSN_ENABLED_ATTR within the attribute
XML node with a value of true to make that attribute available.
<ViewAttribute Name="DeptName">
<Properties>
<SchemaBasedProperties>
<fnd:OSN_ENABLED_ATTR Value="true"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
Display Name - used to show when a label is required for the view object.
Display Name (Plural) - used to show when plural label is required for the view
object.
Description - used for showing the description in the "Manage Social Network
Objects" page.
These UI Hint properties are used from the view objects attributes as Oracle Social
Network field label translations:
What happens when translated Oracle Social Network labels are provided
The view object definition XML file will be modified with these custom properties set:
TOOLTIP - Description
LABEL - Label
The values provided in the Edit property window will be seeded into the
translation bundle and the key will be stored as the ResId attribute of the relevant
property node in the view object definition file. These are sample changes to the
view object definition file.
<ViewObject Name="SndDemoDeptVO">
<Properties>
<SchemaBasedProperties>
<LABEL ResId="DEMO_DEPARTMENT"/>
<LABEL_PLURAL ResId="DEMO_DEPARTMENTS"/>
<TOOLTIP ResId="DEMONSTRATION_DEPARTMENT_FOR_S"/>
</SchemaBasedProperties>
</Properties>
<ViewAttribute Name="DeptName">
<Properties>
<SchemaBasedProperties>
<LABEL ResId="DEPARTMENT_NAME"/>
<LABEL_PLURAL ResId="DEPARTMENT_NAMES"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
</ViewObject>
When to Use
Notes
If the Java Type of the
attribute is anything other
than java.lang.Boolean, then
refer to the Boolean entry in
Special Cases - Boolean.
Boolean
Currency
Attribute #2 : "CreditCurrencyCode"
Gadget Type="STRING" OSN_
ENABLE="false" Value="USD"
When sent to Oracle Social Network,
the credit field will show as Credit:
23 USD
Display the attribute value as a formatted
date.
Date
When to Use
Double
Integer
Percent
Person
String
Display a value.
URL
Notes
If the OSN_GADGET_TYPE is not provided (default state for the property), then the Oracle
Social Network integration code will use the Java Type to Gadget Type mapping
shown in Table 663 for sending the data to Oracle Social Network.
Table 663
java.sql.Date
Date
Integer
Double
java.lang.Boolean
Boolean
String
Display a value.
Currency
Percent
java.lang.String
Person
java.lang.String
URL
java.sql.Timestamp
java.util.Date
oracle.jbo.domain.Date
oracle.jbo.domain.Timestamp
java.lang.Integer
java.lang.Long
java.lang.Short
java.math.BigInteger
java.util.concurrent.atomic
.AtomicInteger
java.util.concurrent.atomic
.AtomicLong
java.lang.Double
java.lang.Float
java.lang.Number
java.math.BigDecimal
oracle.jbo.domain.Number
To configure the attributes for the Oracle Social Network field gadget types
(non-Currency):
In the Property Inspector, open the Applications - Oracle Social Network section.
Change the value in the Oracle Social Network Gadget Type to the required type.
For setting an attribute to the Currency gadget type, an additional step must be
followed to add the currency code for the currency value. By setting the Currency
Code attribute property for the attribute, when the Social Object is sent to Oracle Social
Network, the currency code value also will be sent with the currency value so that
Oracle Social Network can display both values when it displays the currency value.
Note that the currency code attribute does not need to be available to Oracle Social
Network integration for its value to be used when sending the currency so long as the
attribute for the Currency is available to Oracle Social Network integration. These are
the steps to set up an attribute for currency:
In the Property Inspector, open the Applications - Oracle Social Network section.
In the Currency Code attribute property, enter the name of the attribute whose
value will contain the currency code value.
Click Save to keep the changes.
Implement the conversion between the string boolean attribute and the Java
Boolean attribute as a Groovy expression or as a Java override of the getter
attribute of the transient attribute in the RowImpl class for the view object. For
example, this Groovy expression can be used in the "Y"/"N" case:
"Y".equalsIgnoreCase(<your attribute name>)
In the Dependencies page of the attribute wizard, make the Boolean transient
attribute dependent upon the String boolean attribute.
Set the Gadget Type for the Boolean transient attribute as boolean.
Either re-open the Add OSN View Instances wizard, find the view object and click
the Enabled checkbox for the transient attribute and click OK.
or
Open the Attributes tab in the view object, select the transient attribute, go to the
Property Inspector and change the OSN Enabled property to be "true."
Opening the Add OSN View Instances wizard, find the view object and select
the Enabled checkbox for the meaning attribute and click OK.
Implementing Oracle Social Network Integration 66-11
Open the Attributes tab in the view object, select the meaning attribute, go the
Property Inspector and change the OSN Enabled property to be "true".
Special Cases - Other types of attributes that do not fit the defined list of Oracle
Social Network Gadget Types
If there are other value types in a view object attribute that need to be sent to Oracle
Social Network or provided in a different format, the best way to solve this with the
current framework is to provide a new transient String attribute and format the value
in the way it should be displayed in Oracle Social Network.
Implement the conversion between the custom value type and the String transient
attribute as a Groovy expression or as a Java override of the getter attribute of the
transient attribute in the RowImpl class for the view object.
In the Dependencies page of the attribute wizard, make the String transient
attribute dependent upon the custom value type attribute.
Open the view object in JDeveloper and click the Attributes tab.
Determine that attribute is to be used as the Social Object title value. If this is a
pre-existing attribute value, skip the next three optional steps.
[Optional-generated title] Define a new transient attribute that has a type of
String.
[Optional-generated title] Implement the title generation in the transient attribute
as a Groovy expression or as a Java override of the getter attribute of the transient
attribute in the RowImpl class for the view object.
[Optional-generated title] In the Dependencies page of the attribute wizard, make
the String transient attribute dependent upon the custom value type attribute.
Select the attribute (transient or actual).
Access the Property Inspector in the Applications - Oracle Social Network
section and set the Oracle Social Network User Key to be "true".
Click Save to keep the changes.
What happens when you define the Oracle Social Network Social Object Title
The Attribute definition within the view object definition XML file will be modified
with the following custom property:
fnd:OSN_USER_KEY - The Oracle Social Network User Key custom attribute.
The following is an example of the modification in the view object attribute definition
XML file:
<ViewAttribute Name="DeptName">
<Properties>
<SchemaBasedProperties>
<fnd:OSN_ENABLED_ATTR Value="true"/>
<fnd:OSN_USER_KEY Value="true"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
Notes:
There should be only one attribute with the Oracle Social Network
User Key custom property value set to "true". If there are multiple
attributes with the custom property set, then the first one that is
found during processing will be used and all others will be
ignored.
If no attributes are provided with this custom property set, then
the concatenated values of the attributes that comprise the view
object primary key will be used.
Open the view object in JDeveloper and click the Attributes tab.
Determine that attribute is to be used as the Social Object external key value. If this
is a pre-existing attribute value then skip the next three optional steps.
[Optional-generated key] Define a new transient attribute that has a type of
String.
[Optional-generated key] Implement the key generation in the transient attribute
as a Groovy expression or as a Java override of the getter attribute of the transient
attribute in the RowImpl class for the view object.
[Optional-generated key] In the Dependencies page of the attribute wizard, make
the String transient attribute dependent upon the custom value type attribute.
Select the attribute (transient or actual).
Access the Property Inspector in the Applications - Oracle Social Network
section and set the Object Key to be "true."
Click Save to keep the changes.
What happens when you define the Oracle Social Network Social Object Key
The Attribute definition within the view object definition XML file will be
modified with the following custom property:
Notes:
Single attribute primary key view objects do not need to set this
value because no concatenations need to occur to get the primary
key value to use.
There should only one attribute with the Oracle Social Network
Object Key custom property value set to "true". If there are
multiple attributes with the custom property set, then the first one
that is found during processing will be used and all others will be
ignored.
If no attributes are provided with this custom property set, then
the concatenated values of the attributes that comprise the view
object primary key will be used.
</SchemaBasedProperties>
</Properties>
<fnd:OSN_FA_NAV_TASK_PARAMS_LIST
Value="key1=value1;key2=value2"/>
</SchemaBasedProperties>
</Properties>
Notes:
This should not be used if the Task Label property is set. If both
are set, then this one will take precedence and the Task Label will
be ignored.
The attribute to which this property refers can be a transient or
actual attribute.
The values supplied for Nav Page Params List, Nav Task Key List, Nav Task Params
List and Task Label can contain attribute name tokens that will be resolved when the
View Details URL is being generated before it is sent to Oracle Social Network. The
token is made up of an attribute name contained within curly brackets {}.
For example, if the Nav Task Params List is defined as "deptNumParam={DeptNum}"
then the value of the view object row Attribute called "DeptNum" will replace the
{DeptNum} token.
To set up the view object for the View Details URL:
Open the view object in JDeveloper and click the General tab.
Nav Taskflow Id
Nav Task Key List
Nav Task Params List
Task Label
Task Label Attribute
What happens when you configure the View Details URL Properties
The view object definition XML file will be modified with the following custom
properties:
<ViewObject Name="SndDemoDeptVO">
<Properties>
<SchemaBasedProperties>
<fnd:OSN_FA_WEBAPP Value="SocialNetworkDemo"/>
<fnd:OSN_FA_VIEW_ID Value="SocialNetworkDemo"/>
<fnd:OSN_FA_NAV_TASKFLOW_ID
Value="/WEB-INF/DemoDepartmentTF.xml#DemoDepartmentTF"/>
<fnd:OSN_FA_NAV_TASK_PARAMS_LIST Value="deptNumParam={DeptNum}"/>
<fnd:OSN_FA_PAGE_PARAMS_LIST Value="deptNumPageParam={DeptNum}"/>
<fnd:OSN_FA_NAV_TASK_KEY_LIST Value="deptNumKeyParam={DeptNum}"/>
<fnd:OSN_FA_NAV_TASK_LABEL ResId="NAVIGATE_DEPT_DEPTNUM"/>
</SchemaBasedProperties>
</Properties>
</ViewObject>
When the end user submits the view object row this will trigger the Social Object to be
generated for sending to Oracle Social Network. As part of this generation the View
Details URL will be constructed and added to the Social Object payload. The URL is
generated using an algorithm that will perform lookups, such as determining the base
URL from the Web App Id, and other parameter manipulations that will convert these
parameters into a string that UIShell will accept as secure and valid. The UIShell,
when called with this URL, will be able to determine what the parameters were and
how to load the page and taskflow. For example, the following parameters will
generate into the URL.
Open the view object in JDeveloper and click the General tab.
Set the following custom property to override the view objects Social Object
registration definition name:
Definition Name - This must be in the format <module id>.<name>. For example:
FND.FndDempDept
Click the Attributes tab and select the attribute that is to have its Social Object
Field Name overridden.
Set the following custom property:
Oracle Social Network Attribute Name Override - The Social Object Field name
the attribute will be referred to as.
What happens when you change the Social Object Registration Name
The following custom properties are modified within the view object XML definition.
The view object definition XML file will be modified with these custom properties:
<ViewObject Name="FndDemoOsnFieldsVO">
<Properties>
<SchemaBasedProperties>
<fnd:OSN_DEFINITION_NAME Value="fnd.FndDemoOsnFieldsVO"/>
</SchemaBasedProperties>
</Properties>
<ViewAttribute Name="OsnTestRecordId">
<Properties>
<SchemaBasedProperties>
<fnd:OSN_ENABLED_ATTR Value="true"/>
<fnd:OSN_ATTR_DEFINITION_NAME Value="TestId"/>
</SchemaBasedProperties>
</Properties>
</ViewAttribute>
A view object that has multiple entity objects selected to be within it.
The entity objects that are participating in the update must have an association
defined between them that creates an accessor in the Primary entity object that
returns an instance of an OAEntityImpl (or one of its sub-classes) objects that is the
instance of the Secondary entity object.
There are several cases in Oracle Fusion Applications where an Oracle Social Network
integration available view object is tied to multiple updatable entity objects. For
example, several Oracle Fusion applications use TCA (HZ_PARTIES) to manage key
attributes about a person or company. Many teams, such as Procurement and CRM,
extend the TCA schema with their own tables and columns to meet the information
gathering requirements for their product. Procurement owns an entity called Supplier
that extends the TCA Party schema to maintain information about a company from
whom you would like to purchase goods and services. The Supplier view object would
therefore have updateable attributes from both the Supplier entity object and the TCA
Party entity object. ATG business event registration for Oracle Social Network
integration typically only references the primary entity object. In the TCA case, a
customer can go to the Maintain Supplier UI and update a single attribute, such as
Supplier Name. The Supplier Name is maintained in the TCA Party entity object that,
in this case, is not the primary entity object. We must publish these cases to Oracle
Social Network as update events but we do not want to place the Oracle Social
Network integration events on multiple entity objects to avoid mass duplication of
events.
The solution for this use case is to register the Primary entity object (Supplier entity
object) as a post transaction listener for the Secondary entity object (Party entity
object). Whenever an update occurs in the Secondary entity object, the primary entity
object will also be notified and its post transaction processing will send the view object
data from both entity objects to Oracle Social Network.
These implementation steps are required to enable Oracle Social Network for
multi-entity entity objects. This assumes the pre-condition of the accessor being as
described at the beginning of this section.
Open the EOCollImpl class for the entity object in the source editor.
EOCollImpl.java
@Override
protected EntityImpl add(EntityImpl srow)
{
66-20 Developer's Guide
What happens when the secondary Entity Object Accessor Registration occurs
The "add" method override accomplishes these actions:
Ensures that Oracle Social Network integration on the primary entity object exists
before performing any registration.
Ensures that the accessor provided refers to an instance of an OAEntityImpl object.
Checks to see that attributes in the Secondary entity object are to be sent to Oracle
Social Network as marked in the view object. If there are no fields from the
Secondary entity object to be sent, then no listener will be registered. If there are
fields to be sent to Oracle Social Network, then an internal reference is set up in
the instance of the Secondary entity object marking that column it is to track for
Oracle Social Network.
At runtime, each entity object will track which fields are to be sent to Oracle Social
Network (if any). When a post action occurs, the Secondary Entity Object will notify
the Primary Entity Object that it has been modified. The Primary Entity Object
retrieves the associated view object to collate all fields that have been traced for
sending to Oracle Social Network from all participating entity objects. The view object
then will perform the send to Oracle Social Network. The Primary Entity Object will
ensure that if multiple Secondary Entity Objects are modified, then only one send to
Oracle Social Network will occur.
What happens if "add" in the Primary EOCollImpl is not performed and attributes
from the Secondary entity object have been marked as Oracle Social Network enabled
in the view object?
There are three types of events that will occur:
Primary entity object fields only updated - When the post event occurs on the
Primary entity object and those fields in the Primary entity object will be sent to
Oracle Social Network.
Primary entity object and Secondary entity object fields updated - When the post
event occurs, it will fire on the Primary entity object. Because the send is done
from the view object, all fields that can be sent to Oracle Social Network from both
the Primary and Secondary entity objects will be sent to Oracle Social Network.
Secondary entity object fields only updates - Only a post transaction event will
occur on the Secondary entity object and therefore no data will be sent to Oracle
Social Network.
What if Multiple Updateable Entity Objects View are included in View Object as
non-reference
Having multiple entity objects included in the view object is generally not
recommended by the BC4J framework but is possible to implement. The complication
for Oracle Social Network integration is that it uses the non-reference entity object to
identify the Primary Entity Object. If there are multiple non-reference entity objects
within the view object, then it is most likely that the Oracle Social Network integration
will choose the incorrect entity object to be the Primary Entity Object. The solution to
this is to add the fnd:OSN_PRIMARY_EO property to the view objects properties and
provide the EntityUsage name of the entity object to use as the Primary Entity Object.
This property can only be added in the view object source because there intentionally
is no Property Inspector fnd:OSN_PRIMARY_EO property.
This example demonstrates the use of the fnd:OSN_PRIMARY_EO property.
<ViewObject
xmlns="http://xmlns.oracle.com/bc4j"
Name="MeoDeptAttachNonReferenceVO"
xmlns:fnd="http://xmlns.oracle.com/apps/entityview">
<Properties>
<SchemaBasedProperties>
<fnd:OSN_PRIMARY_EO Value="MeoFndDemoDeptEO"/>
</SchemaBasedProperties>
</Properties>
<EntityUsage
Name="MeoFndDemoDeptEO"
Entity="oracle.apps.fnd.applcore.socialnetwork.model.test.setup.multieo.attach.Meo
FndDemoDeptEO"/>
</ViewObject>
By identifying which entity object is the Primary Entity Object for the view object, the
Manage Oracle Social Network Objects UI will correctly configure the Oracle Social
Network integration to ensure all send requests are sent using the declared Primary
Entity Object.
Warning: fnd:OSN_PRIMARY_EO only needs to be implemented
where there are multiple entity objects in the view objects that are
flagged as non-reference. If there is only one entity object in the view
object as non-reference, do not set this flag.
When not to use multiple updateable entity objects Oracle Social Network
Integration for a view object
Consider this scenario:
There are two view objects: the first view object (FirstVO) has two entity objects
contained within it (OneEO + TwoEO) and the second view object (SecondVO) has
only one entity object in it (TwoEO).
The secondary entity object of the first view object (TwoEO) is the primary, and
only, entity object of the second view object.
In this scenario, it does not make sense to use Oracle Social Network integration as
there will be a synchronization issue. Since there are two view objects that contain data
from TwoEO, there will be two Social Objects in Oracle Social Network that contain
this data. When TwoEO data is updated from the SecondVO, only the Social Object
that relates to the SecondVO will be updated. There is no way to determine that the
FirstVO has been affected and its data should be re-synchronized to Oracle Social
Network. The following is the recommended outcome to ensure that the data remains
synchronized on Oracle Social Network:
Do not perform the Secondary entity object registration steps as outlined in the
Additional Advanced Configuration - View Objects That Have Multiple
Updatable Entities section.
Leave the second view object to send all updateable information relating to the
secondary entity object (TwoEO).
In the first view object, only include attributes from the secondary entity object
that will not change after the Social Object has been created. For example: Social
Object title or primary key value.
In the first view object you should include attribute values that will help an end
user find the associated Social Object for the second view object. For example:
Social Object title or primary key value.
66.2.1.9 Configuring Multiple View Objects to Share the Same Social Object
A common scenario in Fusion Applications is to have two different UI pages for a
single Business Object:
A summary page that outlines the information in a logical read-only way and may
include other information that is logical to show with that object.
An edit page where the information about that object can be modified.
To achieve this in Fusion Applications, two different view objects are required (one per
page) that refer to the same business object (such as Opportunity). Therefore, a logical
business requirement would be to have both view objects update and view the exact
same Social Object on the Oracle Social Network server. This would require Oracle
Social Network to enable both view objects individually, because they need to be able
to access the Oracle Social Network server independently of each other. The following
instructions demonstrate how to share the same Social Object when there are two
different view objects that can provide the attribute definitions, translations, and so on.
Before you begin
Pick one of your view objects which will be the Reference View Object. The Reference
View Object:
Is a view object that has already been Oracle Social Network-enabled using these
instructions.
Will be used as an "Oracle Social Network integration template" for all other view
objects that will share the same Social Object.
Nav View Id
Nav Taskflow Id
Task Label
2.
3.
For each attribute, note the attribute property values for these properties:
Object Key
66.2.1.9.1 Configuring the Reference View Object to Be Enabled by Oracle Social Network To
configure the Reference View Object to be enabled by Oracle Social Network:
Open the Reference View Object and in the property inspector set the
Applications > Oracle Social Network > Definition Name property. This will
ensure that the view object's Oracle Social Network definition name will be
consistent among all the view objects that are sharing the Social Object. This
definition name must have the application short name at the beginning, and
should be unique from all other existing view objects that are not to share the
Social Object.
[Optional] If there are any translated values that are different between the two
view objects, set the Registration VO property on the view objects to true. This
will set the fnd:OSN_REGISTRATION_VO property on the view objects and
ensure that any translations are read from this view object.
66.2.1.9.2 Configurating the Other View Objects to Be Enabled by Oracle Social Network For
each view object (not the Reference View Object):
Set the Oracle Social Network Gadget Type, Oracle Social Network User Key,
Object Key and Currency Code Attribute property value to those noted in the
Before you begin steps.
Has the Oracle Social Network Attribute Name Override been set in the
attribute of the Reference View Object?
If Yes, set the Oracle Social Network Attribute Name Override to be the
same value between the two attributes.
If No, set the Oracle Social Network Attribute Name Override to be the
name of the attribute in the Reference View Object unless the two attribute
names are the same.
Open the Add OSN View Instances wizard by right-clicking the Application
Module containing the view objects and selecting the wizard.
Shuttle the view objects from the Available View Objects to the Data Model.
This will ensure that all view objects are set up to use the same Oracle Social Network
Social Object.
Social Link Configuration
Because each view object now is set up to match the Social Object definition in Oracle
Social Network, the row from the view object that is on the page that is being
displayed can be used as the osnRow in the applications panel.
What happens when a transient entity object/view object is used for Oracle
Social Network Integration
When a row is created or inserted in the transient view object, populated with attribute
data, and the commit happens, the row's data is sent to Oracle Social Network as a
create request. This works well for transient entity objects and view objects.
It is during an Update that the situation becomes less clear. Due to the nature of
transient view objects and entity objects, such as when they have no persistent state, it
is impossible to change their entity state away from STATUS_NEW/INITIALIZED
until a commit occurs on that instance of the transient entity object or view object. The
Oracle Social Network integration uses the entity state to determine whether to
perform a create/update/delete request to Oracle Social Network. However, the
Oracle Social Network client library handles the update issue. When a second create
request to Oracle Social Network that contains all of the Social Object fields (view
object attributes) that were sent to Oracle Social Network originally, it will detect that
the Social Object was already created and only will perform an update of the fields
whose values have changed between the two Oracle Social Network sends. The only
issue with this is in the detail: all fields need to be sent though the second time, even if
the field value has not changed. If a field value is not supplied, it will be treated as if
null was sent and the field value removed from Oracle Social Network, but if the field
value is supplied and its value has not changed, then the field will be treated as
not-updated.
Therefore, the update solution becomes a non-issue as the transient view object can be
populated in the exact same mechanism and committed in the same way as the
original insert. When the payload of the second create request gets to Oracle Social
Network, it will determine the correct course of action for the insert/update of the
Social Object data.
Descriptive Flexfields
The Oracle Social Network integration supports descriptive flexfields which have
been deployed for an Oracle Social Network-enabled view object. An Oracle
Fusion applications developer does not need to configure any properties at design
time to enable the descriptive flexfield integration. When the Functional
Administrator uses the "Manage Social Network Objects" UI to add attributes to
send to Oracle Social Network, the descriptive flexfields attributes will also be
shown in the list in a tree structure organized by value set. For more information
about adding custom attributes using descriptive flexfields, see the "Define
Flexfields" section in the "Define Applications Core Configuration" chapter of the
Oracle Fusion Applications Common Implementation Guide.
Parameters
[pageTitle]
The parameters values that can be provided are shown in Table 664.
Table 664
Parameter
Description
moduleType
Default Value
The module key to filter the view objects in the task flow. The
When no value is supplied, all
mapping between the module key and the application modules modules will be shown.
comes from the fnd-osn-integration.xml setup in the "Add OSN
View Instances" wizard.
pageTitle
In Functional Setup Manager, Applications Core will add the "Manage Oracle Social
Network Objects" task to provide access to the setup task flow with no moduleType or
moduleKey specified. This task will give access to the task flow for managing any
Oracle Social Network object in Oracle Fusion Applications.
You can create your own product module-specific Oracle Social Network setup tasks
in your own task lists that provide access to the setup task flow but filtered by the
relevant modules. For example, Financials can create a Manage Financials Oracle
Social Network Objects passing in the correct moduleType and moduleKey.
If a valid moduleType and moduleKey pair is specified, the UI provides access to all
objects whose modules roll up to the specified module. That is, if a family is specified,
the UI displays all objects whose modules roll up to the family.
Oracle Social Network Object settings are moved using the
customization sets on the Customization Migration page instead of
using the export and import function in the Setup and Maintenance
work area of Functional Setup Manager. Customization Migration is
not module-specific.
Note:
Before adding this block to the jazn-data.xml file, verify if there is already a grant
block for the URL ${domain.home}/servers/${weblogic.Name}/tmp/_WL_
user/oracle.social.client/-. If this already exists, then just add the <permission>
node to the existing grant.
multiple times on the Oracle Social Network server, thus allowing each developer to
have his or her own Social Object registration.
image + link
link only
image + button
button only
The component itself has been integrated out of the box as a link in 2 places using
Applications Core and is available for use by developers.
The Social link has been added as a text-only link to the Global Area/Menu as shown
in Figure 662. Therefore, the link will be available on all Oracle Fusion application
pages.
Figure 662 Social Link in the Global Area
Note:
When the Social link is clicked, the Oracle Social Network UI is launched on the right
side as shown in Figure 663. This view displays all the Conversations, Social Objects,
Users and Groups to which a user has access (displayed within the All tab in the
Oracle Social Network UI).
Figure 663 Example of the Oracle Social Network Popup
The Social link also is added to the left of the toolbar (buttons) in the application panel.
The link will appear automatically in Oracle Fusion application pages if the
application panel has been used for object detail pages.
Clicking the Social link in the application panel also launches the Oracle Social
Network UI on the right side as a layover panel. In this view, Oracle Social Network
UI is displayed in the context of the current Oracle Fusion application page or object.
The Social link in the Application Panel typically appears as shown in Figure 664.
Figure 664 Example Showing the Social Link in an Applications Panel
The link currently is supported only within the application panel. The Social link
should not be directly consumed outside an application panel. Also, you should not
use the Oracle Social Network ADF declarative component (link/button) directly.
When the Social link is clicked from within the application panel, the Oracle Social
Network UI should appear as shown in Figure 665. Within the Oracle Social Network
UI there are 2 tabs:
In the context of the Oracle Fusion application Object (depending on the context
passed as explained below), the Oracle Social Network UI displays the associated
Social Object and any Related Conversations.
The All tab displays all the Conversations, Social Objects, Users and Groups to
which a user has access.
66.4.1 How to Render the Behavior of the Social Link in an Application Panel
There are some checks made internally within the application panel and in the Oracle
Social Network ADF declarative component that control the display of the Social link
in the Oracle Fusion application pages.
The Social link in the application panel will render only when some context is passed
to the application panel. The rules that control the rendering are:
If the Oracle Social Network URL is not configured, the link will not show (it also
will not show in the Global Menu).
If there is no context passed to the application panel, the link will not render. The
end-user will need to use the link from the Global Menu to see all Oracle Social
Network Conversations and Social Objects.
If the view object is not enabled (out of the box using Design Time) for Oracle
Social Network, then the link will not render. See Section 66.2.1.1, "Configuring the
Business Object for Oracle Social Network Integration."
If the view object is enabled (out of the box using Design Time) for Oracle Social
Network, but the Oracle Social Network task flow has not been enabled using
Oracle Fusion Functional Setup Manager, then the link will not render.
Developers can control the rendering of the Social link by
setting an Expression Language expression on the osnRendered
attribute (see Table 665). For example, when the same UI is used for
both create and edit cases, the developer may want to hide the Social
link in the Create case because the business object may not be ready at
that point.
Note:
The application panel exposes a subset of parameters that can be used to control the
behavior of the Oracle Social Network Social link. Some additional parameters
exposed by the Oracle Social Network Social ADF component are used internally by
the application panel and are not exposed. Table 665 lists the parameters available to
control the behavior of the Social link and pass the context to it:
Table 665
Attribute
Name
Type
Description
Valid Values
osnDisabled
Boolean
osnRendered
Boolean
Explicitly controls (apart from internal checks made) true or false. The default
whether or not to render the Social link. This is
is true.
optional.
osnRow
osnType
String
osnTypeGroup
String
osnDisableSh
are
Boolean
osnDisableJo
in
Boolean
Do not use.
Examples of Parameters
The Share button is displayed when the view object is enabled with Manual mode
and the object has not yet been shared in Oracle Social Network. In Automatic
mode, you should not see the Share button unless the business object was created
before it was Enabled for OSN. This is because the Oracle Social Network Social
What Happens When Functional Administrators Manage Oracle Social Network Objects
Object will be created automatically when the Oracle Fusion application business
object is created. In this case, the Share button will be displayed and the user can
choose to create the Oracle Social Network Social Object manually.
Once a user clicks the Share button, the button will not be displayed again, unless
there is an error in sharing with Oracle Social Network. The Oracle Social Network
UI then displays the Social Object.
The Join button is displayed for both Manual and Automatic modes for the
current user who is not yet a member of the Social Object in Oracle Social
Network. The Join button will be displayed only after the object is shared, either
automatically or manually by another user, in Oracle Social Network.
Once a user clicks the Join button, the user is made a member of the Social Object
in Oracle Social Network. The Oracle Social Network UI then displays the Social
Object and any related conversations.
The Join and Share buttons can be hidden by setting the osnDisableShare and
osnDisableJoin parameters to the application panel. See Table 665.
The deployed JAR files containing the view object definitions and the
META-INF/fnd-osn-integration.xml file must be in the classpath of the product
team's Functional Setup Manager.
The Functional Setup Manager has had the "Manage Social Network Objects" task
flow added to it.
The person fulfilling the provisioner role has set up the Oracle Social Network
location and the Oracle Social Network credential.
Select the view object in the Business Objects tree that is to be Oracle Social
Network enabled.
Click Enable OSN Tracking.
What Happens When Functional Administrators Manage Oracle Social Network Objects
Manual - The end user consuming the Oracle Fusion application will need to
click the Share button to send the view object row to Oracle Social Network.
Automatic - When the end user commits the view object row with which they
are working, the send to Oracle Social Network will occur automatically.
None - Disable Oracle Social Network integration.
Click OK.
The view object shown in the tree now will have the updated Enabled status to match
the selection. There is a shortcut to disabling Oracle Social Network integration for a
view object by selecting it in the Business Objects tree and clicking Disable OSN
Tracking.
66.5.2.1 How to Add and Remove Attributes to Send to Oracle Social Network
Changing the OSN Enabled state of the view object is only the first half of the
configuration that is required to send a Social Object to Oracle Social Network. The
attribute values that will become the Social Object fields also need to be selected. Use
these steps to select the attributes that will be Oracle Social Network enabled:
Select the view object in the Business Objects tree that is to have attributes Oracle
Social Network enabled. This should show the list of Oracle Social Network
enabled attributes in the table at the bottom of the page.
Click New. This will display a dialog showing all of the attributes that the
developer marked as Oracle Social Network integration available.
Check or uncheck the checkboxes next to each attribute to add and remove
attributes. Attributes that are selected are Oracle Social Network enabled.
Click OK.
The attributes that were checked in the dialog will now be shown in the table at the
bottom of the page. This is the list of attributes for the view object that have been
marked as Oracle Social Network enabled. There is a shortcut for marking the
attributes as not Oracle Social Network enabled. Select the attribute and click Delete to
remove them from the list.
What Happens When Functional Administrators Manage Oracle Social Network Objects
XML. When Save is clicked, the custom properties for these view objects are
changed:
In addition to the view object property being modified, the primary entity object
for the view object will have these custom properties set upon it:
Since the view object and entity object definition XML cannot be changed at
runtime, these modifications will be stored in Oracle Metadata Services (MDS) at
the persdef layer. For each view object that was displayed in the "Manage Social
Network Objects" there will be four persdef files and entries stored. An example of
these files are for the SndDemoDeptVO:
persdef/oracle/apps/model/entity/mdssys/cust/site/site/SndDemoDeptEO.xml.xml
persdef/oracle/apps/model/entity/SndDemoDeptEO.xml
persdef/oracle/apps/model/view/SndDemoDeptVO.xml
persdef/oracle/apps/model/view/mdssys/cust/site/site/SndDemoDeptVO.xml.xml
These entries can be imported and exported if the enabled Oracle Social Network
integration configuration must be ported between server instances.
What Happens When Functional Administrators Manage Oracle Social Network Objects
When Save is clicked, a progress popup will be shown that displays the current
status of the save and send to the OSN server.
66.5.5 Synchronizing
If there is an issue with a previous send to the Oracle Social Network server within
"Manage Oracle Social Network Objects" UI or a migration of Oracle Social Network
integration configuration has occurred between servers then the state of the definition
on the Oracle Social Network server will be different to what is stored in persdef. To
correct this, the Synchronize button was added which will take the definition of all
view objects and resend them to Oracle Social Network. An individual view object be
synchronized in isolation by selecting a view object in the Business Objects table and
clicking Synchronize at the top of the Business Objects table.
What Happens When Clicking Synchronize
Each view object that is displayed and that has an Enabled state of automatic/manual,
will have its Oracle Social Network definition re-created and sent to the Oracle Social
Network server. To confirm if the synchronized view objects are correctly seeded in
Oracle Social Network, the social definition URL for the view object can be used to
verify the Social Object definition. When the page-level Synchronize button is clicked,
a progress popup will be shown that displays the current status of the send to the
Oracle Social Network server. The progress indicator is not shown for the Synchronize
button in the Business Objects table.
66.6 What Happens When End Users Interact with Oracle Social Network
Object Instances
The only decision an end user needs to make is to share instances when Manual
integration mode is enabled.
Automatic Integration
When Oracle Social Network is enabled as Automatic for a view object, end users will
not see any visual signs that a send to Oracle Social Network has occurred with the
data they just committed. The first that they will know about this is when they check
in Oracle Social Network and the record has been created in Oracle Social Network.
Any future updates or deletes (Oracle Social Network Conversation Close) also should
be reflected in Oracle Social Network upon any further commits of the row.
Manual Integration
When Oracle Social Network is enabled as Manual for a view object, the end users
should be able to see the Oracle Social Network Share button on the page. If the users
create or update the record, they should not see any information about that view object
row in Oracle Social Network. After they have committed the row, they can click
Share, which will do the initial send of the row data to Oracle Social Network. By
clicking Share, after the initial record has been sent to Oracle Social Network, a new
window should appear with the conversation displayed within it (if the socialShare
component was set to launch=true when it was configured in the page). Any future
updates or deletes (Oracle Social Network Conversation Close) should also be
reflected in Oracle Social Network upon any further commits of the row.
After configuring the Oracle Fusion Developer role, deploy the model library that
contains the META-INF/fnd-osn-integration.xml file and the view object
definitions into an ADF Library JAR file.
Include this JAR file as a library in the Functional Setup Manager project.
Deploy and run the Functional Setup Manager in an Integrated WebLogic Server
environment.
Log into the Functional Setup Manager and choose the Manage Social Network
Objects task.
Find the view object that has been configured as available for Oracle Social
Network integration, change it to have an Enabled state of Automatic and add all
the attributes to the list of Oracle Social Network enabled attributes.
Click Save to keep the Automatic enabled state and attribute configuration, and
send the Social Object registration to Oracle Social Network.
Deploy and run the application that uses the deployed library from the first step.
Log in to the application and find the product page that uses the view object.
Create a new row for the view object, fill in the required data and commit the row.
Implementing Oracle Social Network Integration 66-37
Log in to Oracle Social Network using the same user as logged in to the
application and see the Social Object representing the newly-created or committed
view object row.
The same MDS partition must be used for both Functional
Setup Manager and for Oracle Fusion Applications. If this is not done,
the Oracle Social Network integration will not be carried between the
two applications.
Note:
Part IX
Part IX
Appendices
The appendices provide information about how to work with the Oracle Fusion
application taxonomy, and a reference for the commands available for the Oracle
Enterprise Crawl and Search (ECSF) Command Line Administration Utility.
The Oracle Fusion Applications taxonomy organizes the components and functions of
Oracle Fusion Applications into a hierarchical structure. Every Oracle Fusion
development artifact or file is tagged with an owning functional component.
Components are grouped hierarchically into larger units, such as more general
components, products and product families.
ECSF Command Line Administration Utilities provides a reference for the commands
available for the Oracle Enterprise Crawl and Search (ECSF) Command Line
Administration Utility. You can use the ECSF Command Line Administration Utility to
quickly test and manage the searchable objects without having to use Oracle
Enterprise Manager Fusion Applications Control for ECSF.
This part contains the following appendices:
A
Working with the Application Taxonomy
This appendix describes the theory of the Oracle Fusion application taxonomy, how to
view the taxonomy, and how to extract taxonomy data from a table and how to insert
taxonomy data into a table.
This appendix describes:
How to extract taxonomy data from a table and how to insert taxonomy data into
a table
Section A.2, "Working with Objects and Methods in the Application Taxonomy"
It is important to note that there is no tool for working with the taxonomy; developers
use public business objects and do all work within JDeveloper. In general, only
developers who are referring to modules, such as Application, will need to work with
the taxonomy.
In the taxonomy user interface, the hierarchy would appear similar to the example
shown in Figure A1:
A-1
Patch Creation
System Administration
Patches will be tagged with the versions they contain. When a patch is applied,
dependency information in the taxonomy can be used to determine which parts of the
system will be affected. This can be used to assess system testing requirements after
the patch is applied, or to schedule partial downtimes while patching is in progress.
A-3
The delivery hierarchy represents the relationships between files and the application
team that is responsible for the development, maintenance, and delivery of those files.
Nodes within the delivery hierarchy have unique parents, so there is one path through
the delivery hierarchy to any given file.
A.1.5 How to Integrate Taxonomy Task Flows into Oracle Fusion Functional Setup
Manager
Every application registers task flows with the Functional Setup Manager that
provides a single, unified user interface that allows customers and implementers to
configure all Oracle applications by defining custom configuration templates or tasks
based on their business needs.
The Functional Setup Manager UI enables customers and implementers to select the
business processes or applications that they want to implement. For example, a
Human Resources application can register setup activities like "Create Employees" and
"Manage Employee Tree Structure" with the Functional Setup Manager. Trees task
flows then provide the mechanism for an application team to register an activity such
as "Manage Employee Tree Structure," which in this case, is a tree structure task flow
with the tree structure code parameter set to some HR tree structure. Table A1 lists
the task flow and its parameters.
Table A1
/WEB-INF/oracle [pageTitle]
/apps/fnd/applc
ore/taxonomy/ui
/taskflow/ViewD
eliveryHierarch
y.xml#ViewDeliv
eryHierarchy
The Manage
Taxonomy
Hierarchy
accepts the
optional
parameter
[pageTitle] and
navigates to the
Taxonomy
Delivery
Hierarchy page.
Comments
This page serves
as the starting
point from which
a user can select
a particular node
and perform the
available actions,
such as create,
update, and view
components for a
selected node.
From this page, a
user can navigate
to other task
flows, such as
Search Hierarchy,
View
Components and
Search
Components.
Who Columns
Column Name
Type
Null?
CREATED_BY
VARCHAR2(64)
Not Null
CREATION_DATE
TIMESTAMP
Not Null
LAST_UPDATED_BY
VARCHAR2(64)
Not Null
LAST_UPDATE_DATE
TIMESTAMP
Not Null
LAST_UPDATE_LOGIN
VARCHAR2(32)
If the table has "extended Who" columns used to track updates by Oracle Enterprise
Scheduler Service programs, the columns must be changed to those shown in
Table A3. You do not need to add extended Who columns if the table does not
already have them.
Table A3
Column Name
Type
Null?
REQUEST_ID
NUMBER(20)
NULL
JOB_DEFINITION_
NAME
VARCHAR2(100)
NULL
JOB_DEFINITION_
PACKAGE
VARCHAR2(900)
NULL
A-5
The service methods use the default Oracle Fusion application line value of 1. The
application module APIs that do not accept an application line id assume that the data
is being queried for the Oracle Fusion application line.
If you query directly against the taxonomy tables, you must take into account the
application line denormalization. You will have to add the filter product_line =
<appropriate application line id> to prevent returning multiple rows for a given
module key or id.
ApplTaxonomyPEO
ApplTaxonomyTranslationPEO
ApplTaxonomyHierarchyPEO
ApplicationPVO: This view object is shaped to match the Application view object
that was on top of the FND_APPLICATIONS view. Note that FND_
APPLICATIONS, which was a table in R12, has now been changed to a view on
top of Taxonomy tables. It has these view criteria exposed:
ApplTaxonomyApplicationPVO
A-7
In the Resource Palette, open the folder icon and select New Connection > File
System as shown in Figure A2:
2.
3.
The new connection will display in the Connections tree, shown in Figure A4:
4.
The Entity and View objects are located in Taxonomy-Model.jar > Business
Components, shown in Figure A5:
Figure A5 Locating the Entity and View Objects in the Connections Tree
A-9
ApplTaxonomyAMImpl am =
(ApplTaxonomyAMImpl)OAApplicationModuleImpl.getFNDNestedService(OAConstants.TAXONO
MY_SERVICE,myAM.getDBTransaction());
Where myAM is the application module that you are working with. You can also create
an instance of the ApplTaxonomyAMImpl class directly as needed.
To access a taxonomy node for a given application module, you can call the
getTaxonomyModule() API on the module ID:
ApplTaxonomyFullDeliveryVORowImpl row = am.getTaxonomyModule(new
oracle.jbo.domain.Raw("025000"));
To access the module name for that node, you can make a call to getModuleName():
String moduleName = row.getModuleName();
To access a set of taxonomy nodes for a given module type, you can call the
getTaxonomyModules() API:
ApplTaxonomyFullDeliveryVORowImpl[] rows =
am.getTaxonomyModules("FAMILY");
These APIs work if the existing data in FND_APPLICATIONS has been migrated to
the Oracle Application Taxonomy tables.
Topology MBean: Provides information about the topology of the Oracle Fusion
environment. Topology MBean data is dependent on the domain against which it
A-11
is tested. In a particular domain, such as Setup, you can have more than one
Product Family.
Log Configuration MBean: Provides utilities for configuring logs at both Userand Site-level in an application.
Topology MBean
Topology MBean Details:
MBean Name oracle.topology:name=Topology,type=TopologyRuntimeMBean
Description Applications Core Topology MBean that provides the information about
overall Oracle Fusion Topology
Name
Description
Access
AllProductFamilyAndDomains
ConfigMBean
CurrentDomain
CurrentPillarInfo
CurrentPillarInstanceInfo
CurrentProductFamily
CurrentProductFamilyInfo
eventProvider
eventTypes
ListOfProducts
objectName
PillarDBInfo
Pillars
Description
Access
ReadOnly
RestartNeeded
stateManageable
statisticsProvider
SystemMBean
Name
Description
Array of
javax.management.openmbean.T
abularData
getAllEnterpriseAp
psInfo
Array of
javax.management.openmbean.T
abularData
getAppListFromDe
ployedDomain
Array of
javax.management.openmbean.T
abularData
getDependentApps
Array of
javax.management.openmbean.T
abularData
Array of
javax.management.openmbean.T
abularData
Array of
javax.management.openmbean.T
abularData
Array of
javax.management.openmbean.T
abularData
getDeployedDomai
nFromPillar
Array of
javax.management.openmbean.T
abularData
getDeployedDomai
nInfo
javax.management.openmbean.T
abularData
Array of
javax.management.openmbean.T
abularData
getDeployedDomai
nsByEnvironment
javax.management.openmbean.T
abularData
getDomainnames
Array of java.lang.String
A-13
Description
getEndPointInfo
Array of
javax.management.openmbean.T
abularData
Array of
javax.management.openmbean.T
abularData
javax.management.openmbean.T
abularData
javax.management.openmbean.T
abularData
getLbasInfo
Array of
javax.management.openmbean.T
abularData
getListOfDeployed
Apps
Array of java.lang.String
getListOfDomains
Array of java.lang.String
getListOfEnterprise
Apps
Array of java.lang.String
getListOfLbas
Array of java.lang.String
Name
Description
Access
ConfigMBean
eventProvider
eventTypes
LogConfigInformation
objectname
ReadOnly
RestartNeeded
stateManageable
statisticsProvider
SystemMBean
Table A7
Name
Description
addUserLogConfig
boolean
deleteUserLogConfig
void
editUserLogConfig
boolean
getUserInfo
javax.management.open
mbean.TabularData
Array of
javax.management.open
mbean.TabularData
updateLogConfigInformation
void
A-15
B
ECSF Command Line Administration Utility
This appendix provides a reference for the commands available for the Oracle
Enterprise Crawl and Search (ECSF) Command Line Administration Utility. You can
use the ECSF Command Line Administration Utility to quickly test and manage the
searchable objects without having to use Oracle Enterprise Manager Fusion
Applications Control for ECSF.
Administrators should use Fusion Applications Control for
ECSF to manage the life cycle of searchable objects in the production
environment.
Note:
Table B1 shows the commands you can use to administer search. The commands
appear in alphabetical order.
Table B1
Command
Description
activate object ID
Associates the searchable object you specify with the search category you
specify. Specify the ID number corresponding to the searchable object you want
to add to the search category, and specify the ID number corresponding to the
search category to which you want to add the searchable object.
Searchable objects must be deployed before you can associate them with search
categories. Search categories must be undeployed before you can associate
searchable objects with them. You can associate the same searchable object with
multiple search categories. You must issue the command while managing the
search engine instance with which the search category is associated.
Associates a searchable object with the search category you specify. Specify the
ID number corresponding to the search category to which you want to add the
searchable object. The ECSF Command Line Administration Utility displays a
list of available searchable objects and prompts you to enter the ID
corresponding to the searchable object you want to associate with the search
category.
Searchable objects must be deployed before you can associate them with search
categories. Search categories must be undeployed before you can associate
searchable objects with them. You can associate the same searchable object with
multiple search categories. You must issue the command while managing the
search engine instance with which the search category is associated.
B-1
Description
Associates the searchable object you specify with the index schedule you
specify. Specify the ID number corresponding to the searchable object you want
to add to the index schedule, and specify the ID number corresponding to the
index schedule to which you want to add the searchable object.
Searchable objects must be deployed before you can associate them with index
schedules. You can only associate each searchable object with one index
schedule. Only a searchable object that is not already associated with an index
schedule can be added to an index schedule. Index schedules must be
undeployed before you can associate searchable objects with them. You must
issue the command while managing the search engine instance with which the
index schedule is associated.
Associates the searchable object you specify with the index schedule you
specify. Specify the ID number corresponding to the index schedule to which
you want to add the searchable object. The ECSF Command Line
Administration Utility displays a list of available searchable objects and
prompts you to enter the ID corresponding to the searchable object you want to
associate with the index schedule.
Searchable objects must be deployed before you can associate them with index
schedules. You can only associate each searchable object with one index
schedule. Only a searchable object that is not already associated with an index
schedule can be added to an index schedule. Index schedules must be
undeployed before you can associate searchable objects with them. You must
issue the command while managing the search engine instance with which the
index schedule is associated.
Associates a searchable object with the specified search engine instance. The
ECSF Command Line Administration Utility displays a list of available
searchable objects and prompts you to enter the ID corresponding to the
searchable object you want to add to the search engine instance.
You must issue the command while managing the search engine instance to
which you want to add the searchable object. A searchable object can only be
associated with one search engine instance at a time.
Associates a searchable object with the specified search engine instance. Specify
the ID corresponding to the searchable object you want to add to the search
engine instance.
You must issue the command while managing the search engine instance to
which you want to add the searchable object. A searchable object can only be
associated with one search engine instance at a time.
connect to database
Creates the connection to a database using a system identifier (SID). Follow the
prompts to enter a username and password, as well as field values.
connect to database
hostname port SID
Creates the connection to a database using a system identifier (SID). Specify the
host name, port number, and SID. Follow the prompts to enter a username and
password.
connect to database
descriptor
Description
connect to database
descriptor 'descriptor'
Creates the connection to a database using a service name. Follow the prompts
to enter a username and password, as well as field values.
Creates the connection to a database using a service name. Specify the host
name, port number, and service name. Follow the prompts to enter a username
and password.
connect to mbeanserver
connect to mbeanserver
hostname port
Creates the connection to an MBean server. Specify the host name and port
number. Follow the prompts to enter a username and password.
create category
create instance
Adds a new search engine instance to the specified search engine type. Follow
the prompts to enter field values. You must issue the command while not
managing a search engine instance.
Adds a new search engine instance to the specified search engine type. Directly
pass in field name-value pairs with the command.
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
You must issue the command while not managing a search engine instance.
B-3
Description
create object
Adds a new searchable object to the specified search engine type. Follow the
prompts to enter field values.
If you issue the command while managing a search engine instance, the
searchable object is automatically associated with the search engine instance you
are managing. If you issue the command outside a search engine instance
context, the ECSF Command Line Administration Utility displays a list of the
available search engine instances and prompts you to choose a search engine
instance for the searchable object you want to create.
create schedule
Adds a new searchable object to the specified search engine type. Follow the
prompts to enter field values. The searchable object is not associated with a
search engine instance.
deactivate object ID
delete category ID
Disassociates the specified search category from the search engine instance and
removes it from the ECSF_SEARCH_INDEX_GROUP table in the Oracle Fusion
Applications database. Specify the ID number corresponding to the search
category you want to delete.
You must issue the command while managing the search engine instance with
which the search category is associated.
delete instance ID
Removes the specified search engine instance. You cannot delete search engine
instances while you are managing an engine instance. You cannot delete a
search engine instance if there are any deployed objects, categories, or schedules
associated with it.
Description
delete object ID
delete schedule ID
Disassociates the specified index schedule from the search engine instance and
removes it from the ECSF_INDEX_SCHEDULE table in the Oracle Fusion
Applications database. Specify the ID corresponding to the index schedule you
want to delete.
You must issue the command while managing the search engine instance with
which the index schedule is associated.
deploy category ID
Deploys the specified search category to the search engine instance. Specify the
ID number corresponding to the search category you want to deploy.
Searchable objects must be associated with the search category before you can
deploy it. You must issue the command while managing the search engine
instance with which the search category is associated.
deploy object ID
Deploy the searchable object you specify to the search engine instance to make
the objects available for the search engine instance to crawl. Specify the ID
number corresponding to the searchable object you want to deploy.
The searchable objects deployed to the search engine instance must have a
unique and fully qualified name, for example, oracle.apps.crm.Opportunity
or oracle.apps.hcm.Opportunity. Only a searchable object that is associated
with a search engine instance can be deployed.
Collectively updates all deployed searchable objects with the latest search
engine instance parameters.
Updates the specified searchable object with the latest search engine instance
parameters.
deploy schedule ID
Deploys the specified index schedule to the search engine instance. Specify the
ID number corresponding to the index schedule you want to deploy.
Searchable objects must be associated with the index schedule before you can
deploy it. You must issue the command while managing the search engine
instance with which the index schedule is associated.
disconnect
exit
help
help activate
help add
help category
help connect
B-5
Description
Lists the fields available for the create unassigned object command.
help deactivate
help delete
help deploy
help disconnect
help instance
Lists the commands that can be used for search engine instances.
help list
help manage
help object
help param
Lists the commands that can be used for search engine instance parameters.
help remove
help schedule
help set
help showdetails
help start
help stop
Lists the commands that can be used for unassigned searchable objects.
help undeploy
help unmanage
Lists one by one all the external categories of the search engine instance you are
managing and prompts you to confirm whether you want to import each
external category. Enter Y to import the external category, which adds it to the
ECSF_SEARCH_INDEX_GROUP table in the Oracle Fusion Applications database.
Enter N to cancel the importing of the external category. The default value is N.
All external search categories that have been previously imported will be
replaced by the latest import from Oracle Secure Enterprise Search (Oracle SES).
If you had previously deleted any of the records corresponding to the external
search categories, you must delete them again to make them unavailable for
querying.
Description
Lists one by one all the external categories of the search engine instance you
specify and prompts you to confirm whether you want to import each external
category. Enter Y to import the external category, which adds it to the ECSF_
SEARCH_INDEX_GROUP table in the Oracle Fusion Applications database. Enter N
to cancel the importing of the external category. The default value is N.
All external search categories that have been previously imported will be
replaced by the latest import from Oracle Secure Enterprise Search (Oracle SES).
If you had previously deleted any of the records corresponding to the external
search categories, you must delete them again to make them unavailable for
querying.
list categories
Lists the search categories and their corresponding ID numbers for the search
engine instance you are managing.
Lists the search categories and their corresponding ID numbers for the search
engine instance you specify. Specify the ID number corresponding to the desired
search engine instance.
Lists the external search categories and their corresponding ID numbers for the
search engine instance you are managing.
Lists the external search categories and their corresponding ID numbers for the
search engine instance you specify. Specify the ID number corresponding to the
desired search engine instance.
list instances
list objects
Lists a summary of the searchable objects associated with the search engine
instance you are managing.
Lists a summary of the searchable objects associated with the search category
you specify. Specify the ID number corresponding to the desired search
category.
Lists a summary of the searchable objects associated with the search engine
instance you specify. Specify the ID number corresponding to the desired search
engine instance.
Lists a summary of the searchable objects associated with the index schedule
you specify. Specify the ID number corresponding to the desired index schedule.
Lists the parameters that are available for the set param command for the
engine instance you are managing.
Lists the parameters that are available for the set param command for the
search engine instance you specify. Specify the ID number corresponding to the
desired search engine instance.
list schedules
Lists the index schedules associated with the search engine instance you are
managing.
Lists the index schedules associated with the search engine instance you specify.
Specify the ID number corresponding to the desired search engine instance.
Lists the unassigned searchable objects (not associated with a search engine
instance) and their corresponding ID numbers.
manage instance
Sets the context to the specified search engine instance. The ECSF Command
Line Administration Utility lists all the search engine instances and their
corresponding ID numbers and prompt you for the ID number of the search
engine instance you want to manage.
manage instance ID
Sets the context to the search engine instance you specify. Specify the ID number
corresponding to the search engine instance you want to manage.
B-7
Description
register idplugin
Registers an identity plug-in for the instance you are managing. The
deployment of the Federated Trust Entity occurs when the identity plug-in is
registered.
Registers an identity plug-in for the search engine instance you specify. Specify
the ID number corresponding to the desired search engine instance. The
deployment of the Federated Trust Entity occurs when the identity plug-in is
registered.
register object
Associates the specified searchable object with the search engine instance you
are managing and creates a new record for the searchable object in the ECSF
schema of the Oracle Fusion Applications database. Follow the prompts to enter
field values. For BO Name, you must enter a fully qualified view object name
defined in your application.
Associates the specified searchable object with the search engine instance you
are managing and creates a new record for the searchable object in the Oracle
Fusion Applications database. Directly pass in field name-value pairs with the
command.
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
Disassociates a searchable object from the search category you specify. Specify
the ID number corresponding to the search category from which you want to
disassociate the searchable object. The ECSF Command Line Administration
Utility displays a list of searchable objects and prompts you to enter the ID
corresponding to the searchable object you want to remove from the search
category.
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
You must issue the command while managing the search engine instance with
which the search category is associated. The searchable object is still available
for association to other search categories.
remove object ID from
category ID
Disassociates the specified searchable object from the search category you
specify. Specify the ID number corresponding to the searchable object you want
to remove from the search category. Specify the ID number corresponding to the
search category from which you want to disassociate the searchable object.
You must issue the command while managing the search engine instance with
which the search category is associated. The searchable object is still available
for association to other search categories.
Disassociates a searchable object from the specified search engine instance and
makes it available for association to another search engine instance. The ECSF
Command Line Administration Utility displays a list of searchable objects and
prompts you to enter the ID corresponding to the searchable object you want to
remove from the search engine instance.
To disassociate a searchable object from a search engine instance, both the object
and the instance must be undeployed.
Description
Disassociates a searchable object from the specified search engine instance and
makes it available for association to another search engine instance. Specify the
ID number corresponding to the search engine instance from which you want to
remove the searchable object. The ECSF Command Line Administration Utility
displays a list of searchable objects and prompts you to enter the ID
corresponding to the searchable object you want to remove from the search
engine instance.
To disassociate a searchable object from a search engine instance, both the object
and the instance must be undeployed.
Disassociates the specified searchable object from the search engine instance and
makes it available for association to another search engine instance. Specify the
ID number corresponding to the searchable object you want to remove.
To disassociate a searchable object from a search engine instance, both the object
and the instance must be undeployed.
Disassociates the searchable object from the search engine instance and makes it
available for association to another search engine instance. Specify the ID
number corresponding to the searchable object you want to remove and the ID
number corresponding to the search engine instance from which you want to
remove the searchable object.
To disassociate a searchable object from a search engine instance, both the object
and the instance must be undeployed.
Disassociates a searchable object from the specified index schedule and makes it
available to be added to another index schedule. Specify the ID number
corresponding to the index schedule from which you want to disassociate the
searchable object. The ECSF Command Line Administration Utility displays a
list of searchable objects and prompts you to enter the ID corresponding to the
searchable object you want to remove from the index schedule.
To disassociate a searchable object from an index schedule, the index schedule
must not be deployed. You must issue the command while managing the search
engine instance with which the index schedule is associated.
Disassociates the searchable object you specify from the specified index
schedule and makes it available to be added to another index schedule. Specify
the ID number corresponding to the searchable object you want to disassociate
and the ID number corresponding to the index schedule from which you want
to disassociate the searchable object.
To disassociate a searchable object from an index schedule, the index schedule
must not be deployed. You must issue the command while managing the search
engine instance with which the index schedule is associated.
set param
"paramname"="value"
Sets parameter values for the search engine instance. Use the following
command syntax to directly pass in one parameter name-value pair at a time:
See the "Managing Search with Oracle Enterprise Crawl and Search Framework"
chapter in the Oracle Fusion Applications Administrator's Guide for a list of known
engine instance parameters.
The parameter name and value must be enclosed in quotes. If the parameter
name or value contains a quote, escape it with a backslash, for example, "value
with \"escaped\" quotes".
You must issue the command while managing the search engine instance whose
password parameters you want to set.
B-9
Description
Sets password parameter values for the search engine instance. Pass in one
password parameter and its password.
See the "Managing Search with Oracle Enterprise Crawl and Search Framework"
chapter in the Oracle Fusion Applications Administrator's Guide for a list of known
engine instance parameters.
The password parameter name must be enclosed in quotes. If the parameter
parameter name contains a quote, escape it with a backslash, for example,
"value with \"escaped\" quotes".
You must issue the command while managing the search engine instance whose
password parameters you want to set.
Lists detailed information about the specified search category and the
searchable objects associated with it.
Lists the detailed information about the specified unassigned searchable object.
showdetails
Lists the detailed information for the search engine instance being managed.
You must issue the command while managing a search engine instance.
Lists the detailed information about the specified search engine instance.
Lists the detailed information about the specified search engine instance
parameter.
Lists detailed information about the specified index schedule and the searchable
objects associated with it.
start schedule ID
Launches the index schedule you specify and causes Oracle SES to create the
full-text search indexes. Specify the ID corresponding to the index schedule you
want to start.
Index schedules must be deployed to the search engine instance before you can
start it. You must issue the command while managing the search engine instance
with which the index schedule is associated.
stop schedule ID
Stops the specified index schedule that has been started and aborts the index
process. Specify the ID number of the index schedule you want to stop. You
must issue the command while managing the search engine instance with which
the index schedule is associated.
undeploy category ID
Removes a search category from the search engine instance. Specify the ID
number corresponding to the search category you want to undeploy.
You must issue the command while managing the search engine instance with
which the search category is associated.
undeploy object ID
Removes a searchable object from the search engine instance to make the object
unavailable for the search engine instance to crawl. Specify the ID number
corresponding to the searchable object you want to undeploy.
Only deployed and deactivated searchable objects can be undeployed.
undeploy schedule ID
Removes the specified index schedule from the search engine instance. Specify
the ID number corresponding to the index schedule you want to undeploy. You
must issue the command while managing the search engine instance with which
the index schedule is associated.
unmanage
unmanage instance
Description
update category ID
Modifies the properties of the specified search category. Specify the ID number
corresponding to the search category you want to modify. Follow the prompts to
enter field values.
Set the scope of the search category to GLOBAL to allow the search categories to
be queried.
You must issue the command while managing the search engine instance with
which the search category is associated.
Modifies the properties of the specified search category. Use the following
command syntax to directly pass in field name-value pairs with the command:
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
Set the scope of the search category to GLOBAL to allow the search categories to
be queried.
You must issue the command while managing the search engine instance with
which the search category is associated.
Modifies the application identity of the specified external search category. Use
the following command syntax to directly pass in a field name-value pair with
the command:
The field name and value must be enclosed in quotes. If the field name or value
contains a quote, escape it with a backslash, for example, "field name with
\"escaped\" quotes".
Set the scope of the search category to GLOBAL to allow the search categories to
be queried.
You must issue the command while managing the search engine instance with
which the external search category is associated.
update instance
Modifies the properties of the search engine instance you are currently
managing. If you are not currently managing a search engine instance, the ECSF
Command Line Administration Utility lists all the search engine instances and
their corresponding ID numbers and prompt you for the ID number of the
search engine instance you want to modify. Follow the prompts to enter field
values.
update instance ID
Modifies the properties of the search engine instance you specify. Specify the ID
number corresponding to the search engine instance you want to modify. Follow
the prompts to enter field values.
Modifies the properties of the search engine instance you are currently
managing. Directly pass in field name-value pairs with the command.
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
B-11
Description
Modifies the properties of the search engine instance you specify. Specify the ID
number corresponding to the search engine instance you want to modify and
directly pass in field name-value pairs with the command.
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
update object ID
update schedule ID
Modifies the properties of the index schedule you specify. Specify the ID
number corresponding to the index schedule you want to modify. Follow the
prompts to enter new field values.
Modifies the properties of the index schedule you specify. Specify the ID
number corresponding to the index schedule you want to modify and directly
pass in field name-value pairs with the command.
The field names and values must be enclosed in quotes. If the field name or
value contains a quote, escape it with a backslash, for example, "field name
with \"escaped\" quotes".
You must issue the command while managing the search engine instance with
which the index schedule is associated.
Glossary
all-segment secondary usage
A type of secondary usage in which the secondary table has all of the key flexfield
segment columns that are present in the combinations table.
application role
A role specific to applications and stored in the policy store.
business component
One of a set of cooperating components that are used by ADF Business Components to
implement a business service.
business object
A resource in an enterprise database, such as an invoice or purchase order.
CCID
Code combination ID, the common attribute for key flexfields. Every key flexfield
combinations table must have a CCID column, the values of which identify each data
row.
child view object
A view object that is nested within a master view object.
code combination ID (CCID)
See CCID.
code-combination reference page
Pages whose underlying entity objects contain a foreign key reference to the
combinations table.
combination maintenance page
A page whose underlying entity objects use the combinations table itself.
consumer (of a flexfield)
The person who incorporates a flexfield into their application, which is typically
different from the producer's application. The consumer typically stores the CCID on a
transaction table, and works with the structural and seed data and the business
components that have been configured by the key flexfield producer.
Glossary-1
context
context
A group of attributes. Each context is part of a flexfield, and is comprised of a set of
context-sensitive segments that store a particular type of related information.
context attribute
The flexfield base view object attribute that contains the context discriminator value.
context-sensitive segment
A flexfield segment that is a member of a context.
custom validation callout
Callout procedure that is used to enforce custom validation logic for new code
combinations beyond what has been defined for cross-validation rules.
customer flexfield
A flexfield created for use by the customer.
cross-validation rule
A rule that is composed of a condition filter and a validation filter and that specifies
when and how to validate a key flexfield code combination.
data security
The control of access to data. Data security controls what action a user can take against
which data.
database schema
A named collection of objects, such as tables, views, clusters, procedures, packages,
attributes, object classes, and their corresponding matching rules, which are associated
with a particular user.
derived segment
A segment whose values automatically change to reflect new reference values.
descriptive flexfield
A type of flexfield used to give additional attributes to a data model. Allows
customers to add custom attributes to entities, to define how the attributes are
validated, and display properties for the attributes. These attributes do not necessarily
have anything to do with each other and are not treated together as a combination. A
descriptive flexfield can only support a set amount of segments.
developer (of a flexfield)
The role to be used if you are incorporating the flexfield into an application.
developer flexfield
A flexfield created to support functionality that has been built into the application.
discriminator
A common attribute amongst multiple view rows. The discriminator determines
which view row type should be used.
Glossary-2
function security
dynamic column
A method of accessing a flexfield in Excel. Using a dynamic column will enable you to
pick flexfield segment values. You can also enter values directly into the segment
fields.
dynamic combination insertion
The act of end users entering values on an application page that constitute new code
combinations (even if the end users are not authorized to perform maintenance tasks
directly).
EAR
An Enterprise Archive file. A Java EE archive file that is used in deploying
applications on a Java EE application server. Framework applications are deployed
using both a generic EAR file, which contains the application and the respective
runtime customization, and a targeted EAR file, which contains only the application
for deployment to the application server.
Enterprise Archive (EAR)
See EAR.
entitlement
Grants of access to functions and data. Oracle Fusion Middleware term for privilege.
entity object
An object that represents a row in a database table and that simplifies modifying its
data by handling all data manipulation language operations for you. Entity objects are
ADF Business Components that provide the mapping to underlying data structures.
extensible flexfield
A type of flexfield that is similar to a descriptive flexfield, but does not have a fixed
number of segments, allows attributes to be grouped, allows entities to inherit
segments from their parents, and supports one-to-many relationships between entity
and extended attribute rows.
flexfield
An "expandable" data field that is divided into segments. Flexfields enable you to
configure your applications to meet your business needs without having to perform
custom development.
flexfield parameter
A declared public variable which can be used to designate which attributes of eligible
entity objects that are related to the flexfield can be used to pass external reference
data to flexfield segments. These entity objects could, in turn, take their values from
column values, constant values, session attributes, and so forth.
form layout
A typical label/prompt and either view-only data or widget (text field, choice list, and
so on) that allows a user to enter values.
function security
The control of access to a page or a specific widget or functionality within a page.
Function security controls what a user can do.
Glossary-3
global
global
The type of segment label that is used if you want the implementer to tie it to all
segments.
global segment
A segment of custom attributes that apply to all entity rows.
hierarchical categories
A feature of extensible flexfields. Extensible flexfields can be configured to enable
categories, which can be used to dynamically display different sets of logical pages
and contexts based upon a runtime differentiator. The categories can be structured in a
hierarchical manner and the children categories inherit all the contexts and logical
pages that are configured for the parent categories.
implementor (of a flexfield)
An individual who sets up all or part of a flexfield-enabled application for
deployment. Implementors typically work for or on behalf of customers to install,
configure, or administer their applications. In the case of developer flexfields that have
been created to support functionality that has been built into the application, the
developer also plays the role of implementor.
intelligent key
A key composed of business-related values as opposed to an arbitrarily generated
sequence.
key flexfield
A type of flexfield in which the segments define a key, or code, that uniquely
identifies an object such as an account, an asset, a part, or a job.
maintenance mode
A mode of the key flexfield user interface which allows you to use a code
combination maintenance page to manage key flexfield code combinations, including
the ability to enter new code combinations and update existing code combinations for
a flexfield.
MAR
A Metadata Archive file. A compressed archive of selected metadata used to deploy
metadata content to the MDS Repository.
master view object
A view object that has other view objects nested within it.
Metadata Archive (MAR)
See MAR.
owner (of a flexfield)
The developer (or development team) who determines that a particular flexfield is
needed or would be useful within a particular Oracle Fusion application, and makes a
flexfield of the appropriate design available.
primary key attribute
The attribute of a base view object which links the flexfield view object to the
application view object.
Glossary-4
segment label
primary table
The application table that was used to first register the flexfield. It is the owner of the
flexfield.
privilege
A grant or entitlement of access to functions and data.
producer (of a flexfield)
The developer who determines that a particular flexfield is needed or would be useful
within a particular application, and makes available a flexfield of the appropriate
design. With key flexfields, the producer's product owns the combinations table for
that flexfield.
readonly
A boolean property that indicates whether users can modify the value.
rendered
A boolean property that indicates whether the value is visible on the application page.
required
A boolean property that indicates whether the field must have a value.
required (segment label)
The type of segment label that is used if you want the implementors to tie it at least to
one segment.
role
Controls access to application functions and data.
secondary table
For descriptive flexfields, a table, other than the primary table, that contains the same
set of extension columns as the primary table and that enables the primary table's
descriptive flexfield to be reused for that table. For key flexfields, a product table
other than the combinations table that contains one or all of the key flexfield
segments.
secondary usage
For descriptive flexfields, the reuse of a flexfield on a table other than the primary
table.
For key flexfields, a type of usage in which there is no direct relationship between the
product table and the combinations table.
See also single-segment secondary usage and all-segment secondary usage.
security reference implementation
Predefined function and data security in Oracle Fusion Applications, including role
based access control, and policies that protect functions, data, and segregation of
duties. The reference implementation supports identity management, access
provisioning, and security enforcement across the tools, data transformations, access
methods, and the information life cycle of an enterprise.
segment label
A label which identifies the purpose of a particular segment in a key flexfield.
Glossary-5
SIN
SIN
Structure instance number. A segment that acts as the discriminator attribute for key
flexfields.
single-segment secondary usage
A type of secondary usage in which the secondary table has only one key flexfield
segment column.
static column
A method of accessing a flexfield in Excel. Used when the flexfield is exposed in an
ADF Table component, is context sensitive, and the context changes from row to row.
A static column should also be used if you do not want flexfield segments to occupy
too much space in the worksheet.
structure code
A string you provide that individually identifies a structure.
Structure instance number (SIN)
See SIN.
tester (of a flexfield)
The role to be used if you are planning to test or share your flexfield.
transient attribute
An attribute whose value is not stored in a database, and therefore holds a value only
for the life of the object. Transient attributes are typically used to display values that
are calculated (for example, using Java or Groovy).
unique
The type of segment label that is used if you want the implementer to tie it to at most
one segment of the flexfield.
value set
A list of valid values used to specify the validation rules for a flexfield segment.
view accessor
An ADF Business Components object that points from an entity object attribute (or
view object) to a destination view object or shared view instance in the same
application workspace. The view accessor returns a row set that by default contains all
the rows from the destination view object.
WAR
A Web Application Archive file. This file is used in deploying applications on a Java
EE application server. WAR files encapsulate in a single module all of the components
necessary to run an application. WAR files typically contain an application's servlet,
JSP, and JSF JSP components.
Web Application Archive (WAR)
See WAR.
Glossary-6